Solicitar reembolso de pago recibido (Refund-In)
POST /api/pix/refund-in/{id}
POST https://<api-host>/api/pix/refund-in/{id}Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.
Solicita el reembolso de un pago PIX recibido. El reembolso puede ser parcial o total, siempre que esté dentro del plazo de 89 días.
Autenticación
Requiere un Bearer token en el header Authorization.
Parámetros de ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | ID de la transacción original a reembolsar |
Cuerpo de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
refundValue | number | Sí | Monto a reembolsar en BRL (puede ser parcial). Mínimo: 0.01 |
reason | string | No | Motivo del reembolso (máx 140 caracteres) |
externalId | string | No | ID externo del reembolso (único por cuenta, máx 100 caracteres). En la API de BACEN, corresponde al parámetro id de la URL |
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}Ejemplos de Código
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);Respuesta (201)
| Campo | Tipo | Descripción |
|---|---|---|
transactionId | string | ID de la transacción de reembolso generada |
externalId | string | ID externo de la transacción de reembolso |
status | string | Estado actual de la transacción de reembolso (PENDING, CONFIRMED, ERROR) |
refundValue | number | Monto del reembolso en BRL |
providerTransactionId | string | ID de transacción del proveedor (utilizado para correlación con webhooks) |
generateTime | string | Fecha/hora de generación de la transacción de reembolso (ISO 8601) |
{
"transactionId": "789",
"externalId": "D123456789",
"status": "PENDING",
"refundValue": 50.00,
"providerTransactionId": "7ef4fc3f-a187-495e-857c-e84d70612761",
"generateTime": "2024-01-15T10:30:00.000Z"
}Errores
| Estado | Descripción |
|---|---|
| 400 | Datos inválidos, transacción no encontrada, plazo excedido o monto inválido |
| 401 | Token faltante o inválido |
| 404 | Transacción original no encontrada |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — externalId del reembolso ya utilizado en esta cuenta |
| 500 | Error al procesar la solicitud de reembolso |