Visão Geral
O evento CashOutReversal é enviado quando você recebe uma devolução de um PIX que enviou anteriormente. Isso pode ocorrer quando:
- O recebedor devolve o valor voluntariamente
- Há um problema com a transação original (dados inválidos, conta encerrada, etc.)
- O banco destino rejeita a transação
O movementType para CashOutReversal é CREDIT, pois você está recebendo de volta dinheiro que havia saído da sua conta.
| Campo | Valor |
|---|
event | CashOutReversal |
movementType | CREDIT |
| Significado | Você recebeu de volta dinheiro que havia enviado |
Payload Completo
{
"event": "CashOutReversal",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "CREDIT",
"transactionId": "29db95cd-0bc9-4f0f-b1b2-722968d8b58d",
"externalId": null,
"endToEndId": "D18236120202512112009s0018351d9f",
"pixKey": "07646173380",
"feeAmount": 0.01,
"originalAmount": 0.08,
"finalAmount": 0.07,
"processingDate": "2025-12-11T20:09:27.786Z",
"errorCode": null,
"errorMessage": null,
"metadata": {
"refund": {
"value": 8,
"originalValue": 31000,
"referenceTransactionId": 917561
},
"provider": "hyperwallet",
"counterpart": {
"bankCode": "260",
"bankIspb": "18236120",
"bankName": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO"
},
"webhookEvent": "PixOutReversalExternal",
"originatedFrom": "WEBHOOK_DIRECT"
},
"parentTransaction": {
"transactionId": "4ac6204e-7c82-47a8-9aea-7fbb6fde72db",
"externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
"endToEndId": "E071368472025121120065P1T3N1CS1A",
"processingDate": "2025-12-11T20:06:12.117Z",
"wasTotalRefunded": false,
"remainingAmountForRefund": 0.22,
"metadata": {},
"counterpart": {
"name": "Ana Costa",
"document": "*.765.432-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": "260",
"accountBranch": null,
"accountNumber": null
}
}
}
}
Campos Específicos do CashOutReversal
O CashOutReversal inclui campos adicionais no metadata e o objeto parentTransaction.
Detalhes da devolução recebida.
Valor devolvido em centavos.Exemplo: 8 (R$ 0,08)
metadata.refund.originalValue
Valor original da transação em centavos.Exemplo: 31000 (R$ 310,00)
metadata.refund.referenceTransactionId
ID interno de referência da transação original no provedor.
parentTransaction
Dados da transação PIX Out original que foi devolvida.
parentTransaction.transactionId
UUID da transação PIX Out original.
parentTransaction.externalId
ID externo que você forneceu ao criar o PIX Out.
parentTransaction.wasTotalRefunded
Indica se o valor total foi devolvido.
true: Devolução totalfalse: Devolução parcial
parentTransaction.remainingAmountForRefund
Valor restante que ainda pode ser devolvido (em reais).
parentTransaction.counterpart
Dados do recebedor original que devolveu o PIX.
Diferença: CashInReversal vs CashOutReversal
| Aspecto | CashInReversal | CashOutReversal |
|---|
| Quem inicia | Você (via API Refund-In) | O recebedor ou o banco destino |
| Direção | Você → Pagador original | Recebedor → Você |
| movementType | DEBIT (saída) | CREDIT (entrada) |
| Quando ocorre | Você decide devolver | Você recebe de volta |
Casos de Uso
1. Devolução Recebida
async function handleCashOutReversal(payload) {
const { parentTransaction, metadata } = payload;
// Creditar o valor devolvido no saldo
await balanceService.credit({
amount: payload.finalAmount,
reference: payload.transactionId,
originalPaymentId: parentTransaction.transactionId
});
// Atualizar status do pagamento original
await paymentService.markAsRefunded({
paymentId: parentTransaction.externalId,
refundAmount: payload.originalAmount,
wasFullRefund: parentTransaction.wasTotalRefunded
});
// Notificar equipe financeira
await notificationService.sendRefundReceived({
originalAmount: metadata.refund.originalValue / 100,
refundAmount: metadata.refund.value / 100
});
}
2. Tratamento de Rejeição
async function handleCashOutReversal(payload) {
// Se o PIX foi devolvido, pode ser rejeição do banco
if (payload.metadata.originatedFrom === 'WEBHOOK_DIRECT') {
console.log('PIX rejeitado pelo banco destino');
await transferService.markAsFailed({
transferId: payload.parentTransaction.externalId,
reason: 'Devolvido pelo banco destino'
});
// Notificar usuário para verificar dados
await notificationService.sendTransferFailed();
}
}
Fluxo Típico
Próximos Passos
