Payouts

Crypto amount to convert, expressed as a decimal string in the source asset (e.g. '10' = 10 USDC). Takes priority over settlement_amount when both are provided.

Target fiat amount you want the beneficiary to receive. Ignored when amount is also provided.

Two-letter ISO 3166-1 alpha-2 country code for the destination (e.g. 'NG', 'KE', 'GH'). Must be one of the codes returned by GET /api/payouts/supported-countries.

Crypto asset you're debiting from your wallet: 'BTC', 'USDT', or 'USDC'.

Target fiat currency code the beneficiary will receive (e.g. 'NGN', 'KES', 'GHS'). Must be a currency supported on the chosen country.

Source of funds (lowercase). 'offchain' debits your Bitnob wallet balance directly; 'onchain' expects a blockchain deposit to cover the quote.

Blockchain network used when source is 'onchain' (e.g. 'BITCOIN', 'trc20', 'erc20'). Omit when source is 'offchain'.

Client-generated unique identifier for this quote. Reused on initialize and finalize for idempotency and reconciliation.

A globally unique identifier for the payout. Used to reference this payout in future requests.

An internal reference string for the quote, passed into subsequent payout endpoints.

The unique identifier of the company that created the quote.

The current state of the quote (e.g., 'QUOTE'). Changes as the payout progresses through its lifecycle.

The source of funds used for the payout (e.g., 'OFFCHAIN' for wallet balance, 'ONCHAIN' for blockchain deposit).

The crypto asset being converted (e.g., 'USDT', 'BTC', 'USDC').

The blockchain network for the transaction (e.g., 'CHAIN_TYPE_ETHEREUM', 'CHAIN_TYPE_BITCOIN').

The target fiat currency code (e.g., 'GHS', 'NGN').

The original crypto amount provided in the quote request.

The exact amount of fiat the recipient will receive after conversion.

The equivalent amount in satoshis for the requested crypto amount.

The equivalent BTC amount for the requested crypto amount.

The fee charged for this payout in the from_asset currency.

Contains the conversion rate details: 'rate' (crypto to fiat), 'btc_rate' (BTC to fiat), and 'currency'.

Your unique reference string for this quote.

Two-letter ISO country code for the destination.

Timestamp indicating when this quote expires. After this time, the quote must be re-generated.

Timestamp when the quote was created.

The ID of the quote returned by Create Payouts Quote (e.g. 'QT_100003'). Must not be expired.

The quote you're initializing. Must match the :quoteId path parameter.

Client-generated unique identifier for this payout. Reused on Finalize for idempotency and reconciliation.

Short reason code for the payment (e.g. 'salary', 'vendor_payment', 'family_support'). Some corridors require a value from a fixed list — check Get Country Details.

HTTPS URL that will receive payout lifecycle webhooks (completed, failed).

Recipient details. Shape depends on destination_type (bank, mobile_money, swift). For SWIFT, populate the bank fields, a nested beneficiary address, and a nested sender identity.

Rail selector: 'bank', 'mobile_money', or 'swift'.

Two-letter ISO country code of the destination account.

Name on the destination account. Use the value returned by Account Lookup when available.

Bank account number (or IBAN for SWIFT corridors).

Provider code from Get Banks. Required for 'bank' and 'mobile_money' destination types.

BIC/SWIFT code of the destination bank. Required when destination_type is 'swift'.

Display name of the destination bank. Required for SWIFT.

Physical address of the destination bank branch. All required for SWIFT.

Regulator-visible reason code (e.g. 'salary_payment', 'family_support'). Required for SWIFT.

Physical address of the recipient (country, city, post_code, address). Required for SWIFT.

Identity of the sender. type is 'business' or 'individual'. Business senders provide registration_number; individual senders provide date_of_birth and country_of_birth.

Top-level flag indicating whether the request was processed successfully.

Human-readable status message.

The initialized payout record.

Unique identifier for this payout. Pass it as :id to GET /api/payouts/:id or as the path param on Finalize is keyed off quote_id (see Finalize).

The quote that was locked (echoed from the request).

Lifecycle state. 'INITIATED' after a successful initialize; transitions through processing states to 'COMPLETED' or 'FAILED' after Finalize.

Source of funds (from the original quote). 'SOURCE_UNSET' when source was not explicitly set.

Crypto asset being debited (e.g. 'USDT', 'USDC', 'BTC').

Destination fiat currency (e.g. 'GHS', 'NGN').

Crypto amount being sent, as a decimal string in from_asset units.

Fiat amount the beneficiary will receive after conversion.

Equivalent amount expressed in BTC for internal pricing.

Equivalent amount expressed in satoshis.

Total fees applied to the payout, as a decimal string in the source asset.

Total fees expressed in cents / smallest fiat unit.

Locked FX details: rate (from_asset → to_currency), btc_rate (for BTC pricing), currency (display).

The full beneficiary object echoed back from the request for auditability.

Reason code provided on the request.

Reference provided on the request.

RFC 3339 / ISO 8601 timestamp. Call Finalize before this time or re-request a quote.

Set once the payout is fully persisted downstream. May be null immediately after initialize.

Request identifier for log correlation and support.

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Two-letter ISO country code of the destination account (e.g. 'NG', 'KE', 'GH').

Bank or mobile-money provider code from GET /api/payouts/banks/:countryCode.

Account or mobile number to resolve.

Name registered on the resolved account. Use this value as account_name when constructing the beneficiary on Initialize.

Echo of the account number that was resolved.

Normalized bank code from the underlying rail (may differ from the input bank_code).

Display name of the resolving bank or mobile-money provider.

Two-letter ISO country code of the resolved account.

True when the rail successfully resolved a name for the account; false when the account couldn't be verified.

The ID of the quote to finalize.

Transitions from 'INITIATED' to 'PENDING' on finalize, then on to 'COMPLETED' or 'FAILED' once the rail settles. Watch the webhook for the terminal state.

Populated from the quote (e.g. 'OFFCHAIN', 'ONCHAIN'). 'SOURCE_UNSET' is replaced with the real source at finalize.

The company the payout is debited from (populated at finalize).

Settlement amount in cents / smallest fiat unit.

Echoed from the initialize request — URL that will receive lifecycle webhooks.

Identifier returned by the downstream rail (e.g. SWIFT provider / bank). Use it for reconciliation with the provider.

Destination country (populated at finalize, e.g. 'GH').

Timestamps of each milestone in the payout's journey: quote_at, initialized_at, and (on completion) finalized_at.

When the quote was created.

When the beneficiary was attached and the payout was initialized.

Now populated (not null) — the payout has been persisted through the finalize pipeline.

Maximum number of payouts to return in a single page. Default 20.

Number of records to skip from the start of the result set. Use with total_count to paginate (e.g. offset=20 for page 2 with limit=20).

Page of payout records. Each entry uses the same shape as the Initialize / Finalize response — refer to those sections for per-field explanations.

Total number of payouts for your company across all pages.

Echo of the limit applied to this page.

Echo of the offset applied to this page.

True when offset + limit < total_count — i.e. more records are available beyond this page.

Lifecycle state of the payout: 'QUOTE' (quote created, not initialized), 'INITIATED', 'PENDING' (awaiting settlement), 'COMPLETED', or 'FAILED'.

Milestone timestamps. 'QUOTE'-status rows only carry quote_at; initialized_at and finalized_at populate as the payout progresses.

Request identifier for log correlation and support.

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

The payout's internal identifier (from data.payout.id on Initialize / Finalize, or data.items[].id on List Payouts). Not the quote_id.

Full list of countries payouts are supported in.

ISO 3166-1 alpha-2 country code (e.g. 'GB', 'NG').

Display name of the country.

Country flag emoji for UI rendering.

International dial prefix. Occasionally a comma-separated list when the country has multiple (e.g. DO → '1809,1829,1849').

Supported payout corridors for this country. Each entry pairs a currency with the destination types available for that currency.

ISO 4217 currency code (e.g. 'USD', 'EUR', 'GHS').

Payout rails available for this (country, currency) pair. See the list above for possible values.

ISO 3166-1 alpha-2 country code — must appear in Get Supported Countries (e.g. 'CN', 'NG', 'GB').

Country identity block — same shape as entries in Get Supported Countries.

Map keyed by rail name (e.g. 'bank', 'swift', 'alipay', 'wechatpay', 'mobile_money'). Each value is the full field schema for that rail.

Human-readable label for the rail (e.g. 'Bank Transfer', 'International Wire (SWIFT)').

Ordered list of fields required on the beneficiary for this rail. Each field carries key/label/type/required/component plus optional pattern/min_length/max_length/placeholder/options. Fields of type 'group' contain nested fields; type 'variant' is a discriminated union keyed by variant_key.

Populated for rails that require a bank selector (e.g. 'bank'). Same shape as Get Banks.

Per-rail amount limits: min_amount, max_amount, currency.

Two-letter ISO country code (e.g. 'NG', 'KE', 'GH'). Must be one of the codes returned by Get Supported Countries.

Echo of the ISO country code you requested.

Display name of the country (e.g. 'Nigeria').

Total number of bank / provider entries returned (e.g. Nigeria returns 358).

Banks and mobile-money providers supported in the country. Typically sorted alphabetically by bank_name.

Provider code — pass this as bank_code on Account Lookup and as the beneficiary's bank_code on Initialize.

Display name of the bank or mobile-money provider (e.g. 'Access bank', 'PAYSTACK PAYMENTS LIMITED').

One entry per (country, currency) corridor. Countries that support multiple currencies (e.g. GB supports both EUR and GBP) return one limit per currency.

ISO 3166-1 alpha-2 country code (e.g. 'NG', 'GH', 'GB').

ISO 4217 currency code for this corridor (e.g. 'NGN', 'GHS', 'GBP').

Minimum amount for a single payout, expressed as a decimal string in the local currency.

Maximum amount for a single payout, expressed as a decimal string in the local currency.

min_amount converted to USD using the current exchange rate. Useful for validating USD-denominated amounts client-side without calling a conversion endpoint.

max_amount converted to USD using the current exchange rate.

SWIFT payload — see the three tables below. Validated against the corridor's field schema for (country, destination_type=swift).

Client-set idempotency / tracking reference. Overrides or supplements the quote's reference.

Short reason code for the payment (free text at this level).

Per-payout webhook URL override.

Optional link to a persisted customer record.

Arbitrary client metadata string.

Set to 'swift' (lowercase). Selects the SWIFT wire rail.

ISO 3166-1 alpha-2 of the destination account. Must match the country on the quote.

Recipient name. Must have ≥2 space-separated parts, each ≥2 chars. No honorifics (Mr/Mrs/Dr). No single-letter-plus-dot (e.g. 'J. Doe' is rejected; 'John Doe' passes).

For IBAN countries (GB, DE, AT, AD, BE, BG, CH, FR, …): IBAN format, 15–34 chars, ^[A-Z0-9]+$. For non-IBAN countries (AR, BW, CN, …): plain account number, 5–34 chars.

8 or 11 chars, ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$. Uppercase only. HK uses a stricter pattern that pins chars 5–6 to literal 'HK'.

Display name of the destination bank.

Street address of the destination bank branch.

City of the destination bank branch.

Postal / ZIP code of the destination bank branch.

ISO 3166-1 alpha-2 of the destination bank's country.

Lowercase snake_case value from the remittance purposes enum (see reference below).

Recipient's physical address (nested object — see table below).

Sender identity, discriminated by `type` ('business' or 'individual'). See table below.

ISO 3166-1 alpha-2 of the recipient.

City.

Postal / ZIP code.

Street address.

'business' or 'individual' (case-insensitive, normalised server-side).

Legal name of the sender (same name-validation rules as recipient account_name).

Sender's ISO 3166-1 alpha-2 country code.

Sender's city.

Sender's street address.

Sender's postal code.

Business registration / tax ID, 2–30 chars. REQUIRED when type='business'; ignored for individuals.

YYYY-MM-DD. REQUIRED when type='individual'.

ISO 3166-1 alpha-2. REQUIRED when type='individual'.

Australia: 6-digit BSB code, pattern ^\d{6}$. The corridor placeholder shows '062-000' but dashes are NOT accepted — strip them ('062000').

India: 11-char IFSC code, pattern ^[A-Z]{4}0[A-Z0-9]{6}$. Note the key is `IFSCode` (camelCase) — unlike every other field in the payload. Sending `ifs_code` or `ifsc_code` silently fails validation.

Hong Kong uses a stricter SWIFT regex: ^[A-Za-z]{4}HK[A-Za-z0-9]{2}([A-Za-z0-9]{3})?$ — chars 5–6 are pinned to literal 'HK'. Case-insensitive on HK only.

Rwanda and Singapore require `type` ('business' or 'individual') on the nested beneficiary object.