Deposit webhook events

Deposit events contain a public wallet transaction snapshot under data.transaction. Subscribe to one or more exact event names; deposit.* is not supported.

Event	When it is sent
`deposit.action_required`	A crypto deposit is on hold until Travel Rule information is submitted.
`deposit.success`	A fiat or crypto deposit reached its successful terminal state.
`deposit.failed`	A fiat or crypto deposit reached its failed terminal state.

For CNGN, deposit.success confirms the net NGN credit, which can include funds awaiting conversion capacity. Subscribe separately to conversion.updated and use balances and withdrawal quotes for current spendability.

`deposit.action_required`

This event has status: "hold" and a required_action object. Call the relative submission_url on your API base URL with the same API key you use for wallet requests. Reading the required fields needs wallets:view; submitting them needs wallets:transfer.

{
  "id": "9f511315-90c9-5fc7-95a0-a79e72b4a425",
  "type": "deposit.action_required",
  "version": 1,
  "occurred_at": "2026-07-17T09:40:00Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-4e10-77ab-88d4-93f43d6a6df2",
      "rail": "crypto",
      "currency": "USD",
      "tx_type": "deposit",
      "status": "hold",
      "amount": "100.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "settlement_rail": "USDC",
      "required_action": {
        "type": "travel_rule",
        "status": "required",
        "submission_url": "/partner/wallets/crypto/deposits/019bd2d1-4e10-77ab-88d4-93f43d6a6df2/travel-rule"
      },
      "created_at": "2026-07-17T09:38:41+00:00",
      "updated_at": "2026-07-17T09:40:00+00:00",
      "settlement_details": {
        "type": "crypto",
        "rail_reference": "019bd2d1-4e10-77ab-88d4-93f43d6a6df2",
        "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": null
      }
    }
  }
}

`deposit.success`

The snapshot is deliberately minimal and immutable. settlement_details.type is bank_transfer for NGN bank deposits, crypto for stablecoin deposits (including CNGN into NGN), and usd_cash for USD cash activity; the usd_cash shape has only rail_reference, confirmed_at, and failed_at. Handle all three types. Within a webhook, reference and description are always null, and settlement_details.rail_reference echoes the transaction id rather than an external reference. Later settlement details such as bank account details, blockchain hashes, and confirmation counts are not included in the webhook body either. Read the transaction resource when you need its external reference or latest details.

{
  "id": "0eddb359-f13e-5183-9337-31cb7e275d6b",
  "type": "deposit.success",
  "version": 1,
  "occurred_at": "2026-07-17T09:42:18Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-58ac-7d3d-b2b1-36c5d9bf0272",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "deposit",
      "status": "success",
      "amount": "250000.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "created_at": "2026-07-17T09:41:02+00:00",
      "updated_at": "2026-07-17T09:42:18+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-58ac-7d3d-b2b1-36c5d9bf0272",
        "confirmed_at": "2026-07-17T09:42:18+00:00",
        "failed_at": null
      }
    }
  }
}

`deposit.failed`

The public failure_reason is normalized and does not expose raw rail or internal accounting details.

{
  "id": "c902d7ed-5ef1-5d7c-9032-a9d63a39b47d",
  "type": "deposit.failed",
  "version": 1,
  "occurred_at": "2026-07-17T09:45:31Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-63bb-7a95-a9b4-cd9270c1b32a",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "deposit",
      "status": "failed",
      "amount": "250000.00",
      "reference": null,
      "description": null,
      "failure_reason": "deposit_failed",
      "created_at": "2026-07-17T09:44:57+00:00",
      "updated_at": "2026-07-17T09:45:31+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-63bb-7a95-a9b4-cd9270c1b32a",
        "confirmed_at": null,
        "failed_at": "2026-07-17T09:45:31+00:00"
      }
    }
  }
}

Reconcile the resource

Use data.transaction.id with GET /v1/partner/wallets/transactions/{id}. The REST response is authoritative and may contain newer display or settlement information than the immutable webhook snapshot. Return to the webhook overview

Get Started

Wallets

Exchange

Webhooks

WebSocket

Deposit webhook events

`deposit.action_required`

`deposit.success`

`deposit.failed`

Reconcile the resource