Request refund of received payment (Refund-In)
Requests a refund of a received PIX payment. The refund can be partial or full, as long as it is within the 89-day deadline.
Requires a Bearer token in the Authorization header.
| Parameter | Type | Required | Description |
|---|
id | string | Yes | ID of the original transaction to be refunded |
| Field | Type | Required | Description |
|---|
refundValue | number | Yes | Amount to be refunded in BRL (can be partial). Minimum: 0.01 |
reason | string | No | Reason for the refund |
externalId | string | No | External ID for identifying the refund. In the BACEN API, this corresponds to the id URL parameter |
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}
| Field | Type | Description |
|---|
transactionId | string | ID of the generated refund transaction |
externalId | string | External ID of the refund transaction |
status | string | Current refund transaction status (PENDING, CONFIRMED, ERROR) |
refundValue | number | Refund amount in BRL |
providerTransactionId | string | Provider transaction ID (used for correlation with webhooks) |
generateTime | string | Refund transaction generation date/time (ISO 8601) |
{
"transactionId": "789",
"externalId": "D123456789",
"status": "PENDING",
"refundValue": 50.00,
"providerTransactionId": "7ef4fc3f-a187-495e-857c-e84d70612761",
"generateTime": "2024-01-15T10:30:00.000Z"
}
| Status | Description |
|---|
| 400 | Invalid data, transaction not found, deadline exceeded, or invalid amount |
| 401 | Missing or invalid token |
| 404 | Parent transaction not found |
| 500 | Error processing refund request |
