Process Payouts

This guide will walk you through the process of programmatically making withdrawals (Off-Ramp) from your Busha Business crypto balances to fiat destinations like bank accounts or mobile money wallets. Payouts, like all transfers, require a Quote to define the transaction terms and a pre-configured Recipient to specify the destination.

What You’ll Achieve:

Understand the prerequisites of creating a recipient for payouts.
Generate a specific Quote for a crypto-to-fiat payout
Execute the payout transfer from your Busha crypto balance to fiat account.
Monitor the status of your payout

PrerequisitesCopied!

Before you begin, ensure you have:

A Busha Business Account and Secret API Key (from the Quick Start Tutorial).
An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the Make Your First Request Guide).
A conceptual understanding of Quotes (from the Understanding Quotes Explainer).
Familiarity with creating basic quotes (from the How to Create Your First Quote Guide)
An existing recipient ID for the bank account or mobile money wallet you wish to send funds to. If you don’t have one, please refer to the How to Create Recipients Guide.

Step 1: Create or Identify a RecipientCopied!

For bank_transfer or mobile_money payouts, Busha requires an existing recipient_id within the pay_out object of your quote. This ensures that the destination account has been previously verified and is associated with your profile, streamlining the payout process.

If you haven’t already, you must create a recipient for the specific bank account or mobile money wallet you intend to send funds to.

For detailed instructions on creating and managing recipients, please refer to the How to Create and Manage Recipients Guide.

Once you have a recipient_id, your pay_out object will look similar to this example:

    "pay_out": {
      "type": "bank_transfer", // or "mobile_money"
      "recipient_id": "677bbf9c7cf061f23784555a", // Replace your actual recipient ID
      "profile_id": "BUS_tg6yujbZ3nMu5BLQkPGGO" // Your Busha profile ID
    }

Step 2: Create a Payout QuoteCopied!

With your recipient_id in hand, the next step is to create a Quote for your payout. This quote will specify the cryptocurrency you're withdrawing from (source_currency), the fiat currency the recipient will receive (target_currency), the amount, and importantly, the pay_out object with the recipient details.

To create a payout quote:

Open your terminal or command prompt.
Construct a POST request to the /v1/quotes endpoint.
Set the type to "withdrawal".
Specify source_currency (e.g., USDT), target_currency (e.g., NGN), and either source_amount or target_amount (e.g., target_amount: "100" NGN the recipient should receive).
Include the pay_out object with the type and recipient_id you prepared in Step 1.
Replace placeholders like YOUR_BASE_URL and YOUR_SECRET_KEY.

curl -i -X POST \
  https://YOUR_BASE_URL/v1/quotes \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_currency": "USDT",
    "target_currency": "NGN",
    "target_amount": "100",
    "pay_out": {
      "type": "bank_transfer",
      "recipient_id": "677bbf9c7cf061f23784555a",
      "profile_id": "BUS_tg6yujbZ3nMu5BLQkPGGO"
    }
  }'

Expected Quote Response:

A successful response will return a Quote object, detailing the id of the quote, the calculated source_amount (how much crypto you'll need to send if you provided target_amount), the rate, associated fees, and the expires_at timestamp. Importantly, the pay_out object will include recipient_details confirming the destination account information.

{
  "status": "success",
  "message": "Created quote successfully",
  "data": {
    "id": "QUO_mprvCPMCfm3K2qSnzbWj7",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "source_currency": "USDT",
    "target_currency": "NGN",
    "source_amount": "100",
    "target_amount": "168876",
    "rate": {
      "product": "USDTNGN",
      "rate": "1690.76",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "NGN"
    },
    "fees": [
      {
        "amount": {
          "amount": "200",
          "currency": "NGN"
        },
        "name": "Fees",
        "type": "FIXED"
      }
    ],
    "pay_out": {
      "recipient_details": {
        "account_name": "SOSANYA DICKSON OLUMIDE",
        "account_number": "2109328188",
        "bank_name": "UNITED BANK FOR AFRICA",
        "country": "NG"
      },
      "recipient_id": "677bbf9c7cf061f2b784555a",
      "type": "bank_transfer"
    },
    "reference": "QUO_mprvCPMCfm3K2qSnzbWj7",
    "status": "pending",
    "expires_at": "2025-02-20T10:58:19.540052923Z",
    "created_at": "2025-02-20T10:28:19.540025003Z",
    "updated_at": "2025-02-20T10:28:19.540025003Z"
  }
}

Step 3: Create the Payout TransferCopied!

This is the final step where you initiate the actual withdrawal from your Busha crypto balance to the specified fiat recipient. You do this by creating a Transfer using the quote_id obtained in Step 2.

To create the payout transfer:

Use the POST request below to the /v1/transfers endpoint.
Include the quote_id obtained from Step 2 in the request body.
Replace YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/transfers \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "QUO_Nm2EBRxmuHGdTyGnVNDUt",
  }'

Expected Transfer Response:

A successful response will return a Transfer object, containing the same information as the quote, plus the id of the transfer (e.g., TRF_tYZ1y5bmXv4N5IhXSMbWJ) and its current status. For payouts, the status will typically start as pending and change as the payout is processed.

{
  "status": "success",
  "message": "Created transfer successfully",
  "data": {
    "id": "TRF_tYZ1y5bmXv4N5IhXSMbWJ",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "quote_id": "QUO_mprvCPMCfm3K2qSnzbWj7",
    "source_currency": "USDT",
    "target_currency": "NGN",
    "source_amount": "100",
    "target_amount": "168876",
    "rate": {
      "product": "USDTNGN",
      "rate": "1690.76",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "USDT",
      "target_currency": "NGN"
    },
    "fees": [
      {
        "amount": {
          "amount": "200",
          "currency": "NGN"
        },
        "name": "Fees",
        "type": "FIXED"
      }
    ],
    "pay_out": {
      "recipient_details": {
        "account_name": "SOSANYA DICKSON OLUMIDE",
        "account_number": "2109328188",
        "bank_name": "UNITED BANK FOR AFRICA",
        "country": "NG"
      },
      "recipient_id": "677bbf9c7cf061f2b784555a",
      "type": "bank_transfer"
    },
    "status": "pending",
    "created_at": "2025-02-20T10:28:42.376910852Z",
    "updated_at": "2025-02-20T10:28:42.376910905Z"
  }
}

Step 4: Monitor Payout StatusCopied!

For payouts, it's crucial to monitor the transfer's status to confirm successful delivery of funds to the recipient.

To monitor payout status:

Webhooks (Recommended): Set up a webhook endpoint to receive real-time notifications from Busha when the transfer status changes (e.g., from pending to completed or failed). This is the most efficient method for real-time updates.
- Refer to the How to Set Up Webhooks Guide for detailed instructions.
Polling (Less Recommended): Periodically GET the transfer status using the transfer id (TRF_tYZ1y5bmXv4N5IhXSMbWJ in the example). While possible, this is less efficient and can lead to rate limiting if done too frequently.
- curl -X GET "YOUR_BASE_URL/v1/transfers/TRF_tYZ1y5bmXv4N5IhXSMbWJ" -H "Authorization: Bearer {YOUR_SECRET_API_KEY}"

Expected Transfer Statuses:

pending: The payout is initiated and being processed.
completed: Funds have been successfully sent to the recipient's bank account or mobile money wallet.
failed: The payout failed (e.g., invalid recipient details, network issues). Funds typically return to your Busha balance.
reversed: A rare status where a completed payout is later reversed.

Troubleshooting Common Payout Issues:Copied!

"Quote expired" during transfer creation: Always generate a fresh quote immediately before attempting to create the transfer.
"Insufficient balance": Ensure your Busha account has enough source_currency to cover the source_amount in the quote.
Invalid Recipient ID: Double-check that the recipient_id in your pay_out object is correct and active. An invalid ID will cause the transfer to fail.
Payout delayed: Bank transfers can sometimes take longer than crypto transfers due to banking hours or processing times. Monitor status via webhooks. If prolonged, contact Busha support.
401 Unauthorized: Verify your Authorization header and API key.

What's Next?Copied!

Now that you know how to make payouts, you can explore other transaction types or manage recipients:

How to Create and Manage Recipient Guide: Essential for managing your payout destinations.
How to Process Fiat Deposits Guide
How to Process Crypto Deposits Guide
How to Perform Balance-to-Balance Conversions Guide
Quotes API Reference
Transfers API Reference