On-Ramps

Overview

The Cashless on-ramp API converts fiat currency into crypto assets (USDC or USDT) on supported EVM chains. It processes a fiat payment and automatically settles the equivalent crypto amount into an on-chain wallet address.

1 - Initiate Mobile Money Onramp

POST /api/crypto/onramp

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

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

Response:

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

2 - Initiate Bank Transfer Onramp

Same endpoint with method: "bank". Only available for KES & NGN collections.

{
  "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]"
}

3 - Get Onramp Status

Check status using the get transaction endpoint with transactionId or externalReference.

/api/b2b/transactions?transactionId=y47aWLwUE2NW7duNNbiM

4 - Handle Webhooks

{
  "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": "0xc3acfde7..."
  },
  "timestamp": "2025-06-17T02:25:44.600Z"
}

Best Practices

Use unique external references to prevent duplicate transactions
Validate wallet addresses before initiating onramps
Use webhooks for real-time status updates rather than polling
Test thoroughly in sandbox before production