CashIn
Descripción General
El evento CashIn se envía cuando un pago PIX es recibido exitosamente en su cuenta. Este es el evento más común e indica que el dinero está disponible.
El movementType para CashIn es siempre CREDIT, indicando una entrada de fondos en la cuenta.
| Campo | Valor |
|---|---|
event | CashIn |
movementType | CREDIT |
| Significado | El dinero entró a su cuenta |
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 de CashIn
CashIn incluye el objeto counterpart con datos del pagador (quien envió el PIX).
counterpartobjectobrigatorioDatos del pagador (quien le envió el PIX).
counterpart.namestringNombre completo del pagador tal como está registrado en el banco de origen.
counterpart.documentstringCPF/CNPJ del pagador (parcialmente enmascarado por privacidad).
Ejemplo: "*.345.678-**"
counterpart.bankobjectDatos bancarios del pagador.
counterpart.bank.bankISPBstringCódigo ISPB del banco del pagador (identificador único en el Sistema de Pagos Brasileño).
counterpart.bank.bankNamestringNombre del banco del pagador.
counterpart.bank.bankCodestringCódigo COMPE del banco (ej.: "001" para Banco do Brasil, "260" para Nubank).
counterpart.bank.accountBranchstringSucursal del pagador (cuando esté disponible).
counterpart.bank.accountNumberstringNúmero de cuenta del pagador (cuando esté disponible).
Cálculo del Monto Final
Para eventos CREDIT (entrada), el monto final se calcula como:
finalAmount = originalAmount - feeAmountLa tarifa (feeAmount) se deduce del monto original. Si el pagador envió R$ 100.00 y la tarifa es R$ 0.50, usted recibirá R$ 99.50.
Casos de Uso
1. Pago de Pedido
async function handleCashIn(payload) {
// Use externalId to correlate with the order
const orderId = payload.externalId.replace('PIX-', '');
await orderService.markAsPaid({
orderId,
transactionId: payload.transactionId,
amount: payload.finalAmount,
paidAt: payload.processingDate
});
// Notify customer
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
});
}Flujo Típico
sequenceDiagram
participant Payer
participant Avista
participant YourSystem
Payer->>Avista: Sends PIX
Avista->>Avista: Processes transaction
Avista->>YourSystem: Webhook CashIn
YourSystem->>YourSystem: Validates authentication
YourSystem->>YourSystem: Checks idempotency
YourSystem-->>Avista: HTTP 200 OK
YourSystem->>YourSystem: Processes payment