Skip to main content
The Busha Off-Ramp widget provides a secure and straightforward solution for your users to convert their cryptocurrencies into fiat currency directly within your application or website. By integrating this widget, you empower your users to easily sell crypto and receive funds in their local currency, with Busha handling the complexities of crypto liquidation, regulatory compliance, and fiat payouts. This guide will walk you through the essential steps to quickly embed and configure the Busha Off-Ramp widget, along with key design principles to optimize the user experience for seamless crypto-to-fiat conversions.
What You’ll Achieve:
  1. Understand key design principles for an optimal Off-Ramp user journey.
  2. Learn the quickest way to integrate the Off-Ramp widget using a client-side URL.
  3. Understand the basic parameters for configuring the Off-Ramp URL.
  4. Learn about handling post-transaction redirects.

​
Prerequisites

​
Step 1: Integration Design and User Experience Best Practices

A successful Off-Ramp integration isn’t just about technical implementation. It’s about crafting an intuitive and efficient user journey. By incorporating these design principles, you can significantly enhance your users’ experience when buying crypto.
RequirementDescription
Multiple entry pointsAll partner apps should add multiple entry points to the off-ramp.
  • Home screen
  • Main app navigation
  • Individual cryptocurrency screens
Amount inputPartner apps with an amount input screen should show:
  • Add a max button and estimate network fees
  • When opening the widget, pre-fill the fiat / crypto amount by using cryptoAsset with cryptoAmount
  • Show the minimum and maximum sell limits set according to our API
Payout method selection screenPartner apps with a payout method selection screen should show:
  • All supported payment methods
  • Payment method logos
  • Estimated transaction completion times
Provider selection screenPartner apps with multiple providers should show:
  • Quotes from our Quote endpoint, using the correct pay_out type.
  • Estimated transaction completion times
Handle crypto depositsPartner apps with send functionality should handle crypto deposits for users to ensure high transaction success rates.
  • Get the deposit instructions by passing the redirectUrl widget parameter
  • Show a screen or bottom sheet with the deposit details for the user to confirm the transaction
Transaction trackingAll partner apps should display a toast message after the user completes their transaction and use the ramp transfers API to display the transfer event timeline.
Mobile app configurationAll partner mobile apps, configure app and browser so KYC and payment methods in the widget work correctly.
  • Use a fullscreen in-app browser and remove the navigation bar for a more native and seamless user experience
  • Configure your app and in-app browser so that users can complete KYC
  • Allow pop-ups at the in-app browser level so all payment methods work

​
Step 2: Quick Start Integration with On-Ramp URL

Integrating the Busha Off-Ramp widget via a URL redirect is the quickest way to get Busha’s crypto buying functionality into your application. All you need to do is incorporate the integration design principles from Step 1, collect the necessary information from your users, and then construct a URL to which you redirect them.
For sandbox requests, you can obtain test addresses from any of the providers listed in the Test Addresses reference.
Here’s a basic example of how you can attach a simple On-Ramp URL to a button in your application’s client-side code: 
<body>
  <div class="container">
    <button
      onclick="window.open('https://sandbox.sell.busha.io/?publicKey=pk_test_123', '_blank')"
    >
      Sell with Busha
    </button>
  </div>
</body>
In the example above, https://sandbox.buy.busha.io/ is the base URL for the Busha Off-Ramp widget in the Sandbox environment, and publicKey=pk_test_123 is your Public API Key passed as a query parameter. Server-Side URL Construction
While direct client-side URL construction is quick, we strongly recommend that you build the Off-Ramp URL on your application’s server-side. This approach offers several benefits:
  • Security: Keeps your Public API Key (though less sensitive than the Secret Key) from being directly exposed in your client-side source code, where it could be easily scraped.
  • Flexibility: Allows you to dynamically generate complex URLs with various parameters based on real-time data, user selections, and API responses (e.g., from the Pairs or Quotes API) without exposing your internal logic.
  • Reliability: Ensures that the URL is always correctly formatted and includes all necessary parameters.
Your server can return the pre-configured On-Ramp URL to the client, which then triggers the window.open() or redirect.

​
Configuring the Integration URL with Parameters

To pre-fill information and customize the user experience (as described in Step 1), you’ll add more query parameters to the base URL. This allows you to pass user selections directly to the widget, speeding up their journey. Common parameters you might include are:
ParameterRequiredDescription
publicKeyYesSpecify the Business PublicKey to recognize that a transaction is referred by a specific business’ application.
sideYesSpecify whether the customer intends to buy or sell
cryptoAssetNoSpecify the cryptocurrency asset (e.g., BTC, ETH, MATIC) for the customer’s purchase. The customer must use the specified cryptocurrency
  • no substitutions are allowed.
networkNoSpecify the cryptocurrency network (e.g., ERC20, POLYGON) for the customer’s purchase. The customer must use the specified network - no substitutions are allowed.
fiatCurrencyNoSpecify the cryptocurrency asset (e.g., NGN, KES) for the customer’s purchase. When passed, the customer must use the specified fiat currency
  • no substitutions are allowed.
cryptoAmountNoSpecify the crypto amount to be processed.
fiatAmountNoSpecify the fiat amount to be processed. If passed, cryptoAmount is ignored.
redirectUrlYesURL to redirect the user to when they to complete a sell transaction.
Example of a more configured URL: 
https://sandbox.sell.busha.co/?publicKey=PublicKey&cryptoAsset=ETH&network=ETH&fiatCurrency=NGN&cryptoAmount=0.005345&redirectUrl=https://www.partner.com
Redirect URL Parameters After a user completes a ramp transfer, Busha will append various URL parameters to your specified redirectUrl. Some parameters you should expect are:
ParameterRequiredDescription
transferIdYesThe represents the transfer that has just been completed or initiated.
depositWalletAddressYesDenotes the address that you should deposit the cryptoAmount into.
cryptoAssetYesThe crypto asset that should be deposited
networkYesSpecific network for the crypto asset.
cryptoAmountYesRequired for Off-Ramp transfers. Denotes the crypto amount that should be deposited in the address
fiatCurrencyNoDenotes the fiat currency for the transfer.
fiatAmountNoDenotes the fiat amount that will be credited to the payout destination or was paid to complete the purchase.
Sample redirect URL configuration 
https://www.partner.com/off-ramp?transferId={transferID}&depositWalletAddress=0xxxxxd134aCd3221a0xxxx80ADE3aF39Ce219037&cryptoAmount=0.005&cryptoAsset=BTC&network=ETH&fiatCurrency=NGN&fiatAmount=16075.87
Your redirectUrl should be able to receive and handle the returned values and process the deposit of the cryptoAmount into the depositWalletAddress upon users’ confirmation.

​
Troubleshooting

  • Widget Not Loading/API Key Issues: Ensure that your publicKey is correctly passed in the URL, and that it is active in your Busha dashboard.
  • Redirect Issues: Verify that your redirectUrl is correctly configured in the widget URL, and that your application endpoint is ready to receive and process the redirect.
  • Parameter Errors: Double-check that all passed URL parameters are spelled correctly and adhere to the expected format (e.g., correct currency codes, valid amounts).

​
What’s Next?

You’ve successfully learned how to integrate the Busha Off-Ramp widget! Consider these next steps to further enhance your Busha integration: