Process Crypto Payouts

This guide will walk you through the process of programmatically making crypto withdrawals (Off-Ramp) from your Busha Business crypto balances. 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-crypto payout.
Execute the payout transfer from your Busha crypto balance to your crypto wallet.
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)

Step 1: Prepare Your Quote ObjectCopied!

For crypto payouts, Busha requires a valid address, network and memo (for networks that mandate a memo for cryptocurrency transactions) in the pay_out object of your quote.

Your pay_out object should look like this:

"pay_out": {
  "type": "address",
  "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
  "network": "BTC"
}

The network type must be in uppercase, e.g., BTC, USDT, TRX.

Step 2: Create a Payout QuoteCopied!

The next step is to create a Quote for your payout. This quote will specify the cryptocurrency you're withdrawing from (source_currency), the cryptocurrency 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., BTC), target_currency (e.g., BTC), and either source_amount or target_amount (e.g., target_amount: "100" the recipient should receive).
Include the pay_out object 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": "BTC",
    "target_currency": "btc",
    "target_amount": "0.0001",
    "pay_out": {
      "type": "address",
      "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
      "network": "BTC"
    }
  }'

For sandbox requests, you can obtain test addresses from any of the providers listed in the Test Addresses reference.

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_mZrlSnIFzGkA",
    "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "target_amount": "0.0001",
    "rate": {
      "product": "",
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_out": {
      "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
      "network": "BTC",
      "type": "address"
    },
    "reference": "QUO_mZrlSnIFzGkA",
    "status": "pending",
    "created_at": "2025-06-18T16:58:12.762193733Z",
    "updated_at": "2025-06-18T16:58:12.762193733Z"
  }
}

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 crypto wallet. 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_KEY with your actual details.

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

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_4VJeKDm6Ow2V",
    "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
    "quote_id": "QUO_mZrlSnIFzGkA",
    "description": "Sold BTC",
    "sub_description": "For BTC",
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "target_amount": "0.0001",
    "rate": {
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_out": {
      "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
      "network": "BTC",
      "type": "address"
    },
    "status": "pending",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-06-18T17:00:37.695327321Z",
    "updated_at": "2025-06-18T17:00:37.695327373Z"
  }
}

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_4VJeKDm60w2V" -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.
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: