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.

Prerequisites

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.

For payout requests involving a customer, the X-BU-PROFILE-ID field should be included in the request header, and its value should be set to the customer ID for whom the request is performed on their behalf.

Step 1: Create or Identify a Recipient

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
    }

Step 2: Create a Payout Quote

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",
    }
  }'

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 Transfer

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 Status

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 Statutes:

pending : Transfer initiated, awaiting user bank transfer.
processing: This means the funds has been received, and is being handled.
funds_delivered: Funds have been successfully received and credited to your Busha balance.
cancelled: the transfer has been cancelled, and will not continue.

Troubleshooting Common Payout Issues:

"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?

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