CashIn
Overview
The CashIn event is sent when a PIX payment received in your account is processed. With status: "CONFIRMED", the amount has been credited and is available.
The movementType for CashIn is always CREDIT, indicating incoming funds to the account.
| Field | Value |
|---|---|
event | CashIn |
movementType | CREDIT |
| Meaning | Money entered your account |
Full Payload
{
"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,
"mismatchAmount": null,
"processingDate": "2025-12-11T19:42:04.080Z",
"errorCode": null,
"errorMessage": null,
"providerId": "a1b2c3d4e5",
"counterpart": {
"name": "Carlos Oliveira",
"document": "*.345.678-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": null,
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}CashIn-Specific Fields
CashIn includes the counterpart object with data about the payer (who sent the PIX).
counterpartobjectobrigatorioData about the payer (who sent the PIX to you).
counterpart.namestring | nullPayer's full name as registered at the originating bank.
counterpart.documentstring | nullPayer's CPF/CNPJ, in the format provided by the PSP (may be partially masked).
Example: "*.345.678-**"
counterpart.bankobjectPayer's bank details. The object always contains the five keys below; each one is null when the PSP does not provide the data.
counterpart.bank.bankISPBstring | nullISPB code of the payer's bank (unique identifier in the Brazilian Payment System).
counterpart.bank.bankNamestring | nullName of the payer's bank.
counterpart.bank.bankCodestring | nullBank COMPE code (e.g. "001" for Banco do Brasil, "260" for Nubank).
counterpart.bank.accountBranchstring | nullPayer's branch (when available).
counterpart.bank.accountNumberstring | nullPayer's account number (when available).
Final Amount Calculation
For CREDIT (incoming) events, the final amount is calculated as:
finalAmount = originalAmount - feeAmountThe fee (feeAmount) is deducted from the original amount. If the payer sent R$ 100.00 and the fee is R$ 0.50, you will receive R$ 99.50.
Paid Amount Check
The originalAmount field carries the amount actually paid by the payer. Always compare this value
with what you generated in the charge (QR Code) before releasing goods or services.
To make this check easier, the webhook includes the mismatchAmount field with the difference already calculated:
mismatchAmount | Meaning |
|---|---|
null | No mismatch — the payer paid exactly the charged amount. |
| Positive | The payer paid less than charged. E.g.: 50.00 = charged R$ 100.00, paid R$ 50.00. |
| Negative | The payer paid more than charged. E.g.: -50.00 = charged R$ 50.00, paid R$ 100.00. |
Example of a R$ 100.00 charge paid with R$ 50.00:
{
"event": "CashIn",
"originalAmount": 50.0,
"feeAmount": 0.5,
"finalAmount": 49.5,
"mismatchAmount": 50.0
}Handle the mismatch in your reconciliation before considering the order paid. A mismatchAmount
other than null means the amount received is not what you charged.
Use Cases
1. Order Payment
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. Balance Top-up
The metadata carries the additionalInfo you sent when creating the charge. In this example, the charge was created with additionalInfo.userId.
async function handleCashIn(payload) {
await walletService.credit({
userId: payload.metadata.userId,
amount: payload.finalAmount,
reference: payload.transactionId
});
}Typical Flow
sequenceDiagram
participant Payer
participant API as Gateways
participant YourSystem
Payer->>API: Sends PIX
API->>API: Processes transaction
API->>YourSystem: CashIn Webhook
YourSystem->>YourSystem: Validates X-Avista-Signature
YourSystem->>YourSystem: Checks idempotency
YourSystem-->>API: HTTP 2xx
YourSystem->>YourSystem: Processes payment