Visão Geral
O evento CashInReversal é enviado quando você inicia um estorno de um PIX recebido anteriormente, devolvendo o valor ao pagador original. Este evento ocorre quando você chama a API de Refund-In.
O movementType para CashInReversal é DEBIT, pois você está devolvendo dinheiro que havia entrado na sua conta.
| Campo | Valor |
|---|
event | CashInReversal |
movementType | DEBIT |
| Significado | Você devolveu dinheiro que havia recebido |
Payload Completo
{
"event": "CashInReversal",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "678689ca-3e16-4f5e-a08f-09a984a97781",
"externalId": "refund-678689ca-3e16-4f5e-a08f-09a984a97781",
"endToEndId": "D07136847202512112011O5222ZRBI5A",
"pixKey": null,
"feeAmount": 0.01,
"originalAmount": 0.3,
"finalAmount": 0.31,
"processingDate": "2025-12-11T20:11:13.289Z",
"errorCode": null,
"errorMessage": null,
"metadata": {},
"parentTransaction": {
"transactionId": "6d94e3ce-5a10-4fbe-a01c-f03c743a6608",
"externalId": "PIX-5482123298-EJUYFSMU1UU",
"endToEndId": "E00416968202512111942rjzxxzSSTD9",
"processingDate": "2025-12-11T19:42:04.080Z",
"wasTotalRefunded": false,
"remainingAmountForRefund": 0.2,
"metadata": {},
"counterpart": {
"name": "Carlos Oliveira",
"document": "*.345.678-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": null,
"accountBranch": null,
"accountNumber": null
}
}
}
}
Campos Específicos do CashInReversal
O CashInReversal inclui o objeto parentTransaction com dados da transação original que está sendo estornada.
parentTransaction
Dados da transação PIX In original que está sendo estornada.
parentTransaction.transactionId
UUID da transação PIX In original.
parentTransaction.externalId
ID externo da transação original.
parentTransaction.endToEndId
ID End-to-End da transação original.
parentTransaction.processingDate
Data de processamento da transação original.
parentTransaction.wasTotalRefunded
Indica se o valor total da transação original foi estornado.
true: Estorno total (não pode estornar mais)false: Estorno parcial (ainda pode estornar o restante)
parentTransaction.remainingAmountForRefund
Valor restante que ainda pode ser estornado (em reais).Exemplo: 0.2 (ainda pode estornar R$ 0,20)
parentTransaction.counterpart
Dados do pagador original que receberá o estorno.
Estorno Total vs Parcial
Estorno Total
Quando você devolve 100% do valor recebido:
{
"parentTransaction": {
"wasTotalRefunded": true,
"remainingAmountForRefund": 0
}
}
Estorno Parcial
Quando você devolve apenas parte do valor:
{
"parentTransaction": {
"wasTotalRefunded": false,
"remainingAmountForRefund": 0.2
}
}
Você pode fazer múltiplos estornos parciais até que wasTotalRefunded seja true.
Casos de Uso
1. Devolução de Pagamento Duplicado
async function handleCashInReversal(payload) {
const refundId = payload.transactionId;
const originalOrderId = payload.parentTransaction.externalId;
await refundService.markAsCompleted({
refundId,
originalOrderId,
amount: payload.originalAmount,
completedAt: payload.processingDate
});
// Notificar cliente sobre a devolução
await notificationService.sendRefundConfirmation({
orderId: originalOrderId,
amount: payload.originalAmount
});
}
2. Controle de Estornos Parciais
async function handleCashInReversal(payload) {
const { parentTransaction } = payload;
await refundService.updateStatus({
originalTransactionId: parentTransaction.transactionId,
totalRefunded: !parentTransaction.wasTotalRefunded
? false
: true,
remainingAmount: parentTransaction.remainingAmountForRefund
});
if (parentTransaction.wasTotalRefunded) {
console.log('Transação totalmente estornada');
} else {
console.log(`Ainda disponível para estorno: R$ ${parentTransaction.remainingAmountForRefund}`);
}
}
Fluxo Típico
Próximos Passos
