Visão Geral
O evento CashIn é enviado quando um pagamento PIX é recebido com sucesso na sua conta. Este é o evento mais comum e indica que o dinheiro está disponível.
O movementType para CashIn é sempre CREDIT, indicando entrada de recursos na conta.
| Campo | Valor |
|---|
event | CashIn |
movementType | CREDIT |
| Significado | Dinheiro entrou na sua conta |
Payload Completo
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "CREDIT",
"transactionId": "6d94e3ce-5a10-4fbe-a01c-f03c743a6608",
"externalId": "PIX-5482123298-EJUYFSMU1UU",
"endToEndId": "E00416968202512111942rjzxxzSSTD9",
"pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
"feeAmount": 0.01,
"originalAmount": 0.5,
"finalAmount": 0.49,
"processingDate": "2025-12-11T19:42:04.080Z",
"errorCode": null,
"errorMessage": null,
"counterpart": {
"name": "Carlos Oliveira",
"document": "*.345.678-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": null,
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}
Campos Específicos do CashIn
O CashIn inclui o objeto counterpart com dados do pagador (quem enviou o PIX).
Dados do pagador (quem enviou o PIX para você).
Nome completo do pagador conforme cadastrado no banco de origem.
CPF/CNPJ do pagador (parcialmente mascarado por questões de privacidade).Exemplo: "*.345.678-**"
Dados bancários do pagador.
counterpart.bank.bankISPB
Código ISPB do banco do pagador (identificador único no Sistema de Pagamentos Brasileiro).
counterpart.bank.bankName
Nome do banco do pagador.
counterpart.bank.bankCode
Código COMPE do banco (ex: “001” para Banco do Brasil, “260” para Nubank).
counterpart.bank.accountBranch
Agência do pagador (quando disponível).
counterpart.bank.accountNumber
Número da conta do pagador (quando disponível).
Cálculo do Valor Final
Para eventos de CREDIT (entrada), o valor final é calculado como:
finalAmount = originalAmount - feeAmount
A taxa (feeAmount) é descontada do valor original. Se o pagador enviou R100,00eataxaeˊR 0,50, você receberá R$ 99,50.
Casos de Uso
1. Pagamento de Pedido
async function handleCashIn(payload) {
// Usar externalId para correlacionar com o pedido
const orderId = payload.externalId.replace('PIX-', '');
await orderService.markAsPaid({
orderId,
transactionId: payload.transactionId,
amount: payload.finalAmount,
paidAt: payload.processingDate
});
// Notificar cliente
await notificationService.sendPaymentConfirmation(orderId);
}
2. Recarga de Saldo
async function handleCashIn(payload) {
await walletService.credit({
userId: payload.metadata.userId,
amount: payload.finalAmount,
reference: payload.transactionId
});
}
Fluxo Típico
Próximos Passos
