Integrate the On-Ramp Widget

The Busha On-Ramp widget provides a seamless solution for your users to convert fiat currency into cryptocurrencies directly within your application or website. By integrating this widget, you enable your users to easily purchase crypto, handling the complexities of payment processing, KYC, and compliance on Busha's side.

This guide will walk you through the essential steps to quickly embed and configure the Busha On-Ramp widget, along with key design principles to optimize the user experience.

What You’ll Achieve:

Understand key design principles for an optimal On-Ramp user journey.
Learn the quickest way to integrate the On-Ramp widget using a client-side URL.
Understand the basic parameters for configuring the On-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 On-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 On-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 prominent entry points to the On-Ramp widget. This ensures users can easily find and initiate the purchase process from various relevant locations, such as: Your Home screen Your Main app navigation Individual cryptocurrency screens
Amount Input	If your app has an amount input screen where users specify their desired buy amount: When opening the widget, pre-fill the fiat or crypto amount by using URL parameters like `cryptoAsset` with `cryptoAmount` or `fiatAmount` with `fiatCurrency`. Show minimum and maximum buy limits (retrieved from our Pairs API) to users upfront.
Payment Method Selection Screen	If your app includes a payment method selection screen: Show all supported payment methods that Busha offers for on-ramp. Display relevant payment method logos. Provide estimated transaction completion times for each method.
Provider Selection Screen	If your app offers multiple providers (or if Busha offers various internal options) Show quotes from our Quote Endpoint, using the right `pay_in`/`pay_out` method. Display estimated transaction completion times for each quote.
Pre-fill Customer's Wallet Address	For partner apps that already know the customer's destination wallet address(es): Pre-fill the wallet address to skip the wallet address screen in the user journey within the widget. To do this, pass the `address` widget parameter. If using `address`, also pass the `cryptoAsset` widget parameter.
Transaction Tracking	After the user completes their transaction, provide clear feedback: Display a toast message or similar notification. Include a link to the Busha transaction tracker. Alternatively, link to your app's own transaction history page.
Mobile App Configuration	For mobile apps, configure your app and its in-app browser for optimal widget performance: Use a fullscreen in-app browser and remove its navigation bar for a more native and seamless user experience. Configure your app and in-app browser to allow users to complete KYC successfully. Allow pop-ups at the in-app browser level to ensure all payment methods work correctly.

Step 2: Quick Start Integration with On-Ramp URLCopied!

Integrating the Busha On-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.

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:

In the example above, https://sandbox.buy.busha.io/ is the base URL for the Busha On-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.
`address`	No	Enter the destination wallet address for the cryptocurrency purchase. If provided, this address will be pre-filled and locked - customers won't need to enter their own wallet address. Otherwise, customers will be prompted to provide a wallet address during checkout. Passing an address makes `cryptoAsset` and `network` required.
`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`	No	URL to redirect the user to when they successfully complete a transaction.

Example of a more configured URL:

https://sandbox.buy.busha.io/?publicKey=pk_test_YOUR_PUBLIC_KEY&cryptoAsset=BTC&fiatCurrency=NGN&fiatAmount=50000&redirectUrl=https://your-app.com/busha-callback&address=bc1qyourbitcoinaddress&email=user@example.com

Step 3: Handling Post-Transaction RedirectsCopied!

After a user completes their On-Ramp transaction (or cancels) within the Busha widget, they will be redirected back to your application using the redirectUrl parameter you provided in the widget URL.

It is crucial to correctly set up and handle this redirectUrl in your application. Busha will append query parameters to this URL to indicate the transaction status (e.g., success, failure, pending, transaction ID). Your application should parse these parameters to update its UI, record the transaction status in your database, and provide appropriate feedback to the user.

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 On-Ramp widget! Consider these next steps to further enhance your Busha integration:

How to Integrate the Off-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.