Withdrawal webhook events

Withdrawal events are terminal notifications. A newly submitted or pending withdrawal does not produce a Partner webhook event.

Event	When it is sent
`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 three 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.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.success`

`withdrawal.partial`

`withdrawal.failed`

​withdrawal.success

​withdrawal.partial

​withdrawal.failed

`withdrawal.success`

`withdrawal.partial`

`withdrawal.failed`