Payouts

The crypto asset to convert from (e.g., BTC, USDT, USDC).

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

The source of funds. Use `onchain` for blockchain deposit or `offchain` for wallet balance.

The blockchain network (e.g., BITCOIN, trc20, erc20). Required when source is `onchain`.

The crypto amount to convert. Takes priority over settlement_amount if both are provided.

The target fiat amount to receive. Ignored if amount is also provided.

Description of the payment purpose.

Your unique reference for this quote.

JSON string of custom metadata for internal tracking.

Two-letter ISO country code for the destination (e.g., NG, KE).

A globally unique identifier for the quote. This ID can be used to reference the quote in future payout requests or for auditing and logging purposes.

The current state of the quote. Typically set to 'quote', but may include other statuses depending on the lifecycle (e.g., expired, used).

The fiat currency that the recipient will receive after the crypto-to-fiat conversion. Example: 'NGN' for Nigerian Naira.

The calculated conversion rate used to determine how much fiat will be received per unit of crypto. This rate is time-sensitive and may vary across quotes.

An internal reference string for the quote that can be passed into subsequent payout endpoints. Helps in tracking and verifying quote integrity during processing.

The exact amount of fiat the user will receive, calculated based on the crypto amount and exchange rate. This is the final payout value to the end user.

The original crypto amount provided in the quote request.

Represents the Bitcoin to fiat exchange rate at the time of quote generation.

The equivalent amount in satoshis for the requested crypto amount.

The UNIX timestamp (in seconds) indicating when this quote will become invalid. After this time, the quote must be re-generated to reflect updated rates.

A human-readable message showing how long the quote is valid. Common formats include 'This quote expires in 15 minutes'.

A user-friendly summary of the quote details, such as 'NGN 327,202 will be settled for this transaction'. Often shown directly in UI confirmations.

The ID of the quote to initialize.

Unique identifier for the customer initiating the transaction.

Bank or wallet details of the recipient. Structure varies by country — use the GET /api/payouts/supported-countries/:countryCode/requirements endpoint to retrieve the correct fields.

Unique reference for this transaction.

Reason or description of the payment.

JSON string of additional metadata.

Webhook URL for transaction status updates.

Any fees applied to the payout transaction. A value of 0 means no fees were charged for this transaction.

A unique identifier assigned to the payouts transaction. You can use this ID for tracking or referencing the transaction in future API calls.

The cryptocurrency deposit address where the user should send funds. Only applicable for on-chain payments.

The blockchain network to be used for the transaction. Examples include trc20, erc20, BITCOIN, depending on the selected from_asset.

The current state of the payouts transaction. Values can include initiated, pending, completed, or failed.

An estimate of how long it will take for the fiat payout to reach the beneficiary after the transaction is confirmed.

The unique reference passed during initialization. Useful for reconciliation or auditing purposes.

The cryptocurrency asset being converted in the payouts transaction, such as USDT, USDC, or BTC.

The identifier of the quote that was previously generated and used to initialize this transaction.

A description or note about the purpose of the payment.

The fiat currency the user will receive in the payout (e.g., NGN, KES).

The rate at which the selected from_asset is converted into the settlement fiat currency. This rate was locked during quote generation.

A UNIX timestamp representing when the initialization request or quote will expire. After this, a new quote will be required.

The original crypto amount to be paid by the customer.

The equivalent amount of the crypto asset in BTC, used for internal calculations or when the user is paying in BTC.

The equivalent Bitcoin amount in satoshis (1 BTC = 100,000,000 satoshis). Useful when using precise crypto payments.

A human-readable string showing how much time is left before the transaction or quote expires.

Contains all verified and saved information about the payout beneficiary. Fields include: id, status (e.g., success, pending), country (ISO code), currency (e.g., NGN), created_at, updated_at, reference, and destination (account details).

Contains the actual payout account details. Fields include: type (e.g., BANK), bank_code, account_name, and account_number.

The total amount the beneficiary will receive in their local fiat currency after all conversions and fees.

Two-letter ISO country code (e.g., NG, KE).

The beneficiary's account number.

The bank code for the account.

The account type (e.g., bank_account).

Indicates whether the lookup was successful.

The name registered to the provided account number.

The validated account number.

The bank code associated with the account.

The ID of the quote to simulate deposit for.

The amount of crypto to simulate.

A simulated transaction hash.

Indicates whether the simulation request was successful.

A human-readable message describing the result of the simulation.

Indicates whether the simulated deposit was accepted successfully and the payouts process is progressing.

The ID of the quote to finalize.

Sort order of results. Can be `ASC` (oldest to newest) or `DESC` (newest to oldest).

Page number for paginated results. Defaults to 1.

Number of results to return per page. Default is 10.

Unique identifier for the payout transaction.

ISO 8601 timestamp indicating when the payout was created.

ISO 8601 timestamp showing the last time the payout record was updated.

Identifier linking this payout to its original quote.

Unique identifier of the company that initiated the payout.

Unique identifier of the customer linked to this payout.

Description provided for the payout, e.g., 'Invoice Payment' or 'Business'.

A unique reference string used for reconciliation or tracking.

Webhook or callback URL provided to receive async updates. Null if not used.

Identifier linking the payout to a beneficiary record.

The current status of the payout. Example values include success, expired, pending, failed.

Optional metadata provided by the client. Empty object if none is supplied.

The equivalent value of the crypto in satoshis (1 BTC = 100,000,000 sats).

The equivalent value of the crypto in BTC format.

The amount of crypto provided in the payout request.

The amount represented in the smallest fiat unit (e.g., cents for USD, kobo for NGN).

The final fiat amount the beneficiary receives after conversion.

Any fees applied to the payout, expressed in the smallest fiat unit. '0' means no fee.

Any fees applied to the payout transaction in standard fiat units.

The deposit address (if applicable). Null for off-chain payouts.

The funding source for the payout, e.g., 'offchain' or 'onchain'.

The cryptocurrency used for the payout, e.g., USDT, USDC, BTC.

The blockchain network used for the transaction, e.g., trc20, erc20, BITCOIN.

The fiat currency in which the beneficiary will be paid, e.g., NGN, KES.

Estimated delivery time for the payout, e.g., '3-5 minutes'.

The ISO 8601 timestamp when this payout quote or transaction expires.

Conversion details including the applied rate, fiat currency, and BTC-specific fields if applicable.

Information about the payout beneficiary including ID, country, currency, and account details.

The actual account or wallet where funds are delivered, e.g., bank account or mobile money wallet.

Timeline information describing when the payout was submitted, initialized, processed, and completed.

Details of the company initiating the payout, including name, country, type, and compliance data.

A set of feature flags showing which actions the company can perform on the platform.

Pagination details including page number, item count, page count, and navigation flags.

The unique identifier of the quote you want to fetch.

The unique internal ID of the quote transaction that was previously generated. This ID is required to retrieve full details.

Unique transaction reference that identifies the specific quote you want to retrieve.

The ISO 3166-1 alpha-2 country code for the target country (e.g., 'NG' for Nigeria, 'KE' for Kenya).

Indicates if the API request was processed successfully.

A human-readable message describing the result of the request.

The ISO 3166-1 alpha-2 country code of the target country. For example, 'KE' for Kenya, 'NG' for Nigeria.

The full official name of the country (e.g., 'Kenya', 'Nigeria').

The country's flag represented as a Unicode emoji character.

The international telephone dialing code for the country. For example, '254' for Kenya or '234' for Nigeria.

An object representing the payout destination types supported by the country (e.g., 'BANK', 'MOBILEMONEY'). Each key maps to an array of field requirement objects necessary to initiate a payout to that destination type.

Indicates whether the request to retrieve transaction limits was successful.

A message describing the result of the request.

The minimum allowable payouts transaction amount in the country's local currency. Any transaction below this amount will be rejected.

The maximum allowable payouts transaction amount in the country's local currency. Transactions above this limit are not permitted.

The local currency in which the limits are defined.

The two-letter ISO 3166-1 alpha-2 code representing the country (e.g., 'NG' for Nigeria, 'GH' for Ghana).

The real-time exchange rate between the local currency and USD.

The minimum transaction amount converted to USD using the current exchange rate.

The maximum transaction amount converted to USD based on the current exchange rate.