> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Process Payouts
> Send payouts to bank accounts and mobile money.
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:**
1. Understand the prerequisites of creating a recipient for payouts.
2. Generate a specific Quote for a crypto-to-fiat payout.
3. Execute the payout transfer from your Busha crypto balance to fiat account.
4. 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](/guides/getting-started/quick-start)).
* An understanding of **API Environments** (Sandbox vs. Production) and their base URLs (from the [Make Your First Request Guide](/guides/getting-started/make-first-request)).
* A conceptual understanding of **Quotes** (from the [Understanding Quotes](/overview/quotes) Overview).
* Familiarity with creating basic quotes (from the [How to Create Your First Quote Guide](/guides/quotes/create-first-quote)).
* 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](/guides/recipients/create-and-manage).
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.
## How to Process Crypto to Fiat Payouts
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](/guides/recipients/create-and-manage).
Once you have a `recipient_id`, your `pay_out` object will look similar to this example:
```json theme={null}
"pay_out": {
"type": "bank_transfer", // or "mobile_money"
"recipient_id": "677bbf9c7cf061f23784555a" // Replace your actual recipient ID
}
```
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:
1. Open your terminal or command prompt.
2. Construct a `POST` request to the `/v1/quotes` endpoint.
3. Set the type to "withdrawal".
4. 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).
5. Include the `pay_out` object with the type and `recipient_id` you prepared in Step 1.
6. Replace placeholders like `YOUR_BASE_URL` and `YOUR_SECRET_KEY`.
```bash theme={null}
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.
```json theme={null}
{
"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"
}
}
```
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:
1. Use the `POST` request below to the `/v1/transfers` endpoint.
2. Include the `quote_id` obtained from Step 2 in the request body.
3. Replace `YOUR_BASE_URL` and `YOUR_SECRET_TOKEN` with your actual details.
```bash theme={null}
$ 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.
```json theme={null}
{
"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"
}
}
```
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](/guides/webhooks/setup) 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.
```bash theme={null}
curl -X GET "YOUR_BASE_URL/v1/transfers/TRF_tYZ1y5bmXv4N5IhXSMbWJ" -H "Authorization: Bearer {YOUR_SECRET_API_KEY}"
```
**Expected Transfer Statuses**
* **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](/guides/recipients/create-and-manage): Essential for managing your payout destinations.
* [How to Process Fiat Deposits Guide](/guides/deposits/process-fiat-deposits)
* [How to Process Crypto Deposits Guide](/guides/deposits/process-crypto-deposits)
* [How to Perform Balance-to-Balance Conversions Guide](/guides/balance/convert-balance-to-balance)
* [Quotes API Reference](/api-reference/quotes/list-quotes)
* [Transfers API Reference](/api-reference/transfers/list-transfers)