CashOut
Overview
The CashOut event is sent when a PIX payment is sent successfully from your account to another account. It indicates that the transfer was completed.
This event is triggered for both PIX key payments (/api/pix/cash-out) and QR Code payments (/api/pix/cash-out-qrcode).
The movementType for CashOut is always DEBIT, indicating an outflow of funds from the account.
| Field | Value |
|---|---|
event | CashOut |
movementType | DEBIT |
| Meaning | Money left your account |
Full Payload
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
"endToEndId": "E071368472025121120065P1T3N1CS1A",
"pixKey": "07646173380",
"feeAmount": 0.01,
"originalAmount": 0.30,
"finalAmount": 0.31,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": null,
"errorMessage": null,
"counterpart": {
"name": "Ana Costa",
"document": "*.765.432-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": "260",
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}CashOut-Specific Fields
CashOut includes the counterpart object with data about the recipient (who received the PIX).
counterpartobjectobrigatorioData about the recipient (who received the PIX you sent).
counterpart.namestringFull name of the recipient as registered at the destination bank.
counterpart.documentstringRecipient's CPF/CNPJ (partially masked for privacy).
Example: "*.765.432-**"
counterpart.bankobjectRecipient's bank details.
counterpart.bank.bankCodestringCOMPE code of the recipient's bank.
Example: "260" (Nubank)
counterpart.bank.bankISPBstringISPB code of the recipient's bank.
counterpart.bank.bankNamestringName of the recipient's bank.
Final Amount Calculation
For DEBIT events (outflow), the final amount is calculated as:
finalAmount = originalAmount + feeAmountThe fee (feeAmount) is added to the original amount. If you sent R$ 100.00 and the fee is R$ 0.50, the total debit from your account will be R$ 100.50.
Use Cases
1. Supplier Payment
async function handleCashOut(payload) {
const paymentId = payload.externalId.replace('PIX-OUT-', '');
await paymentService.markAsCompleted({
paymentId,
transactionId: payload.transactionId,
endToEndId: payload.endToEndId,
completedAt: payload.processingDate
});
// Notify finance team
await notificationService.sendPaymentCompleted(paymentId);
}2. Customer Withdrawal
async function handleCashOut(payload) {
await withdrawalService.confirm({
withdrawalId: payload.externalId,
transactionId: payload.transactionId,
amount: payload.originalAmount,
fee: payload.feeAmount
});
}Typical Flow
sequenceDiagram
participant YourSystem
participant Avista
participant Recipient
YourSystem->>Avista: POST /api/pix/payment
Avista->>Avista: Validates and processes
Avista->>Recipient: Transfers PIX
Recipient-->>Avista: Confirmation
Avista->>YourSystem: Webhook CashOut
YourSystem-->>Avista: HTTP 200 OKError Handling
When a CashOut fails, you will receive the webhook with status: "ERROR" and the errorCode/errorMessage fields populated:
{
"event": "CashOut",
"status": "ERROR",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
"endToEndId": null,
"pixKey": "07646173380",
"feeAmount": 0,
"originalAmount": 0.30,
"finalAmount": 0.30,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": "TAX_ID_MISMATCH",
"errorMessage": "O documento informado não corresponde ao titular da chave PIX",
"counterpart": {
"name": null,
"document": null,
"bank": {}
},
"metadata": {}
}When status is ERROR, the endToEndId field will be null (the PIX was not confirmed by the Central Bank) and feeAmount will be 0 (no fee is charged on failed operations).
When status is ERROR, the amount was not debited from your account. Handle the error and inform the user.
How to test error webhooks? In sandbox, use the X-Sandbox-Scenario header to simulate errors. The errorCode values in sandbox (e.g., INSUFFICIENT_FUNDS) may differ from production codes (e.g., TAX_ID_MISMATCH), as each provider has its own format. Treat the errorCode field as a generic string instead of mapping fixed codes. See all scenarios in the Sandbox Testing guide.