GuideReference

Process Quotes with Quote Currency and Quote Amount

Only fiat currencies are supported for quote_currency

This guide explains how to leverage Busha's Quotes API to process a quote using the quote_currency and quote_amount fields, allowing for transactions where the original value is denominated in a different FIAT currency than the source and target cryptocurrencies.

What You’ll Achieve:

  1. Understand the specific parameters for this type of transaction.

  2. Generate a deposit quote that provisions a crypto pay in address

Prerequisites

Before you begin, ensure you have:

For deposit 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.

Get a Quote for the Deposit

A deposit is initiated by creating a Quote. In this guide, we’re going to define the original currency for which the quote is being prepared which is fiat using the quote_currency field, as well as the amount of the quote_currency to be transacted.

This is useful for scenarios where a business wants a customer to pay for services in a currency of their choice while still maintaining the original price of the service regardless of the payment currency.

To get a deposit quote:

  1. Identify the quote_currency and quote_amount:

    • The quote_currency is the original currency for which the quote is being prepared (e.g., NGN, KES).

    • The quote_amount is the amount of the quote_currency to be transacted (e.g., 50000).

  2. Specify source_currency and target_currency:

    • The source_currency is the cryptocurrency the user will use to pay (e.g., USDT).

    • The target_currency is the cryptocurrency you want to receive and store (e.g., USDT).

  3. Define the pay_in object:

    • Set type to "address" as the medium of payment is a cryptocurrency address.

    • Specify the network for the chosen source_currency (e.g., "TRX" for USDT).

  4. Set the pay_out object:

    • Set type to "balance" as the destination of the received funds is your Busha balance.

Example quote object:

{  
  "quote_currency": "NGN", // Original fiat currency of the value  
  "quote_amount": "50000", // Amount in the quote_currency  
  "source_currency": "USDT", // Currency user wants to pay with  
  "target_currency": "USDT", // Currency to be received in balance  
  "pay_in": {  
    "type": "address", // Medium of payment  
    "network": "TRX" // Network of the said currency  
  },  
  "pay_out": {  
    "type": "balance" // Destination of the money paid in  
  }  
}

With the quote object defined, send a POST request to the /v1/quotes endpoint:

$ curl -i -X POST https://BASE_URL/v1/quotes \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_currency": "NGN",
    "quote_amount": "50000",
    "source_currency": "USDT",
    "target_currency": "USDT",
    "pay_in": {
      "type": "address",
      "network": "TRX"
    },
    "pay_out": {
      "type": "balance"
    }
  }'

A successful response will return a standard Quote object, similar to what you’ve seen before.

  1. Locate the "data" object within the response.

  2. Note the id of the returned Quote

  3. Extract the value from the "source_amount" field. This value represents the exact amount of cryptocurrency (e.g., USDT) the use needs to pay, which is calculated internally by Busha based on the quote_currency, quote_amount, and the current exchange rate.

  4. Note the "target_amount" field, which indicates the amount of cryptocurrency you will receive. In this specific scenario, source_amount and target_amount will be the same.

Example Response Snippet:

{  
  "status": "success",  
  "message": "Created quote successfully",  
  "data": {  
    // ... other fields  
    "id": "QUO_vxnndjeneiviu84",
    "source_currency": "USDT",  
    "target_currency": "USDT",  
    "source_amount": "32.851512", // Amount of crypto the user needs to pay  
    "target_amount": "32.851512", // Amount of crypto you will receive  
    // ... other fields  
  }  
}

Finalize the Deposit Transfer

To initiate the transfer process and obtain the unique cryptocurrency address for the user payment:

  1. Create a transfer via the /v1/transfers endpoint with the quote ID retrieved from the response.

  2. The API response for creating a transfer will contain a "pay_in" object.

  3. Within the "pay_in" object, retrieve the "address" field. This is the unique cryptocurrency address where the user should send their payment.

  4. Note the "expires_at" field, which indicates when the payment address will expire. Ensure the user completes the transaction before this time.

$ 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_vxnndjeneiviu84"
  }'

Example Response Snippet:

{  
  "status": "success",  
  "message": "Created transfer successfully",  
  "data": {  
    "id": "TRF_LJB2GQb55Cs98LbpqgRGx"
    // other fields
    "source_currency": "USDT",  
    "target_currency": "USDT",  
    "source_amount": "32.851512",  
    "target_amount": "32.851512",  
    "rate": {  
      "rate": "1",  
      "side": "sell",  
      "type": "FIXED",  
      "source_currency": "USDT",  
      "target_currency": "USDT"  
    },  
    "fees": [],  
    "pay_in": {  
      "address": "TWcYEz1UjSre7LqvvPyKHQ7EQzQ9oQDzit", // The crypto address to send payment to  
      "expires_at": "2025-07-20T23:22:52.857352Z",  
      "network": "TRX",  
      "type": "address"  
    },  
    // ... other fields  
  }  
}

Monitoring Deposit Status

After the user has made the payment to the provided address, you can query the transfer status using the transfer ID.

To monitor deposit status:

  • Webhooks (Recommended): Set up a webhook endpoint to receive real-time notifications from Busha when the transfer status changes. This is the most efficient method for real-time updates.

  • Polling (Less Recommended): Periodically GET the transfer status using the transfer id TRF_LJB2GQb55Cs98LbpqgRGx in the example). While possible, this is less efficient and can lead to rate limiting if done too frequently.

Expected Transfer Statutes:

  • pending : Transfer initiated, awaiting user deposit.

  • funds_received: Funds have been successfully received and credited to your Busha balance.

  • cancelled: the transfer has been cancelled, and will not continue.

Troubleshooting Common Fiat Deposit Issues

  • “Quote expired” during transfer finalization: Always create a fresh quote immediately before attempting to finalize the transfer.

  • Deposit not reflecting: Check the transfer status via API/webhooks. If still pending after an extended period, contact Busha support with the TRF_ ID.

What’s Next?

Now that you know how to process deposits using quote_currency and quote_amount, consider: