Onramp SDK

Overview

The Onramp Widget is a pre-built, embeddable user interface that allows your users to convert fiat currency into crypto assets directly within your application. Unlike the API-only integration, this fully hosted component manages the entire user journey—including amount input, real-time exchange rate display, payment method selection, and status updates. It abstracts the complexity of payment collection and blockchain settlement, delivering the equivalent USDC or USDT to the user's wallet via a secure, low-code integration.

When to Use the SDK

Use the Onramp SDK when you want:

• Quick integration with minimal development effort
• A pre-built, white-labeled payment interface
• Automatic handling of payment collection and settlement
• Real-time exchange rate display
• Seamless user experience across devices
• Reduced complexity compared to building a custom UI

For more control over the user experience, use the Onramp API instead.

Happy Path

1. Create an Onramp SDK transaction with the fiat amount, settlement token, chain, receiver wallet address, and redirect URLs.

2. Redirect the customer to the returned paymentSdkLink.

3. The customer completes the hosted payment flow.

4. Honeycoin confirms the fiat payment and settles USDC or USDT to the receiver address.

5. Reconcile the final result from webhooks, redirects, or the transaction status endpoint.

1 - Initialize the Onramp SDK

To initialize the Onramp SDK, send a request to the onramp SDK endpoint with your parameters.

Prefill Data Object:

Example Request:

{
  "senderAmount": 5000,
  "senderCurrency": "KES",
  "receiverCurrency": "USDC",
  "chain": "BASE",
  "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",
  "externalReference": "onramp_sdk_001",
  "email": "[email protected]",
  "prefillData": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+254719624551"
  },
  "successRedirectUrl": "https://yourapp.com/success",
  "failureRedirectUrl": "https://yourapp.com/failed",
  "cancelRedirectUrl": "https://yourapp.com/cancelled"
}

Below is an example of the response:

Success

{  
  "success": true,
  "message": "Transaction created successfully",
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",
    "paymentSdkLink": "https://checkout.honeycoin.app/y47aWLwUE2NW7duNNbiM"
  }  
}

Note: Redirect the customer to paymentSdkLink. Use the returned transactionId to track the onramp status and for reconciliation.

2 - Embed the Widget in Your Application

Once you receive the transaction ID from the SDK endpoint, embed the widget in your application. The SDK handles:

• Payment method selection - Users choose between mobile money and bank transfer
• Amount input and validation - Real-time validation of amounts
• Real-time exchange rates - Display current conversion rates
• Payment collection - Secure collection of payment details
• Status updates - Real-time transaction status display
• Blockchain settlement - Automatic crypto settlement to the user's wallet

Widget Features

• Localized interface - Displays in the user's local language and currency
• Mobile-optimized - Works seamlessly on all devices
• Secure - Handles sensitive payment data securely
• Method-flexible - Shows available payment methods for the user's location
• Real-time updates - Instant feedback on transaction progress

3 - Handle Redirects

After the user completes or cancels the payment, they will be redirected to one of the URLs you specified:

• Success: User is redirected to successRedirectUrl after successful payment and crypto settlement
• Failure: User is redirected to failureRedirectUrl if payment fails
• Cancelled: User is redirected to cancelRedirectUrl if they cancel the transaction

Include the transactionId or externalReference as query parameters in your redirect URLs to identify the transaction:

https://yourapp.com/success?transactionId=y47aWLwUE2NW7duNNbiM
https://yourapp.com/failed?externalReference=onramp_sdk_001
https://yourapp.com/cancelled?transactionId=y47aWLwUE2NW7duNNbiM

4 - Get Onramp Status

Always verify the onramp status to confirm payment and crypto settlement. Use the get transaction endpoint with either:

• The transactionId from the SDK response, or
• Your externalReference

Example status check:

GET /api/b2b/transactions/y47aWLwUE2NW7duNNbiM

Here are examples of onramp status responses:

{  
  "success": true,  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "amount": 5000,  
    "type": "onramp",  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "status": "PENDING",  
    "chargeStatus": "pending",  
    "chain": "base",  
    "fullTimestamp": "2025-06-17T02:16:44+03:00",  
    "externalReference": "onramp_sdk_001"  
  }  
}

{  
  "success": true,  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "amount": 5000,  
    "type": "onramp",  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "status": "SUCCESSFUL",  
    "chargeStatus": "successful",  
    "chain": "base",  
    "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",  
    "cryptoAmount": "4.95",  
    "fullTimestamp": "2025-06-17T02:25:44+03:00",  
    "externalReference": "onramp_sdk_001",  
    "txId": "0xc3acfde7f212fcb902045119ee41299249ca153fc5c2730b0e8adba749846b53"  
  }  
}

{  
  "success": true,  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "amount": 5000,  
    "type": "onramp",  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "status": "FAILED",  
    "chargeStatus": "failed",  
    "chain": "base",  
    "fullTimestamp": "2025-06-17T02:30:44+03:00",  
    "externalReference": "onramp_sdk_001",  
    "failureReason": "Payment declined by mobile money provider"  
  }  
}

5 - Handle Webhooks

Configure webhooks to receive real-time onramp updates instead of polling the status endpoint.

Setup

1. Configure your webhook URL in your dashboard account.

2. Implement webhook endpoint security and validation.

3. Handle the webhook notifications in your application.

Here are examples of onramp webhook responses:

{  
  "event": "onramp_created",  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "status": "pending",  
    "type": "onramp",  
    "externalReference": "onramp_sdk_001",  
    "senderAmount": 5000,  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC"  
  },  
  "timestamp": "2025-06-17T02:16:44.600Z"  
}

{  
  "event": "onramp_updated",  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "status": "successful",  
    "type": "onramp",  
    "externalReference": "onramp_sdk_001",  
    "senderAmount": 5000,  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "cryptoAmount": "4.95",  
    "chain": "base",  
    "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",  
    "txId": "0xc3acfde7f212fcb902045119ee41299249ca153fc5c2730b0e8adba749846b53"  
  },  
  "timestamp": "2025-06-17T02:25:44.600Z"  
}

{  
  "event": "onramp_updated",  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM",  
    "status": "failed",  
    "type": "onramp",  
    "externalReference": "onramp_sdk_001",  
    "senderAmount": 5000,  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "failureReason": "Payment declined by mobile money provider"  
  },  
  "timestamp": "2025-06-17T02:30:44.600Z"  
}

6 - Handle Failed Onramps

When an onramp fails, you will receive a webhook notification or see the failure status when querying the transaction. Common failure reasons include:

7 - Multi-Currency Support

The Onramp SDK supports multiple fiat currencies across different countries. The fiat currency you specify in senderCurrency determines:

• Which payment methods are available
• The exchange rate for crypto settlement
• Transaction limits

For the most current list of supported currencies and limits, refer to the Supported Countries & Limits documentation.

8 - Exchange Rate Information

Onramps automatically handle currency conversion at current market rates. The SDK displays real-time exchange rates to users. To retrieve exchange rate information programmatically, use the Get FX Rate API.

Example:

GET /api/b2b/fx/rate?from=KES&to=USDC

For historical rates, use the Get Historical Rates API.

Best Practices

• Use unique external references to prevent duplicate transactions
• Include customer email for transaction receipts and support
• Validate wallet addresses before initializing the SDK
• Implement proper redirect handling for all three redirect URLs
• Use webhooks for real-time status updates rather than polling
• Test thoroughly in sandbox before deploying to production
• Monitor transaction success rates to identify potential issues
• Keep detailed records of all transactions for reconciliation
• Verify receiver address is valid on the specified blockchain
• Handle redirect parameters to identify transactions after user returns