Withdrawal webhook events

External withdrawals emit withdrawal.pending once the payout has been accepted for processing. This acknowledges that the payout is underway; it does not confirm that the beneficiary has received funds. Subscribe explicitly to withdrawal.pending to receive this best-effort update. The success, partial, and failed events report the final outcome.

Event	When it is sent
`withdrawal.pending`	The payout was accepted for processing; final confirmation is outstanding.
`withdrawal.success`	Every bank transfer or the stablecoin transfer was paid.
`withdrawal.partial`	An NGN withdrawal with more than one bank transfer finished with some transfers paid and the rest failed. The failed principal and fees are already back in the wallet.
`withdrawal.failed`	Nothing was paid.

All four events contain a public wallet transaction snapshot under data.transaction. settlement_details.type is bank_transfer for NGN, crypto for stablecoin settlement, and usd_cash for USD cash activity; the usd_cash shape has only rail_reference, confirmed_at, and failed_at. Handle all three types. withdrawal.partial is only possible for NGN withdrawals that were split into several bank transfers, most often bulk withdrawals. Subscribe to all three so a mixed batch is not left waiting for an event that will never arrive.

`withdrawal.pending`

The event uses the same transaction ID as the final webhook, with data.transaction.status set to processing. This event covers NGN bank payouts, USD stablecoin payouts, and NGN payouts through cNGN. Internal transfers that complete immediately send their terminal event directly.

{
  "id": "c30218a5-2f72-5355-9df7-9a4486fd7b31",
  "type": "withdrawal.pending",
  "version": 1,
  "occurred_at": "2026-07-17T10:04:25Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-7893-7cda-8944-528b5e9e3318",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "withdrawal",
      "status": "processing",
      "amount": "75000.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "created_at": "2026-07-17T10:04:20+00:00",
      "updated_at": "2026-07-17T10:04:25+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-7893-7cda-8944-528b5e9e3318",
        "confirmed_at": null,
        "failed_at": null
      }
    }
  }
}

`withdrawal.success`

{
  "id": "b5be9fe7-f602-5dcc-9f28-985b324c3d39",
  "type": "withdrawal.success",
  "version": 1,
  "occurred_at": "2026-07-17T10:08:12Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-7893-7cda-8944-528b5e9e3318",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "withdrawal",
      "status": "success",
      "amount": "75000.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "created_at": "2026-07-17T10:04:20+00:00",
      "updated_at": "2026-07-17T10:08:12+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-7893-7cda-8944-528b5e9e3318",
        "confirmed_at": "2026-07-17T10:08:12+00:00",
        "failed_at": null
      }
    }
  }
}

`withdrawal.partial`

{
  "id": "3f0c2a4e-7d1b-5a63-9e2f-0c4b8d7a1e55",
  "type": "withdrawal.partial",
  "version": 1,
  "occurred_at": "2026-09-09T08:19:41Z",
  "data": {
    "transaction": {
      "id": "0198f3a0-0000-7000-8000-0000000000a1",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "withdrawal",
      "status": "partial",
      "amount": "1045000.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "created_at": "2026-09-09T08:12:04+00:00",
      "updated_at": "2026-09-09T08:19:41+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "0198f3a0-0000-7000-8000-0000000000a1",
        "confirmed_at": "2026-09-09T08:19:41+00:00",
        "failed_at": null
      }
    }
  }
}

amount is the full amount you requested, not the amount that was paid. confirmed_at is when the batch finished settling. Read GET /v1/partner/wallets/transactions/{id} and walk settlement_details.transfers to see which beneficiaries were paid and which need a fresh withdrawal, as shown in Bulk withdrawals.

`withdrawal.failed`

{
  "id": "886a7af0-c0d9-573d-a42e-1580b2f3184e",
  "type": "withdrawal.failed",
  "version": 1,
  "occurred_at": "2026-07-17T10:11:44Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-846f-727d-9c04-9d2ea226f344",
      "rail": "crypto",
      "currency": "USD",
      "tx_type": "withdrawal",
      "status": "failed",
      "amount": "50.00",
      "reference": null,
      "description": null,
      "failure_reason": "withdrawal_failed",
      "settlement_rail": "USDC",
      "created_at": "2026-07-17T10:10:06+00:00",
      "updated_at": "2026-07-17T10:11:44+00:00",
      "settlement_details": {
        "type": "crypto",
        "rail_reference": "019bd2d1-846f-727d-9c04-9d2ea226f344",
        "blockchain_tx_hash": null,
        "explorer_url": null,
        "sender_address": null,
        "destination_address": null,
        "beneficiary_nickname": null,
        "network": null,
        "network_display": null,
        "principal_amount": null,
        "network_fee": null,
        "block_number": null,
        "confirmations": null,
        "confirmed_at": null,
        "failed_at": "2026-07-17T10:11:44+00:00"
      }
    }
  }
}

The webhook snapshot does not expose recipient bank details, destination wallet addresses, per-transfer detail, network fees, or raw failure messages. Within a webhook, reference and description are always null, and settlement_details.rail_reference echoes the transaction id rather than an external reference; read the transaction for all three. Use data.transaction.id with GET /v1/partner/wallets/transactions/{id} for the latest public resource. Return to the webhook overview

Get Started

Wallets

Exchange

Webhooks

WebSocket

Withdrawal webhook events

`withdrawal.pending`

`withdrawal.success`

`withdrawal.partial`

`withdrawal.failed`