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" y los campos errorCode/errorMessage completados:
{
"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": {}
}Cuando status es ERROR, el campo endToEndId será null (el PIX no fue confirmado por el Banco Central) y feeAmount será 0 (no se cobra tarifa en operaciones fallidas).
Cuando status es ERROR, el monto no fue debitado de su cuenta. Maneje el error e informe al usuario.
¿Cómo probar webhooks de error? En sandbox, use el header X-Sandbox-Scenario para simular errores. Los errorCode en sandbox (ej: INSUFFICIENT_FUNDS) pueden diferir de los códigos de producción (ej: TAX_ID_MISMATCH), ya que cada proveedor tiene su propio formato. Trate el campo errorCode como string genérico en vez de mapear códigos fijos. Vea todos los escenarios en la guía de Pruebas en Sandbox.