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.

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).

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: Prepare Your Quote Object

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 Quote

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 Transfer

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