Onramps

Overview

The onramp API endpoint facilitates converting fiat currency into crypto assets on a specified blockchain. It processes a fiat payment from a customer and automatically settles the equivalent crypto amount (USDC or USDT) into an on-chain wallet address. The service handles exchange rate conversion and transaction fees, providing a seamless bridge between traditional finance and decentralized applications.

When To Use This

Use the Onramp API when you want to build your own checkout or payment UI while Honeycoin handles fiat collection, conversion, and crypto settlement.

For a hosted widget that manages the payment UI for you, use the Onramp SDK instead.

Happy Path

1. Collect the customer's fiat amount, payment method, settlement token, chain, and receiver wallet address.

2. Submit an onramp request with a unique externalReference.

3. For mobile money, ask the customer to approve the payment prompt. For bank transfer, display the returned virtual account details.

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

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

1 - Initiate Mobile Money Onramp

To accept fiat payment via mobile money and settle crypto, use the onramp API endpoint.

Charge Details Object (Mobile Money):

Example Request:

{
  "senderAmount": 5000,
  "senderCurrency": "KES",
  "receiverCurrency": "USDC",
  "chain": "BASE",
  "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",
  "method": "momo",
  "chargeDetails": {
    "phoneNumber": "254719624551",
    "momoOperatorId": "mpesa"
  },
  "externalReference": "onramp_user_001",
  "email": "[email protected]"
}

Below is an example of the response:

Success

{  
  "success": true,  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM"  
  }  
}

Note: Use the returned transactionId to track the onramp status. The transaction is processed asynchronously.

2 - Initiate Bank Transfer Onramp

To accept fiat payment via bank transfer and settle crypto, use the same endpoint with method set to bank. Honeycoin creates virtual account details for the customer to pay into.

Charge Details Object (Bank Transfer):

Example Request:

{
  "senderAmount": 50000,
  "senderCurrency": "KES",
  "receiverCurrency": "USDT",
  "chain": "ARB",
  "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",
  "method": "bank",
  "chargeDetails": {
    "email": "[email protected]"
  },
  "externalReference": "onramp_bank_001",
  "email": "[email protected]"
}

Example Response:

{  
  "success": true,  
  "data": {  
    "transactionId": "y47aWLwUE2NW7duNNbiM"  
  }  
}

Bank transfer onramps may also return virtual account details in data.virtualAccount. Display those details to the customer and continue tracking the transaction by transactionId.

3 - 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 onramp 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_user_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_user_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_user_001",  
    "failureReason": "Payment declined by mobile money provider"  
  }  
}

4 - 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_user_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_user_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_user_001",  
    "senderAmount": 5000,  
    "senderCurrency": "KES",  
    "receiverCurrency": "USDC",  
    "failureReason": "Payment declined by mobile money provider"  
  },  
  "timestamp": "2025-06-17T02:30:44.600Z"  
}

5 - 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:

6 - Multi-Currency Support

Onramps support 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.

7 - Exchange Rate Information

Onramps automatically handle currency conversion at current market rates. To display real-time exchange rates to your users or for rate calculations, 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 initiating onramps
• Implement proper error handling for failed transactions
• 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