接口端点
申请退款
概述
PUT /pix/:e2eid/devolucao/:id 接口端点用于申请退还已收到的 PIX。它使用原始交易的端到端 ID（e2eid）和由客户端生成的退款标识符。
退款可以是全额或部分退款。所有退款金额之和不得超过原始交易金额。
接口端点
PUT /pix/{e2eid}/devolucao/{id}身份认证
通过 /oauth/token 获取的 Bearer 令牌。
URL 参数
e2eidstringobrigatorio端到端 ID - 原始 PIX 交易的唯一标识符。恰好包含 32 个字母数字字符。
示例：E12345678901234567890123456789012
idstringobrigatorio客户端生成的退款标识。长度在 1 到 35 个字符之间。
示例：D123456789
请求体
申请退款的金额。带 2 位小数的十进制格式字符串。
所有退款金额之和不得超过原始 PIX 的总金额。
示例："7.89"
退款性质：
ORIGINAL：标准 PIX 退款或 PIX 找零中的购买金额退款RETIRADA：PIX 取款或 PIX 找零中的找零金额退款
向付款人展示的退款说明文本。
最长：140 个字符。
请求
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()响应
{
"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"
}响应字段
idstring客户端生成的退款标识（与 URL 中发送的值相同）。
rtrIdstring退款交易的唯一标识符。包含 32 个字符。
valorstring退款金额，带 2 位小数的字符串格式。
naturezastring退款性质：
ORIGINAL：标准退款RETIRADA：取款退款MED_OPERACIONAL：因操作故障的 MED 退款MED_FRAUDE：因涉嫌欺诈的 MED 退款
descriçãostring向付款人显示的退款说明。
horarioobjectstatusstring退款状态：
EM_PROCESSAMENTO：退款正在处理中DEVOLVIDO：退款成功完成NAO_REALIZADO：退款未完成（失败）
motivostring可选字段，包含当前状态的原因说明。主要在失败情况下填充。
退款状态
stateDiagram-v2
[*] --> EM_PROCESSAMENTO: Request sent
EM_PROCESSAMENTO --> DEVOLVIDO: Success
EM_PROCESSAMENTO --> NAO_REALIZADO: Failure
DEVOLVIDO --> [*]
NAO_REALIZADO --> [*]退款 Webhook
当退款处理完成时，您将收到一个类型为 REFUND 的 V2 Webhook：
{
"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
查看完整的 REFUND Webhook 文档
退款性质
| 性质 | 描述 |
|---|---|
ORIGINAL | 标准 PIX 退款 |
RETIRADA | PIX 取款或找零退款 |
MED_OPERACIONAL | 因操作故障的 MED |
MED_FRAUDE | 因涉嫌欺诈的 MED |
MED_OPERACIONAL 和 MED_FRAUDE 仅在响应中返回，不能在请求中发送。它们用于特殊退款机制（MED）的特定情况。
退款期限
根据中央银行规定，退款可在收到原始 PIX 后 89 天内申请。
部分退款
您可以申请多次部分退款：
// 原始交易：R$ 100.00
// 第一次退款：R$ 30.00
await requestRefund(e2eid, 'DEV001', '30.00');
// 可退款余额：R$ 70.00
// 第二次退款：R$ 50.00
await requestRefund(e2eid, 'DEV002', '50.00');
// 可退款余额：R$ 20.00
// 第三次退款：R$ 25.00 - 错误！
await requestRefund(e2eid, 'DEV003', '25.00');
// 失败：金额超过可用余额（R$ 20.00）常见错误
| 状态码 | 错误 | 解决方案 |
|---|---|---|
| 400 | 金额无效 | 使用格式 "7.89"（带 2 位小数的字符串） |
| 400 | 金额超过可用额度 | 检查可退款余额 |
| 404 | 未找到交易 | 验证提供的 e2eid |
| 404 | 交易非收款类型 | 退款仅适用于已收到的 PIX |
| 422 | 退款期限已过 | 退款仅限收款后 89 天内 |