Request Refund
Overview
The PUT /pix/:e2eid/devolucao/:id endpoint requests the refund of a received PIX. It uses the End to End ID (e2eid) of the original transaction and a refund identifier generated by the client.
Refunds can be full or partial. The sum of all refunds cannot exceed the original transaction amount.
Endpoint
PUT /pix/{e2eid}/devolucao/{id}Authentication
Bearer token obtained via /oauth/token.
URL Parameters
e2eidstringobrigatorioEnd to End ID - unique identifier of the original PIX transaction. Contains exactly 32 alphanumeric characters.
Example: E12345678901234567890123456789012
idstringobrigatorioClient-generated identification to represent the refund. Between 1 and 35 characters.
Example: D123456789
Request Body
Amount requested for refund. String in decimal format with 2 decimal places.
The sum of all refund amounts cannot exceed the total amount of the original PIX.
Example: "7.89"
Indicates the nature of the requested refund:
ORIGINAL: Refund of a standard PIX or purchase amount in PIX ChangeRETIRADA: Refund of PIX Withdrawal or change amount in PIX Change
Text to be shown to the payer containing information about the refund.
Maximum: 140 characters.
Request
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",
"descrição": "Devolução 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',
descrição: 'Devolução solicitada pelo recebedor',
}),
}
);
const devolução = 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',
'descrição': 'Devolução solicitada pelo recebedor',
}
)
devolução = response.json()Response
{
"id": "D123456789",
"rtrId": "D12345678901234567890123456789012",
"valor": "7.89",
"natureza": "ORIGINAL",
"descrição": "Devolução solicitada pelo recebedor",
"horario": {
"solicitação": "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": "Transação original não encontrada",
"error": "Not Found"
}Response Fields
idstringClient-generated identification representing the refund (same value sent in the URL).
rtrIdstringUnique identifier of the refund transaction. Contains 32 characters.
valorstringRefund amount in string format with 2 decimal places.
naturezastringRefund nature:
ORIGINAL: Standard refundRETIRADA: Withdrawal refundMED_OPERACIONAL: MED refund due to operational failureMED_FRAUDE: MED refund due to fraud suspicion
descriçãostringMessage to the payer regarding the refund.
horarioobjectstatusstringRefund status:
EM_PROCESSAMENTO: Refund is being processedDEVOLVIDO: Refund completed successfullyNAO_REALIZADO: Refund not completed (failure)
motivostringOptional field with details about the reason for the current status. Primarily populated in case of failure.
Refund Status
stateDiagram-v2
[*] --> EM_PROCESSAMENTO: Request sent
EM_PROCESSAMENTO --> DEVOLVIDO: Success
EM_PROCESSAMENTO --> NAO_REALIZADO: Failure
DEVOLVIDO --> [*]
NAO_REALIZADO --> [*]Refund Webhook
When the refund is processed, you will receive a V2 webhook of type 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": "Devolução solicitada pelo recebedor"
}
],
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT"
}
}REFUND Webhooks
See the full REFUND webhook documentation
Refund Nature
| Nature | Description |
|---|---|
ORIGINAL | Standard PIX refund |
RETIRADA | PIX Withdrawal or Change refund |
MED_OPERACIONAL | MED due to operational failure |
MED_FRAUDE | MED due to fraud suspicion |
The values MED_OPERACIONAL and MED_FRAUDE are only returned in the response and cannot be sent in the request. They are used in specific cases of the Special Refund Mechanism (MED).
Refund Deadline
Refunds can be requested up to 89 days after receiving the original PIX, as per Central Bank regulations.
Partial Refunds
You can request multiple partial refunds:
// Original transaction: R$ 100.00
// First refund: R$ 30.00
await requestRefund(e2eid, 'DEV001', '30.00');
// Available balance for refund: R$ 70.00
// Second refund: R$ 50.00
await requestRefund(e2eid, 'DEV002', '50.00');
// Available balance for refund: R$ 20.00
// Third refund: R$ 25.00 - ERROR!
await requestRefund(e2eid, 'DEV003', '25.00');
// Failure: amount exceeds available balance (R$ 20.00)Common Errors
| Code | Error | Solution |
|---|---|---|
| 400 | Invalid value | Use the format "7.89" (string with 2 decimals) |
| 400 | Value exceeds available | Check the available balance for refund |
| 404 | Transaction not found | Verify the e2eid provided |
| 404 | Transaction is not a receipt | Refunds are only for received PIX |
| 422 | Deadline expired | Refunds only up to 89 days after receipt |