Integrate the Off-Ramp Widget

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:

Understand key design principles for an optimal Off-Ramp user journey.
Learn the quickest way to integrate the Off-Ramp widget using a client-side URL.
Understand the basic parameters for configuring the Off-Ramp URL.
Learn about handling post-transaction redirects.

PrerequisitesCopied!

An active Busha Business Account.
Your Public API Key (refer to the How to Generate an API Key Guide if you don't have one).
A conceptual understanding of the Busha On-Ramp Widget (refer to the Understanding the Off-Ramp Widget Explainer).
Basic knowledge of web development (HTML, JavaScript) or mobile app development.

Step 1: Integration Design and User Experience Best PracticesCopied!

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.

Requirement	Description
Multiple entry points	All partner apps should add multiple entry points to the off-ramp. Home screen Main app navigation Individual cryptocurrency screens
Amount input	Partner 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 screen	Partner apps with a payout method selection screen should show: All supported payment methods Payment method logos Estimated transaction completion times
Provider selection screen	Partner apps with multiple providers should show: Quotes from our `Quote endpoint`, using the correct `pay_out` type. Estimated transaction completion times
Handle crypto deposits	Partner 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 tracking	All 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 configuration	All 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 URLCopied!

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:

Parameter	Required	Description
`publicKey`	Yes	Specify the Business PublicKey to recognize that a transaction is referred by a specific business' application.
`side`	Yes	Specify whether the customer intends to `buy` or `sell`
`cryptoAsset`	No	Specify the cryptocurrency asset (e.g., BTC, ETH, MATIC) for the customer's purchase. The customer must use the specified cryptocurrency - no substitutions are allowed.
`network`	No	Specify the cryptocurrency network (e.g., ERC20, POLYGON) for the customer's purchase. The customer must use the specified network - no substitutions are allowed.
`fiatCurrency`	No	Specify 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.
`cryptoAmount`	No	Specify the crypto amount to be processed.
`fiatAmount`	No	Specify the fiat amount to be processed. If passed, `cryptoAmount` is ignored.
`redirectUrl`	Yes	URL 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:

Parameter	Required	Description
`transferId`	Yes	The represents the transfer that has just been completed or initiated.
`depositWalletAddress`	Yes	Denotes the address that you should deposit the `cryptoAmount` into.
`cryptoAsset`	Yes	The crypto asset that should be deposited
`network`	Yes	Specific network for the crypto asset.
`cryptoAmount`	Yes	Required for Off-Ramp transfers. Denotes the crypto amount that should be deposited in the `address`
`fiatCurrency`	No	Denotes the fiat currency for the transfer.
`fiatAmount`	No	Denotes 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.

TroubleshootingCopied!

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?Copied!

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

How to Integrate the On-Ramp Widget: Learn how to enable crypto-to-fiat conversions for your users.
How to Generate an API Key: Review best practices for securing your credentials.
Busha API Reference: Explore other Busha APIs, such as the Pairs API, to dynamically fetch available currencies and limits for a more advanced integration.