Solicitar Devolução
Visão Geral
O endpoint PUT /pix/:e2eid/devolucao/:id solicita a devolução de um PIX recebido. Utiliza o End to End ID (e2eid) da transação original e um identificador de devolução gerado pelo cliente.
A devolução pode ser total ou parcial. A soma de todas as devoluções não pode ultrapassar o valor original da transação.
Endpoint
PUT /pix/{e2eid}/devolucao/{id}Autenticação
Token Bearer obtido via /oauth/token.
Parâmetros de URL
e2eidstringobrigatorioEnd to End ID - identificador único da transação PIX original. Contém exatamente 32 caracteres alfanuméricos.
Exemplo: E12345678901234567890123456789012
idstringobrigatorioIdentificação gerada pelo cliente para representar a devolução. Entre 1 e 35 caracteres.
Exemplo: D123456789
Request Body
Valor solicitado para devolução. String no formato decimal com 2 casas.
A soma dos valores de todas as devoluções não pode ultrapassar o valor total do PIX original.
Exemplo: "7.89"
Indica a natureza da devolução solicitada:
ORIGINAL: Devolução de PIX comum ou valor da compra em PIX TrocoRETIRADA: Devolução de PIX Saque ou valor do troco em PIX Troco
Texto a ser apresentado ao pagador contendo informações sobre a devolução.
Máximo: 140 caracteres.
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"
}Campos da Resposta
idstringIdentificação gerada pelo cliente para representar a devolução (mesmo valor enviado na URL).
rtrIdstringIdentificador único da transação de devolução. Contém 32 caracteres.
valorstringValor da devolução no formato string com 2 casas decimais.
naturezastringNatureza da devolução:
ORIGINAL: Devolução comumRETIRADA: Devolução de saqueMED_OPERACIONAL: Devolução MED por falha operacionalMED_FRAUDE: Devolução MED por suspeita de fraude
descriçãostringMensagem ao pagador relativa a devolução.
horarioobjectstatusstringStatus da devolução:
EM_PROCESSAMENTO: Devolução em processamentoDEVOLVIDO: Devolução realizada com sucessoNAO_REALIZADO: Devolução não realizada (falha)
motivostringCampo opcional com detalhes sobre o motivo do status atual. Preenchido principalmente em caso de falha.
Status da Devolução
stateDiagram-v2
[*] --> EM_PROCESSAMENTO: Solicitação enviada
EM_PROCESSAMENTO --> DEVOLVIDO: Sucesso
EM_PROCESSAMENTO --> NAO_REALIZADO: Falha
DEVOLVIDO --> [*]
NAO_REALIZADO --> [*]Webhook de Devolução
Quando a devolução for processada, você receberá um webhook V2 do 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": "Devolução solicitada pelo recebedor"
}
],
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT"
}
}Webhooks REFUND
Veja a documentação completa do webhook REFUND
Natureza da Devolução
| Natureza | Descrição |
|---|---|
ORIGINAL | Devolução de PIX comum |
RETIRADA | Devolução de PIX Saque ou Troco |
MED_OPERACIONAL | MED por falha operacional |
MED_FRAUDE | MED por suspeita de fraude |
Os valores MED_OPERACIONAL e MED_FRAUDE são retornados apenas na resposta, não podem ser enviados na requisição. São utilizados em casos específicos de Mecanismo Especial de Devolução (MED).
Prazo para Devolução
Devoluções podem ser solicitadas em até 89 dias após o recebimento do PIX original, conforme regulamentação do Banco Central.
Devoluções Parciais
Você pode solicitar múltiplas devoluções parciais:
// Transação original: R$ 100,00
// Primeira devolução: R$ 30,00
await solicitarDevolução(e2eid, 'DEV001', '30.00');
// Saldo disponível para devolução: R$ 70,00
// Segunda devolução: R$ 50,00
await solicitarDevolução(e2eid, 'DEV002', '50.00');
// Saldo disponível para devolução: R$ 20,00
// Terceira devolução: R$ 25,00 - ERRO!
await solicitarDevolução(e2eid, 'DEV003', '25.00');
// Falha: valor excede saldo disponível (R$ 20,00)Erros Comuns
| Código | Erro | Solução |
|---|---|---|
| 400 | Valor inválido | Use formato "7.89" (string com 2 decimais) |
| 400 | Valor excede disponível | Verifique saldo disponível para devolução |
| 404 | Transação não encontrada | Verifique o e2eid informado |
| 404 | Transação não e do tipo recebimento | Devoluções so para PIX recebidos |
| 422 | Prazo expirado | Devoluções so até 89 dias após recebimento |