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

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 exact compact body for that vector is:

{
  "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"
}

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 quote for 200000000.00 NGN reports two transfers because no individual bank transfer exceeds 100000000.00 NGN. The parent amount, fee, and debit remain aggregate values.

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.

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; unsupported combinations return UNSUPPORTED_WITHDRAWAL_ROUTE.

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.

{
  "status": "success",
  "data": {
    "id": "0197f1f0-0000-7000-8000-000000000014",
    "status": "processing",
    "rail": "fiat",
    "currency": "NGN",
    "tx_type": "withdrawal",
    "amount": "200000000.00",
    "reference": "WD-0197f1f000007000",
    "fee": "500.00",
    "debit_amount": "200000500.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": "pending" },
          { "sequence": 2, "amount": "100000000.00", "status": "pending" }
        ]
      }
    ]
  }
}

Do not infer completion from the initial response. Persist data.id and wait for the corresponding withdrawal.success or withdrawal.failed webhook. A parent can remain processing while item transfers settle independently. 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, description, item order, client item value, currency, or settlement rail returns IDEMPOTENCY_CONFLICT.

Errors

Code	Meaning
`MISSING_SCOPE`	The key is not enabled for withdrawals
`SIGNING_REQUIRED`	The key or required signing headers do not support signed withdrawals
`INVALID_SIGNATURE`	The canonical payload or signature does not match
`INVALID_TIMESTAMP`	The timestamp is malformed or outside the accepted window
`REPLAYED_REQUEST`	The nonce was already accepted for this key
`SIGNING_VERIFICATION_UNAVAILABLE`	Replay protection is temporarily unavailable; fail closed and retry later
`IDEMPOTENCY_CONFLICT`	The idempotency key is already bound to another intent
`ACCOUNT_WITHDRAWAL_LIMIT_EXCEEDED`	The aggregate parent amount exceeds the account policy
`INSUFFICIENT_BALANCE`	Available balance cannot cover principal plus fee
`UNSUPPORTED_WITHDRAWAL_ROUTE`	Currency, rail, and destination do not form a supported route

Never automatically retry MISSING_SCOPE, INVALID_SIGNATURE, IDEMPOTENCY_CONFLICT, or UNSUPPORTED_WITHDRAWAL_ROUTE. Correct the request or key configuration first.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Routes

Request Signing

Test Vector

Quote NGN

Submit NGN

Submit USD

Response Shape

Safe Retries

Errors

​Routes

​Request Signing

​Test Vector

​Quote NGN

​Submit NGN

​Submit USD

​Response Shape

​Safe Retries

​Errors

Routes

Request Signing

Test Vector

Quote NGN

Submit NGN

Submit USD

Response Shape

Safe Retries

Errors