Payouts
The Payouts APIs allow users to convert crypto assets like USDT, USDC, or BTC into local fiat currencies (e.g., NGN, KES, AUD). They include endpoints for creating quotes, processing payouts, simulating deposits (sandbox), and retrieving payout details or country requirements—supporting seamless crypto-to-cash transfers.
Create Payouts Quote
This endpoint generates a quote for converting cryptocurrency into fiat currencies through Bitnob’s payoutsing system. It helps you understand the exchange rate and amount receivable before actually executing the transaction.
Create Payouts Quote Request
Specifies the response format expected by the client. Should be set to application/json.
Specifies the media type of the request payload. Must be application/json.
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.
Create Payouts Quote Response
Indicates whether the quote was successfully generated. A value of true means the system was able to calculate a valid conversion quote using the provided parameters.
A message from the API confirming the result of the quote generation process. Useful for providing user-facing feedback such as 'Payouts quote generated successfully'.
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., satoshis, cents).
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.
Initialize Payouts Quote
This endpoint allows you to initialize a payout transaction after generating a quote. You can provide either an existing beneficiary's ID or a full beneficiary object. Once initialized, it returns the payment details and transaction metadata required to complete the payouts.
Initialize Payouts Quote - Request
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
Initialize Payouts Quote - Response
Indicates if the initialization request was successful. A value of true confirms the transaction setup proceeded without issues.
A human-readable response message from the API. Typically used to confirm that the initialization was successful or describe any errors.
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. Usually expressed in the smallest denomination (e.g., cents or satoshis).
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'.
An object containing all verified and saved information about the beneficiary. Includes account name, number, bank code, and internal ID.
The total amount the beneficiary will receive in their local fiat currency after all conversions and fees (if applicable).
Finalize Payouts Quote
This endpoint is used to finalize an already initialized payouts quote. Once a quote has been initialized (with the beneficiary and all required details), this final step makes it actionable. It generates a deposit address (for on-chain flows) where the customer can send the crypto, and triggers the process that results in the fiat being sent to the selected beneficiary. Use this right before showing the user payment instructions.
Finalize Quote Request
The media type of the response body. Set this to application/json to receive structured JSON responses.
The media type of the request payload. Must be application/json.
The ID of the payouts quote previously created via the /payouts/quotes endpoint. This identifies the quote to finalize.
Finalize Quote Response
Indicates whether the finalize operation was successful. If true, the payouts quote is now active and awaiting payment.
A confirmation message from the server. Usually indicates successful finalization.
Unique identifier of the finalized payouts transaction. Use this to track the payout.
Any network or service fees associated with the transaction, returned in fiat currency units.
The blockchain network selected for the crypto deposit (e.g., trc20, erc20).
The crypto amount to be paid, expressed in the smallest unit (e.g., cents, satoshis).
Current lifecycle state of the payout (e.g., pending_address_deposit). Use this to track progress.
Blockchain address where the customer should send the crypto. This address is tied to the finalized quote.
The same quote ID used during initialization and now finalized for payment.
The equivalent BTC amount (if asset is BTC or converted internally for tracking).
The equivalent value in satoshis (smallest BTC unit).
The crypto asset being payoutsed (e.g., usdt, btc, usdc).
The unique transaction reference provided during quote initialization for external tracking.
Estimated time in which the fiat payout will be received by the beneficiary after payment confirmation.
Rate used to convert crypto into fiat. This value is locked in from the quote.
User-friendly text showing how much time is left before the quote expires.
Purpose of the payment as provided by the sender. Useful for audit and compliance.
UNIX timestamp indicating when the payment quote will expire and no longer be valid.
The exact amount of fiat currency that will be received by the beneficiary after conversion and fees.
Full details of the recipient, including bank information, verification status, and country of residence.
Fiat currency the beneficiary will receive, based on quote and country.
Simulate Address Deposit
This endpoint is used only in the sandbox environment to simulate a crypto deposit to the blockchain address provided after quote finalization. It mimics the user sending crypto to Bitnob's generated address to trigger fiat settlement for testing purposes.
Use this after finalizing an payouts quote to test the full payouts payout flow without moving real funds.
Simulate Address Deposit Request
Must be application/json to ensure correct data formatting.
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.
Simulate Address Deposit Response
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.
Get All Quotes
This endpoint retrieves all payouts quotes initiated under your company's account. It supports pagination, sorting, and returns comprehensive data on each transaction, including quote info, status, amounts, associated customers, beneficiaries, and metadata.
Use it to list recent or historical payouts activities for reporting, reconciliation, or transaction tracking.
Get All Quotes Request
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.
Get All Quotes Response
Returns a list of payouts quotes and associated metadata including pagination details. Each quote object contains transaction details such as quote ID, customer, settlement data, status, and crypto conversion details.
Indicates whether the request to fetch all payouts quotes was successful. True means the request was processed and a response was returned.
A descriptive message from the server about the outcome of the request. Usually confirms success or describes an error.
An array of payouts quote objects. Each object contains detailed information about a specific payouts transaction.
Unique identifier for the payouts transaction. Can be used to retrieve more details or perform further operations.
Identifier that links this payouts to its original quote. Useful for tracking and referencing the transaction’s lifecycle.
Current status of the payouts transaction. Example values include expired, pending, underpayment, completed.
User-defined reference for the transaction, typically used for reconciliation, tracking, or correlating with internal records.
The conversion rate used to calculate the fiat equivalent of the crypto asset during the payouts quote generation.
Fiat currency used in the settlement. Example: ngn for Nigerian Naira.
Name of the recipient associated with the bank account that will receive the fiat funds after settlement.
Bank account number for the beneficiary where the converted fiat will be deposited.
Timestamp (UNIX format) representing when the payouts transaction was first submitted by the client.
Amount of crypto (e.g., USDT) to be converted. Value is typically represented in whole units (not cents).
Final fiat amount (in lowest denomination, e.g., kobo for NGN) the user will receive after all calculations are done.
Blockchain network over which the crypto was sent. Example values include trc20.
The type of cryptocurrency used for the transaction. For example, usdt, btc, or usdc.
Current page of the paginated result. Used to navigate through large datasets returned from the server.
Number of items returned per page. This defines the size of each paginated set of results.
Total number of items (payoutss) matching the request criteria.
Total number of pages based on the itemCount and take values. Useful for rendering pagination UI.
true if there is a page before the current one, useful for enabling/disabling 'Previous' pagination buttons.
true if there are more results available on the next page.
Get Quote by QuoteId
This endpoint allows you to fetch detailed information about a previously generated payouts quote using its unique quoteId. This is useful for checking the status, parameters, and settlement details of the quote.
Path Parameters
The unique identifier of the quote you want to fetch.
Response Fields
Indicates whether the request to retrieve the quote was successful. A value of `true` means the operation succeeded without errors.
A human-readable string describing the result of the API call. Usually used for confirmation or debugging.
The unique identifier of the payouts transaction. Useful for tracking and referencing the specific payout.
Timestamp (in ISO format) indicating when the quote was initially created.
Timestamp showing the last time any update was made to this quote's record.
The internal quote reference code generated when the quote was created. Used to finalize or simulate the quote.
The unique ID of the company associated with this quote. Indicates which company initiated or owns the transaction.
The UUID representing the customer for whom this payouts quote was generated.
A custom reason for the payment, typically provided by the user or platform to describe the purpose of the transaction.
A unique alphanumeric string used to reference the quote transaction, typically used for internal tracking or reconciliation.
The webhook URL that Bitnob will call with updates to the transaction's status, if provided.
The unique ID of the beneficiary associated with the payout. Beneficiaries contain destination bank details or wallet info.
The current status of the quote transaction. Common values include `initiated`, `expired`, `completed`, or `pending_address_deposit`.
The exchange rate used to convert the crypto asset into the target fiat currency at the time of quote creation.
The fiat currency used in the settlement, represented in ISO 4217 format (e.g., `NGN` for Nigerian Naira).
The unique identifier for the beneficiary object, which includes full details about the payout destination.
Indicates whether the beneficiary has been successfully verified or not (e.g., `success`, `failed`).
The country code (ISO 3166-1 alpha-2) representing the beneficiary's country. For example, `NG` for Nigeria.
Timestamp indicating the last update made to the beneficiary record.
The type of destination account. Currently `BANK` is supported, indicating a bank transfer payout.
The bank code of the beneficiary’s financial institution.
The account number of the beneficiary. It may be masked for security purposes in the response.
UNIX timestamp (in seconds) indicating when the quote was initially sent to the user.
UNIX timestamp indicating when the quote was initialized for a payout request.
UNIX timestamp representing when the payout was completed.
Custom metadata field capturing the name associated with the transaction, typically user-provided.
Another example of metadata, stored as a string, could represent any user-defined detail.
The crypto amount expressed in satoshis (smallest unit of Bitcoin). A string to preserve precision.
The crypto amount converted to BTC equivalent at the time of the quote.
The amount of crypto being payoutsed, in the original asset's denomination (e.g., 1000 USDT).
The fiat equivalent of the amount in the smallest unit (e.g., cents for USD or kobo for NGN).
The total amount that will be received by the beneficiary after conversion and fees.
Any transaction fees charged, expressed in the smallest denomination of the currency (e.g., cents or kobo).
The total fee amount for the transaction, expressed in standard currency units.
The crypto deposit address assigned for this transaction. May be null if address is not required.
Indicates the source of crypto funds. Typically onchain for blockchain deposits.
The type of crypto asset used for the transaction (e.g., usdt).
The blockchain network on which the transaction is processed (e.g., trc20, erc20).
The fiat currency that the crypto will be converted into (e.g., ngn).
Estimated time range for when the payment will reach the beneficiary, usually stated in minutes.
The expiration timestamp for this quote. After this time, the quote becomes invalid and cannot be used.
Get Quote by Id
Get a quote by it's id
Path Parameters
The unique internal ID of the quote transaction that was previously generated. This ID is required to retrieve full details.
Get Quote by Reference
This endpoint allows you to retrieve a specific payouts quote using its unique reference. It's especially useful for systems that track transactions using external reference IDs rather than internal IDs or quoteIds.
Path Parameters
Unique transaction reference that identifies the specific quote you want to retrieve.
Get Country Requirements
Get the beneficiary requirements for all supported countries.
Path Parameters
The country to retrieve beneficiary requirements for. Accepts full name (e.g. 'Nigeria'), ISO code (e.g. 'NG'), or dial code (e.g. '234').
Response Fields
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).
Get Transaction Limits
This endpoint returns the minimum and maximum allowable transaction amounts for payouts operations per supported country. It provides limits in local currency as well as their equivalent values in USD based on real-time exchange rates.
Use this endpoint to validate or display country-specific limits before initiating a payout.
Response Fields
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.