CashOut
Descripción General
El evento CashOut se envía cuando un pago PIX enviado desde su cuenta llega a un estado final: CONFIRMED (transferencia concluida) o ERROR (transferencia no realizada).
Este evento se dispara tanto para pagos vía clave PIX (/api/pix/cash-out) como para pagos vía código QR (/api/pix/cash-out-qrcode).
El movementType de CashOut es siempre DEBIT, lo que indica salida de fondos de la cuenta.
| Campo | Valor |
|---|---|
event | CashOut |
movementType | DEBIT |
| Significado | Salió dinero 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,
"mismatchAmount": null,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": null,
"errorMessage": null,
"providerId": "f6e5d4c3b2",
"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 los datos del receptor (quien recibió el PIX).
counterpartobjectobrigatorioDatos del receptor (quien recibió el PIX que usted envió).
counterpart.namestring | nullNombre completo del receptor según lo registrado en el banco de destino.
counterpart.documentstring | nullCPF/CNPJ del receptor, en el formato informado por el PSP (puede venir parcialmente enmascarado).
Ejemplo: "*.765.432-**"
counterpart.bankobjectDatos bancarios del receptor: bankISPB, bankName, bankCode, accountBranch y accountNumber. El objeto siempre trae las cinco claves; cada una es null cuando el dato no está disponible.
counterpart.bank.bankCodestring | nullCódigo COMPE del banco del receptor.
Ejemplo: "260" (Nubank)
counterpart.bank.bankISPBstring | nullCódigo ISPB del banco del receptor.
counterpart.bank.bankNamestring | nullNombre del banco del receptor.
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 usted envió R$ 100,00 y la tarifa es R$ 0,50, el débito total en 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
});
// Notificar al equipo financiero
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 SuSistema
participant FyPay
participant Receptor
SuSistema->>FyPay: POST /api/pix/cash-out
FyPay->>FyPay: Valida y procesa
FyPay->>Receptor: Transfiere PIX
Receptor-->>FyPay: Confirmación
FyPay->>SuSistema: Webhook CashOut
SuSistema-->>FyPay: HTTP 2xxManejo 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.01,
"originalAmount": 0.30,
"finalAmount": 0.31,
"mismatchAmount": null,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": "TAX_ID_MISMATCH",
"errorMessage": "O documento informado não corresponde ao titular da chave PIX",
"providerId": null,
"counterpart": {
"name": "Ana Costa",
"document": "12345678900",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": null,
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}Cuando status es ERROR, el endToEndId normalmente es null, ya que el PIX no fue liquidado. feeAmount y finalAmount muestran los valores calculados para la operación, pero nada queda debitado de su cuenta.
Cuando status es ERROR, el monto no queda debitado de su cuenta. Trate el error e informe al usuario.
Los códigos de error varían según el liquidador. Los valores de errorCode dependen del liquidador de su cuenta. Trate el campo errorCode como un string genérico y no lo use para lógica; muestre errorMessage al usuario.