Single Withdrawals

Withdrawal access is disabled on new API keys by default. Enable the wallets:withdraw scope when creating a dedicated key, store its signing secret once, and keep it in a server-side secret store. Production withdrawal submission requires approved KYB for every supported NGN and USD settlement rail. Withdrawal quotes remain available before approval, but submit returns 403 while KYB is non-approved. Development and staging skip this KYB gate. The signed Partner API request authorizes the withdrawal directly. There is no emailed verification step and no client-supplied withdrawal token after submit.

See Withdrawal examples for complete Node.js and Python implementations that quote, sign, submit, and hand completion off to webhooks.

Routes

This page covers a withdrawal to one beneficiary and the signing, retry, and error rules that apply to every withdrawal. An NGN request can also carry up to 50 beneficiaries; see Bulk withdrawals for the bank-transfer specifics. For NGN withdrawals as CNGN, see the NGN currency guide.

Route	Purpose
`POST /partner/wallets/withdrawal/quotes`	Validate an intent and preview fees, items, and transfers without reserving funds
`POST /partner/wallets/withdrawals`	Directly create one parent withdrawal
`GET /partner/wallets/transactions`	List resulting parent transactions
`GET /partner/wallets/transactions/{id}`	Read parent status and item-level transfer outcomes

Quote and submit require X-Api-Key, X-Stabyl-Timestamp, X-Stabyl-Nonce, and X-Stabyl-Signature. Transaction reads require X-Api-Key and wallets:view.

Request Signing

Use the exact bytes sent in the HTTP body. Do not parse and reserialize JSON between hashing and sending the request.

STABYL-SIGNATURE-V1
<unix timestamp in milliseconds>
<UUIDv4 or UUIDv7 nonce>
<uppercase HTTP method>
<exact path and query>
<lowercase hex SHA-256 of the raw body>

Join those six values with newline characters and no trailing newline. Sign the UTF-8 bytes with Ed25519, then encode the 64-byte signature as unpadded base64url. Sign the complete path exactly as it appears in the request URL. For the production submit URL, sign /v1/partner/wallets/withdrawals, not /partner/wallets/withdrawals. Include the query string exactly when one is present. The server accepts a timestamp up to 30 seconds behind or ahead. A verified nonce is single-use for five minutes. Synchronize server clocks with NTP.

Test Vector

These values are synthetic and must never be used outside tests.

private seed (base64url): BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc
public key (base64url):  6kpsY-KcUgq-9VB7Ey7F-ZVHdq6-vnuSQh7qaRRG0iw
timestamp:               1783756800000
nonce:                   018f32f0-3333-7333-8333-333333333333
method:                  POST
path:                    /v1/partner/wallets/withdrawals
body SHA-256:            1a73bf403deda52f4271d542a62e1961dee1959607e06b439d24a8f9d61aaf81
signature (base64url):   -_flQmASKXMSSh5cMTAON3zdPWWDWus4ONfim0kYqaG3nGPyWw-TC4bbr4YfmoebWgYgj6V2DNmM6WIl1oaHAA

The body hash covers the exact bytes you send. The vector above hashes this single-line body with no whitespace (the same JSON shown pretty-printed below would hash differently):

{"currency":"NGN","items":[{"client_item_id":"beneficiary-a","amount":"200000000.00","destination":{"type":"bank_account","bank_code":"044","bank_name":"Access Bank","account_number":"0123456789","account_name":"Example Recipient"},"description":"Supplier settlement"}],"idempotency_key":"partner-withdrawal-20260711-001"}

{
  "currency": "NGN",
  "items": [
    {
      "client_item_id": "beneficiary-a",
      "amount": "200000000.00",
      "destination": {
        "type": "bank_account",
        "bank_code": "044",
        "bank_name": "Access Bank",
        "account_number": "0123456789",
        "account_name": "Example Recipient"
      },
      "description": "Supplier settlement"
    }
  ],
  "idempotency_key": "partner-withdrawal-20260711-001"
}

Whatever serializer you use, hash and sign the exact bytes you put on the wire.

Quote NGN

Quote bodies always use items and omit idempotency_key:

{
  "currency": "NGN",
  "items": [
    {
      "client_item_id": "beneficiary-a",
      "amount": "200000000.00",
      "destination": {
        "type": "bank_account",
        "bank_code": "044",
        "bank_name": "Access Bank",
        "account_number": "0123456789",
        "account_name": "Example Recipient"
      },
      "description": "Supplier settlement"
    }
  ]
}

A single bank transfer is capped at 100000000.00 NGN, so a quote for 200000000.00 NGN reports two transfers. The parent amount, fee, and debit remain aggregate values.

Quote Response

Quotes return one entry per settlement route under quotes:

{
  "status": "success",
  "data": {
    "currency": "NGN",
    "amount": "200000000.00",
    "quotes": [
      {
        "rail": "bank_transfer",
        "status": "available",
        "fee": "200.00",
        "debit_amount": "200000200.00",
        "estimated_receive": "200000000.00",
        "receive_currency": "NGN",
        "transfer_count": 2,
        "max_transfer_amount": "100000000.00",
        "max_withdrawable_amount": "299999700.00",
        "as_of": "2026-10-20T12:00:00Z",
        "items": [
          {
            "client_item_id": "beneficiary-a",
            "amount": "200000000.00",
            "destination": {
              "type": "bank_account",
              "bank_code": "044",
              "bank_name": "Access Bank",
              "account_number": "0123456789",
              "account_name": "Example Recipient"
            },
            "transfers": [
              { "sequence": 1, "amount": "100000000.00", "status": "available" },
              { "sequence": 2, "amount": "100000000.00", "status": "available" }
            ]
          }
        ]
      }
    ]
  }
}

An NGN bank quote contains one bank_transfer entry. A CNGN quote contains one CNGN entry. NGN quotes include max_withdrawable_amount and as_of; an oversized valid request returns status: "unavailable" and a reason_code with the current maximum. The requested fee, debit, and receive amounts are preserved. max_transfer_amount is the bank’s per-transfer limit, not the account’s withdrawable balance. For a beneficiary list, the maximum describes one destination; availability and fees describe the actual list. A USD quote contains one entry for the requested settlement_rail; it adds expires_at and settlement_estimate, omits max_transfer_amount, and can carry a status other than available with a reason. Submit a USD withdrawal before its quote expires. Quoting never reserves funds. Submission rechecks balances and account limits and can reject a request that was previously available. Quote as part of a user action rather than in a loop; quotes have their own rate limit.

Submit NGN

Submit uses the same list envelope and adds one parent idempotency key:

{
  "currency": "NGN",
  "items": [
    {
      "client_item_id": "beneficiary-a",
      "amount": "200000000.00",
      "destination": {
        "type": "bank_account",
        "bank_code": "044",
        "bank_name": "Access Bank",
        "account_number": "0123456789",
        "account_name": "Example Recipient"
      },
      "description": "Supplier settlement"
    }
  ],
  "idempotency_key": "partner-withdrawal-20260711-001"
}

You can send multiple beneficiaries in one request. client_item_id is optional but recommended for correlating your records with response items.

Paying many bank accounts at once? Bulk withdrawals covers the 50-beneficiary limit, per-transfer fees, partial outcomes, and how to reconcile each transfer.

Submit USD

USD stablecoin settlement uses the same envelope, with a parent settlement_rail and exactly one item in the current version:

{
  "currency": "USD",
  "settlement_rail": "USDC",
  "items": [
    {
      "client_item_id": "customer-payout-42",
      "amount": "1000.00",
      "destination": {
        "type": "crypto_address",
        "chain": "evm",
        "slug": "base",
        "address": "0x1111111111111111111111111111111111111111"
      },
      "description": "Customer payout"
    }
  ],
  "idempotency_key": "partner-withdrawal-20260711-002"
}

Supported settlement rails are USDT and USDC on an available chain. A USD quote validates the supplied chain, slug, and destination against the current environment and enabled route before it can return available. Cash USD settlement is not available through this API. An unsupported rail, a destination that does not match the rail, or an unsupported chain returns UNSUPPORTED_WITHDRAWAL_ROUTE; more than one USD item or a missing settlement_rail returns VALIDATION_FAILED. The USD submit response differs from the NGN one in a few ways: rail is crypto, settlement_rail is present, amount equals debit_amount with the fee taken out of it (so estimated_receive is what the destination receives), transfer_count is 1, max_transfer_amount is absent, and reference equals id.

Response Shape

The submit response represents one parent transaction. items is always a list, including one-item NGN and USD withdrawals. NGN items can contain multiple transfers. The NGN fee is charged for every generated bank transfer, so fee is the ₦100 flat transfer fee multiplied by transfer_count.

{
  "status": "success",
  "data": {
    "id": "0197f1f0-0000-7000-8000-000000000014",
    "status": "pending",
    "rail": "fiat",
    "currency": "NGN",
    "tx_type": "withdrawal",
    "amount": "200000000.00",
    "reference": "WD-0197f1f0-4c2d-7e4f-8a91-0b3c5d7e9f11",
    "fee": "200.00",
    "debit_amount": "200000200.00",
    "estimated_receive": "200000000.00",
    "receive_currency": "NGN",
    "transfer_count": 2,
    "max_transfer_amount": "100000000.00",
    "items": [
      {
        "client_item_id": "beneficiary-a",
        "amount": "200000000.00",
        "destination": {
          "type": "bank_account",
          "bank_code": "044",
          "bank_name": "Access Bank",
          "account_number": "0123456789",
          "account_name": "Example Recipient"
        },
        "transfers": [
          { "sequence": 1, "amount": "100000000.00", "status": "processing" },
          { "sequence": 2, "amount": "100000000.00", "status": "processing" }
        ]
      }
    ]
  }
}

The parent starts as pending and its transfers as processing. reference is WD- followed by a full UUID; it is generated by Stabyl and is not derived from id, so store it rather than reconstructing it. Do not infer completion from the initial response. Persist data.id and wait for the corresponding withdrawal.success, withdrawal.partial, or withdrawal.failed webhook. A parent moves from pending to processing and can remain there while item transfers settle independently; the terminal statuses are success, partial, failed, and cancelled. withdrawal.partial applies only to NGN parents with more than one bank transfer, including a single beneficiary whose amount was split above the per-transfer limit. Use GET /partner/wallets/transactions/{id} for on-demand confirmation, webhook-gap recovery, and periodic reconciliation rather than continuous polling.

Safe Retries

For an uncertain HTTP response:

Keep the same body and idempotency_key.
Generate a new timestamp and nonce.
Sign the new canonical payload.
Retry submit, then read the returned parent transaction.

The idempotency-key namespace is shared across every withdrawal currency and settlement rail for the account. The same key with the same normalized intent returns the existing parent. Reusing it for USD after NGN, for NGN after USD, or with a changed amount, destination, settlement rail, description, item order, client item value, or currency returns IDEMPOTENCY_CONFLICT. Amounts are compared as decimals, so 200000000.00 and 200000000 are the same intent.

Errors

Code	Status	Meaning
`VALIDATION_FAILED`	`400`	A field is invalid, too many items, more than one USD item, a missing USD `settlement_rail`, or a signed body over 1 MiB
`UNSUPPORTED_WITHDRAWAL_ROUTE`	`400`	Currency, rail, and destination do not form a supported route
`SIGNING_REQUIRED`	`401`	The key or required signing headers do not support signed withdrawals
`INVALID_SIGNATURE`	`401`	The signature does not verify, or the nonce, signature encoding, or signing headers are malformed
`INVALID_TIMESTAMP`	`401`	The timestamp is malformed or outside the accepted window
`INSUFFICIENT_BALANCE`	`402`	Available balance cannot cover the request. NGN reserves principal plus fee; USD debits the requested amount and takes the fee out of it
`MISSING_SCOPE`	`403`	The key is not enabled for withdrawals
`FORBIDDEN`	`403`	Production KYB is not approved
`REPLAYED_REQUEST`	`409`	The nonce was already accepted for this key
`IDEMPOTENCY_CONFLICT`	`409`	The idempotency key is already bound to another intent
`ACCOUNT_WITHDRAWAL_LIMIT_EXCEEDED`	`422`	The total principal exceeds the account policy
`SIGNING_VERIFICATION_UNAVAILABLE`	`503`	Replay protection is temporarily unavailable; fail closed and retry later

Never automatically retry a 400, 401, 402, 403, 409, or 422; correct the request, funding, or key configuration first. Retry 429 and 503 with bounded backoff and a new nonce. Requests need Content-Type: application/json. A body with an unknown field, or one that does not match the request schema, is rejected before the request is processed with a plain-text 422 and no error envelope, so branch on the status code for that case. For external payouts, subscribe to withdrawal.pending to receive a best-effort update after the payout is accepted for processing. Its transaction status is processing; continue waiting for the final withdrawal.success, withdrawal.partial, or withdrawal.failed event.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Routes

Request Signing

Test Vector

Quote NGN

Quote Response

Submit NGN

Submit USD

Response Shape

Safe Retries

Errors