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.
Prerequisites
- 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 Overview).
- Basic knowledge of web development (HTML, JavaScript) or mobile app development.
Step 1: Integration Design and User Experience Best Practices
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 URL
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: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 ConstructionWhile direct client-side URL construction is quick, we strongly recommend that you build the On-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.| 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
|
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 fiat currency (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. |
Step 3: Handling Post-Transaction Redirects
After a user completes their On-Ramp transaction (or cancels) within the Busha widget, they will be redirected back to your application using theredirectUrl 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.
Troubleshooting
Widget Not Loading/API Key Issues: Ensure that yourpublicKey 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 On-Ramp widget! Consider these next steps to further enhance your Busha integration:- How to Integrate the Off-Ramp Widget
- 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.