CashIn
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": "12345",
"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).
counterpartobjectobrigatorioDados do pagador (quem enviou o PIX para você).
counterpart.namestringNome completo do pagador conforme cadastrado no banco de origem.
counterpart.documentstringCPF/CNPJ do pagador (parcialmente mascarado por questões de privacidade).
Exemplo: "*.345.678-**"
counterpart.bankobjectDados bancários do pagador.
counterpart.bank.bankISPBstringCódigo ISPB do banco do pagador (identificador único no Sistema de Pagamentos Brasileiro).
counterpart.bank.bankNamestringNome do banco do pagador.
counterpart.bank.bankCodestringCódigo COMPE do banco (ex: "001" para Banco do Brasil, "260" para Nubank).
counterpart.bank.accountBranchstringAgência do pagador (quando disponível).
counterpart.bank.accountNumberstringNú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 - feeAmountA taxa (feeAmount) é descontada do valor original. Se o pagador enviou R$ 100,00 e a taxa é 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
sequenceDiagram
participant Pagador
participant Avista
participant SeuSistema
Pagador->>Avista: Envia PIX
Avista->>Avista: Processa transação
Avista->>SeuSistema: Webhook CashIn
SeuSistema->>SeuSistema: Valida autenticação
SeuSistema->>SeuSistema: Verifica idempotência
SeuSistema-->>Avista: HTTP 200 OK
SeuSistema->>SeuSistema: Processa pagamento