Documentation Index Fetch the complete documentation index at: https://docs.firebanking.dev/llms.txt
Use this file to discover all available pages before exploring further.
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 eventCashInReversalmovementTypeDEBITSignificado Você devolveu dinheiro que havia recebido
Payload Completo { "event" : "CashInReversal" , "status" : "CONFIRMED" , "transactionType" : "PIX" , "movementType" : "DEBIT" , "transactionId" : "11111" , "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" : "12345" , "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
ID numérico da transação PIX In original (retornado como string).
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
PIX Refund-In Aprenda a estornar recebimentos
CashIn Entenda o evento de recebimento
