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.

1 - Initiate Mobile Money Onramp

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

Field	Type	Required	Description
senderAmount	Number	✅	Amount of fiat currency to charge (e.g. 1000)
senderCurrency	String	✅	Fiat currency code (e.g. KES, UGX, NGN)
receiverCurrency	String	✅	Cryptocurrency to settle (USDC or USDT)
chain	String	✅	Blockchain for settlement (ETH, ARB, BASE, MATIC, BSC, OPTIMISM)
receiverAddress	String	✅	Destination on-chain wallet address
method	String	✅	Payment method (set to momo for mobile money)
chargeDetails	Object	✅	Mobile money payment details (see below)
externalReference	String	✅	Your unique ID for reconciliation
email	String	❌	The customer’s email

Charge Details Object (Mobile Money):

Field	Type	Required	Description
phoneNumber	String	✅	Customer phone number with country code, no plus (e.g. 254719624551)
momoOperatorId	String	✅	Mobile money operator ID (required for some currencies)

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]](mailto:[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 bank-specific details.

Field	Type	Required	Description
senderAmount	Number	✅	Amount of fiat currency to charge
senderCurrency	String	✅	Fiat currency code
receiverCurrency	String	✅	Cryptocurrency to settle (USDC or USDT)
chain	String	✅	Blockchain for settlement
receiverAddress	String	✅	Destination on-chain wallet address
method	String	✅	Payment method (set to bank for bank transfer)
chargeDetails	Object	✅	Bank payment details (see below)
externalReference	String	✅	Your unique ID for reconciliation
email	String	❌	Customer email (highly recommended)

Charge Details Object (Bank Transfer) - Only available in KES & NGN collection.

Field	Type	Required	Description
accountName	String	✅	Account holder name
accountNumber	String	✅	Bank account number
bankCode	String	✅	Bank code (retrieve from Get Banks API)

Example Request:

{  
  "senderAmount": 50000,  
  "senderCurrency": "KES",  
  "receiverCurrency": "USDT",  
  "chain": "arbitrum",  
  "receiverAddress": "0xbac726e1df4dd58ca13bf6b9f23664df5d07d2fe",  
  "method": "bank",  
  "chargeDetails": {  
    "accountName": "John Doe",  
    "accountNumber": "1234567890",  
    "bankCode": "1243"  
  },  
  "externalReference": "onramp_bank_001",  
  "email": "[[email protected]](mailto:[email protected])"  
}

Example Response:

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

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:

/api/b2b/transactions?transactionId=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

Configure your webhook URL in your dashboard account
Implement webhook endpoint security and validation
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:

Failure Reason	Cause	Action
Payment declined	Payment method rejected the transaction	Retry with valid payment details
Invalid wallet address	Receiver address is invalid for the chain	Verify wallet address is valid on the specified chain
Insufficient balance	Customer's account has insufficient funds	Customer needs to add funds
Invalid currency	Currency not supported for the method	Check Supported Countries & Limits
Blockchain error	Error settling crypto to wallet	Retry or contact support
Duplicate transaction	External reference already used	Use a unique external reference
Service unavailable	Payment network temporarily down	Retry after some time

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