CashOut
Descripción General
El evento CashOut se envía cuando un pago PIX es enviado exitosamente desde su cuenta a otra cuenta. Indica que la transferencia fue completada.
Este evento se dispara tanto para pagos por clave PIX (/api/pix/cash-out) como para pagos por QR Code (/api/pix/cash-out-qrcode).
El movementType para CashOut es siempre DEBIT, indicando una salida de fondos de la cuenta.
| Campo | Valor |
|---|---|
event | CashOut |
movementType | DEBIT |
| Significado | El dinero salió de su cuenta |
Payload Completo
{
"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": {}
}Campos Específicos de CashOut
CashOut incluye el objeto counterpart con datos del destinatario (quien recibió el PIX).
counterpartobjectobrigatorioDatos del destinatario (quien recibió el PIX que usted envió).
counterpart.namestringNombre completo del destinatario tal como está registrado en el banco de destino.
counterpart.documentstringCPF/CNPJ del destinatario (parcialmente enmascarado por privacidad).
Ejemplo: "*.765.432-**"
counterpart.bankobjectDatos bancarios del destinatario.
counterpart.bank.bankCodestringCódigo COMPE del banco del destinatario.
Ejemplo: "260" (Nubank)
counterpart.bank.bankISPBstringCódigo ISPB del banco del destinatario.
counterpart.bank.bankNamestringNombre del banco del destinatario.
Cálculo del Monto Final
Para eventos DEBIT (salida), el monto final se calcula como:
finalAmount = originalAmount + feeAmountLa tarifa (feeAmount) se suma al monto original. Si envió R$ 100.00 y la tarifa es R$ 0.50, el débito total de su cuenta será R$ 100.50.
Casos de Uso
1. Pago a Proveedor
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. Retiro de Cliente
async function handleCashOut(payload) {
await withdrawalService.confirm({
withdrawalId: payload.externalId,
transactionId: payload.transactionId,
amount: payload.originalAmount,
fee: payload.feeAmount
});
}Flujo Típico
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 OKManejo de Errores
Cuando un CashOut falla, recibirá el webhook con status: "ERROR":
{
"event": "CashOut",
"status": "ERROR",
"errorCode": "INVALID_PIX_KEY",
"errorMessage": "Chave PIX não encontrada ou inválida",
...
}Cuando status es ERROR, el monto no fue debitado de su cuenta. Maneje el error e informe al usuario.