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":
{
"event": "CashOut",
"status": "ERROR",
"errorCode": "INVALID_PIX_KEY",
"errorMessage": "Chave PIX não encontrada ou inválida",
...
}When status is ERROR, the amount was not debited from your account. Handle the error and inform the user.