Payouts

Payout webhook events and example payloads.

Payout webhooks track outgoing transfers to recipients.

The examples on this page show crypto payouts.

Field descriptions

Payout webhook events use data.payout.

Field	Type	Description
data.payout.id	string	Unique payout identifier.
data.payout.method	string	Payout method.
data.payout.type	string	Payout type.
data.payout.status	string	Payout status.
data.payout.amount	string	Net payout amount.
data.payout.fee	string	Fee charged.
data.payout.total	string	Total debited amount.
data.payout.currency	string	Payout currency.
data.payout.reference	string | null	External reference.
data.payout.narration	string | null	Payout narration.
data.payout.recipient	object	Recipient details.
data.payout.txHash	string | null	Blockchain transaction hash when available.
data.payout.createdAt	string	Creation timestamp.
data.payout.updatedAt	string	Last update timestamp.
data.payout.completedAt	string | null	Completion timestamp for successful payouts.
data.payout.failureReason	string | null	Failure reason for failed payouts.

Events

• payout.created
• payout.success
• payout.failed

payout.created

Sent when a payout is created.

Use this event to track payout initiation.

{
  "event": "payout.created",
  "data": {
    "payout": {
      "id": "po_123",
      "method": "crypto",
      "type": "withdrawal",
      "status": "pending",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "reference": "PAY-ABC123DEF456",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "cryptoAddress",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "ethereum",
        "asset": "USDT",
        "accountName": null,
        "accountNumber": null,
        "bankName": null
      },
      "txHash": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

payout.success

Sent when a payout is delivered successfully.

Use this event to close the payout in your ledger.

{
  "event": "payout.success",
  "data": {
    "payout": {
      "id": "po_123",
      "method": "crypto",
      "type": "withdrawal",
      "status": "success",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "reference": "PAY-ABC123DEF456",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "cryptoAddress",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "ethereum",
        "asset": "USDT",
        "accountName": null,
        "accountNumber": null,
        "bankName": null
      },
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "completedAt": "2024-01-15T10:40:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:40:00.000Z"
    }
  }
}

payout.failed

Sent when a payout fails.

Use this event to stop reconciliation and surface the error.

Check data.payout.failureReason for the failure reason.

{
  "event": "payout.failed",
  "data": {
    "payout": {
      "id": "po_123",
      "method": "crypto",
      "type": "withdrawal",
      "status": "failed",
      "amount": "99.50",
      "fee": "0.50",
      "total": "100.00",
      "currency": "USDT",
      "reference": "PAY-ABC123DEF456",
      "narration": "Withdrawal payout",
      "recipient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "cryptoAddress",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "ethereum",
        "asset": "USDT",
        "accountName": null,
        "accountNumber": null,
        "bankName": null
      },
      "txHash": null,
      "failureReason": "Invalid address",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  }
}