Payouts

The source of funds for the payouts. Use offchain for wallet or onchain to generate a blockchain address.

The asset to convert from. Accepted values include: usdt, usdc, btc.

The target fiat currency. Examples: NGN (Naira), KES (Kenyan Shilling), AUD (Australian Dollar).

The blockchain network to be used. Optional values: trc20, erc20, lightning, mainnet.

Amount to convert, in the smallest denomination (e.g., cents, satoshis). Takes priority over settlementAmount if both are provided.

Target amount to receive after conversion. Ignored if amount is also provided.

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. This value is typically in the smallest unit of the asset (e.g., cents).

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.

ID of the previously generated quote to base this transaction on.

Unique identifier for the customer initiating the transaction.

Country code where the payout should be made (Currently supported: NG Nigeria,KE Kenya,AU Australia).

Unique reference for this transaction. Useful for tracking.

Reason or description of the payment.

ID of an existing beneficiary (optional if beneficiary is provided).

Bank or wallet details of the recipient (required if beneficiaryId not used).It's an Object containing bank account details (use country requirements endpoint to get the correct structure per country)

Webhook URL for transaction status updates.

Additional metadata for internal reference or tracking.Any valid JSON object

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 or lightning network payments.

The blockchain network to be used for the transaction. Examples include trc20, erc20, lightning, or mainnet, depending on the selected fromAsset.

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. This is useful for reconciliation or auditing purposes in your system.

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. Helps tie the payout to a fixed rate.

A description or note about the purpose of the payment. This field is passed by the client and appears in the transaction metadata.

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

The rate at which the selected fromAsset 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. For stablecoins like USDT this is expressed in whole units (e.g., 200 USDT). For Bitcoin transactions, the satoshi equivalent is provided in satAmount.

The equivalent amount of the crypto asset in BTC (Bitcoin), 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 Lightning Network or precise crypto payments.

A human-readable string showing how much time is left before the transaction or quote expires, such as '15 minutes remaining'.

Contains all verified and saved information about the payout beneficiary. Fields include: id (unique record ID), status (e.g., success, pending), country (ISO code), currency (e.g., NGN), createdAt / updatedAt (timestamps), reference (internal link to quote/transaction), and destination (account details).

Contains the actual payout account details. Fields include: type (e.g., BANK, WALLET), bankCode (code of the bank), accountName (name on the account), and accountNumber (recipient’s account number).

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

The ID of the payouts quote previously created via the /payouts/quotes endpoint. This identifies the quote to finalize.

The blockchain address provided in the finalized quote. Funds are simulated as deposited to this address.

The crypto amount (in smallest denomination or as specified) to simulate as deposited. Must match the finalized quote.

Indicates whether the simulation request was successful. A value of true confirms that the simulation went through.

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

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

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, lightning.

The fiat currency in which the beneficiary will be paid, e.g., 'usd' or 'ngn'.

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 (payouts, transfers, etc.).

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

The unique identifier of the quote you want to fetch.

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

The country to retrieve beneficiary requirements for. Accepts full name (e.g. 'Nigeria'), ISO code (e.g. 'NG'), or dial code (e.g. '234').

A boolean value indicating if the API request was processed successfully. A value of true means the country requirements were retrieved without error.

A human-readable message describing the result of the request. Useful for debugging or confirmation messages.

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

The full official name of the country (e.g., 'Kenya', 'Nigeria'). This helps with display purposes in interfaces.

The country's flag represented as a Unicode emoji character. It can be used in UI to visually represent the country.

The international telephone dialing code for the country. For example, '254' for Kenya or '234' for Nigeria. Can be used to validate phone numbers.

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. These fields include metadata like field name, type, whether it's required, and sometimes specific constants or enum values (e.g., for networks like MPESA).

Indicates whether the request to retrieve transaction limits was successful. A value of true means the data was retrieved without errors.

A message describing the result of the request. Typically used to confirm success or provide an error description.

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. This helps determine the denomination applicable to lower and upper bounds.

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

The real-time exchange rate between the local currency and USD. This rate is used to compute the USD equivalent of the defined limits.

The minimum transaction amount converted to USD using the current exchange rate. Useful for applications working primarily with USD values.

The maximum transaction amount converted to USD based on the current exchange rate. Helps standardize limits across different countries.