Request refund of received payment (Refund-In)
POST /api/pix/refund-in/{id}
POST https://<api-host>/api/pix/refund-in/{id}Requires a Bearer token in the Authorization header. See Generate Token to obtain one.
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.
Authentication
Requires a Bearer token in the Authorization header.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | ID of the original transaction to be refunded |
Request Body
| 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 (max 140 characters) |
externalId | string | No | External ID of the refund (unique per account, max 100 characters). In the BACEN API, this corresponds to the id URL parameter |
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}Code Examples
curl -X POST "https://<api-host>/api/pix/refund-in/12345" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/refund-in/12345',
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);Response (201)
| 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"
}Errors
| Status | Description |
|---|---|
| 400 | Invalid data, transaction not found, deadline exceeded, or invalid amount |
| 401 | Missing or invalid token |
| 404 | Parent transaction not found |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — refund externalId already used on this account |
| 500 | Error processing refund request |