Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

payoutIdstring

The payout ID.

amountnumber

Gross payout amount in cents (100 = $1.00).

feenumber

Provider transfer fee in cents.

netAmountnumber

What would have reached your bank in cents.

currencystring

The payout currency. Always "usd".

statusstring

Always "failed" for this event.

destinationBankobject | null

Destination bank display metadata: bankName and last4.

failedAtstring | null

ISO 8601 datetime when the failure was recorded.

failureCodestring | null

The provider's failure code, when available.

failureMessagestring | null

A human-readable failure message, when available.

{
  "event": "payout.failed",
  "timestamp": "2026-06-14T09:00:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "payoutId": "8b6f2a1c-4d3e-4f5a-9b8c-7d6e5f4a3b2c",
    "amount": 20000,
    "fee": 0,
    "netAmount": 20000,
    "currency": "usd",
    "status": "failed",
    "destinationBank": {
      "bankName": "CHASE",
      "last4": "6789"
    },
    "failedAt": "2026-06-14T09:00:00.000Z",
    "failureCode": "account_closed",
    "failureMessage": "The bank account has been closed"
  }
}

Cuándo se dispara

Cuando el proveedor informa que una transferencia no pudo completarse, en cualquiera de las etapas del ciclo de vida, lo más común cuando el banco rechaza el depósito (cuenta cerrada, datos inválidos). Los fondos vuelven a tu saldo disponible.

failureCode y failureMessage llevan el motivo del proveedor cuando está disponible.

Úsalo para alertar a tu contacto de finanzas y corregir la cuenta bancaria antes de volver a solicitar la transferencia.