Solicitar Devolución
Descripción general
El endpoint PUT /pix/:e2eid/devolucao/:id solicita la devolución de un PIX recibido. Utiliza el End to End ID (e2eid) de la transacción original y un identificador de devolución generado por el cliente.
Las devoluciones pueden ser totales o parciales. La suma de todas las devoluciones no puede exceder el monto de la transacción original.
Endpoint
PUT /pix/{e2eid}/devolucao/{id}Autenticación
Token Bearer obtenido via /oauth/token.
Parámetros de URL
e2eidstringobrigatorioEnd to End ID - identificador único de la transacción PIX original. Contiene exactamente 32 caracteres alfanumericos.
Ejemplo: E12345678901234567890123456789012
idstringobrigatorioIdentificacion generada por el cliente para representar la devolución. Entre 1 y 35 caracteres.
Ejemplo: D123456789
Cuerpo de la Solicitud
Monto solicitado para la devolución. String en formato decimal con 2 decimales.
La suma de todos los montos de devolución no puede exceder el monto total del PIX original.
Ejemplo: "7.89"
Indica la naturaleza de la devolución solicitada:
ORIGINAL: Devolución de un PIX estandar o monto de compra en PIX TrocoRETIRADA: Devolución de PIX Saque o monto de cambio en PIX Troco
Texto que se mostrara al pagador con información sobre la devolución.
Máximo: 140 caracteres.
Solicitud
curl -X PUT https://api.ntxpay.com/pix/E12345678901234567890123456789012/devolucao/D123456789 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"valor": "7.89",
"natureza": "ORIGINAL",
"descricao": "Devolucao solicitada pelo recebedor"
}'const e2eid = 'E12345678901234567890123456789012';
const devolucaoId = 'D123456789';
const response = await fetch(
`https://api.ntxpay.com/pix/${e2eid}/devolucao/${devolucaoId}`,
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
valor: '7.89',
natureza: 'ORIGINAL',
descricao: 'Devolucao solicitada pelo recebedor',
}),
}
);
const devolucao = await response.json();import requests
e2eid = 'E12345678901234567890123456789012'
devolucao_id = 'D123456789'
response = requests.put(
f'https://api.ntxpay.com/pix/{e2eid}/devolucao/{devolucao_id}',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
},
json={
'valor': '7.89',
'natureza': 'ORIGINAL',
'descricao': 'Devolucao solicitada pelo recebedor',
}
)
devolucao = response.json()Respuesta
{
"id": "D123456789",
"rtrId": "D12345678901234567890123456789012",
"valor": "7.89",
"natureza": "ORIGINAL",
"descricao": "Devolucao solicitada pelo recebedor",
"horario": {
"solicitacao": "2024-01-15T10:30:00.000Z"
},
"status": "EM_PROCESSAMENTO"
}{
"statusCode": 400,
"message": "Valor deve estar no formato decimal com 2 casas (ex: 7.89)",
"error": "Bad Request"
}{
"statusCode": 404,
"message": "Transacao original nao encontrada",
"error": "Not Found"
}Campos de Respuesta
idstringIdentificacion generada por el cliente que representa la devolución (mismo valor enviado en la URL).
rtrIdstringIdentificador único de la transacción de devolución. Contiene 32 caracteres.
valorstringMonto de la devolución en formato string con 2 decimales.
naturezastringNaturaleza de la devolución:
ORIGINAL: Devolución estandarRETIRADA: Devolución de saqueMED_OPERACIONAL: Devolución MED por falla operacionalMED_FRAUDE: Devolución MED por sospecha de fraude
descricaostringMensaje al pagador sobre la devolución.
horarioobjectstatusstringEstado de la devolución:
EM_PROCESSAMENTO: Devolución en procesamientoDEVOLVIDO: Devolución completada exitosamenteNAO_REALIZADO: Devolución no completada (fallo)
motivostringCampo opcional con detalles sobre el motivo del estado actual. Principalmente se llena en caso de fallo.
Estado de la Devolución
stateDiagram-v2
[*] --> EM_PROCESSAMENTO: Solicitud enviada
EM_PROCESSAMENTO --> DEVOLVIDO: Exito
EM_PROCESSAMENTO --> NAO_REALIZADO: Fallo
DEVOLVIDO --> [*]
NAO_REALIZADO --> [*]Webhook de Devolución
Cuando la devolución es procesada, recibira un webhook V2 de tipo REFUND:
{
"type": "REFUND",
"data": {
"id": 123,
"txId": "original-txid",
"status": "REFUNDED",
"payment": {
"amount": "100.00",
"currency": "BRL"
},
"refunds": [
{
"status": "LIQUIDATED",
"payment": {
"amount": 7.89,
"currency": "BRL"
},
"endToEndId": "D12345678901234567890123456789012",
"eventDate": "2024-01-15T10:30:00.000Z",
"information": "Devolucao solicitada pelo recebedor"
}
],
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT"
}
}Webhooks REFUND
Vea la documentación completa del webhook REFUND
Naturaleza de la Devolución
| Naturaleza | Descripción |
|---|---|
ORIGINAL | Devolución estandar de PIX |
RETIRADA | Devolución de PIX Saque o Troco |
MED_OPERACIONAL | MED por falla operacional |
MED_FRAUDE | MED por sospecha de fraude |
Los valores MED_OPERACIONAL y MED_FRAUDE solo se retornan en la respuesta y no pueden enviarse en la solicitud. Se utilizan en casos especificos del Mecanismo Especial de Devolución (MED).
Plazo de Devolución
Las devoluciones pueden solicitarse hasta 89 días después de recibir el PIX original, según las regulaciones del Banco Central.
Devoluciones Parciales
Puede solicitar multiples devoluciones parciales:
// Transacción original: R$ 100.00
// Primera devolución: R$ 30.00
await requestRefund(e2eid, 'DEV001', '30.00');
// Saldo disponible para devolución: R$ 70.00
// Segunda devolución: R$ 50.00
await requestRefund(e2eid, 'DEV002', '50.00');
// Saldo disponible para devolución: R$ 20.00
// Tercera devolución: R$ 25.00 - ERROR!
await requestRefund(e2eid, 'DEV003', '25.00');
// Fallo: monto excede el saldo disponible (R$ 20.00)Errores Comunes
| Código | Error | Solución |
|---|---|---|
| 400 | Valor invalido | Use el formato "7.89" (string con 2 decimales) |
| 400 | Valor excede el disponible | Verifique el saldo disponible para devolución |
| 404 | Transacción no encontrada | Verifique el e2eid proporcionado |
| 404 | Transacción no es una recepción | Las devoluciones solo aplican para PIX recibidos |
| 422 | Plazo expirado | Devoluciones solo hasta 89 días después de la recepción |