Skip to main content
POST
/
api
/
v3
/
deposit
/
on-chain
Deposit onChain
curl --request POST \
  --url https://preview.kotanipay.com/api/v3/deposit/on-chain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "wallet_id": "<string>",
  "amount": 123,
  "customer_key": "<string>",
  "public_address": "<string>",
  "callback_url": "<string>",
  "reference_id": "<string>"
}
'
{
  "success": true,
  "message": "Deposit has been successfully created.",
  "data": {
    "id": "<string>",
    "message": "<string>",
    "reference_id": "<string>",
    "reference_number": 123,
    "customer_key": "<string>",
    "redirect_url": "<string>"
  }
}
This endpoint is marked as deprecated but is fully functional. It will be replaced with a clearer naming convention in the future.

​
Use Case

This endpoint is for e-commerce platforms and businesses that want to accept mobile money payments and receive the equivalent in cryptocurrency. Perfect for:
  • E-commerce platforms accepting crypto payments
  • Merchants wanting to receive payments in stablecoins
  • Platforms converting fiat payments to crypto automatically
NOT for:
  • Selling crypto to customers (use /onramp instead)
  • Running a crypto exchange

​
How It Works

  1. Your customer pays via mobile money (STK push)
  2. We collect the mobile money payment
  3. We convert the fiat to crypto at current rates
  4. Your crypto wallet receives the USDT/crypto
  5. You fulfill the customer’s order

​
Flow

​
Key Differences

AspectThis Endpoint (Deposit On-Chain)Onramp Endpoint
Who receives crypto?✅ You (the merchant)Customer
Who receives fiat?Payment processor✅ You (the merchant)
Crypto inventory needed?❌ No✅ Yes (must have crypto to sell)
Use caseAccept payments in cryptoSell crypto to customers

​
Examples

​
Receive crypto to your wallet

When you DON’T provide public_address, crypto goes to your wallet: 
{
  "customer_key": "cus_abc123",
  "wallet_id": "wallet_polygon_usdt_xyz",
  "amount": 1450,
  "chain": "POLYGON",
  "token": "USDT",
  "callback_url": "https://yourdomain.com/webhook",
  "reference_id": "order_12345"
}
Result: You receive ~0.65 USDT in your POLYGON wallet

​
Send crypto to customer’s address

When you provide public_address, crypto goes directly to that address: 
{
  "customer_key": "cus_abc123",
  "wallet_id": "wallet_polygon_usdt_xyz",
  "amount": 1450,
  "chain": "POLYGON",
  "token": "USDT",
  "public_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "callback_url": "https://yourdomain.com/webhook",
  "reference_id": "order_12345"
}
Result: Customer receives ~0.65 USDT at their address

​
Supported Chains & Tokens

Get supported chains and tokens: 
GET /api/v3/deposit/on-chain/supported-chains
Response: 
{
  "data": {
    "POLYGON": ["USDT", "USDC"],
    "ETHEREUM": ["USDT", "USDC"],
    "CELO": ["CUSD"],
    "STELLAR": ["USDC"],
    "SOLANA": ["USDT", "USDC"]
  }
}

​
Status Tracking

Track your deposit status: 
GET /api/v3/deposit/on-chain/status/{reference_id}
See Get Deposit On-Chain Status for details.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
chain
enum<string>
required

supported chain

Available options:
ETHEREUM,
CELO,
AVALANCHE,
POLYGON,
ARBITRUM,
OPTIMISM,
STELLAR,
TRON,
FUSE,
LIGHTNING,
SOLANA,
PROVENANCE,
CARDANO,
HEDERA,
BASE,
LISK,
VICTION,
SCROLL
​
token
enum<string>
required

supported token

Available options:
CUSD,
USDC,
USDT,
USDT0,
SAT,
BTC,
HASH,
FUSE,
HBAR,
USDGLO,
CKES,
CGHS,
MSAT,
XLM,
ADA
​
wallet_id
string
required

The wallet id

​
amount
number
required

The amount to deposit

​
customer_key
string
required

The customer key

​
public_address
string

The transaction public address

​
callback_url
string

The callback url

​
reference_id
string

Optional reference id

Response

​
success
boolean
Example:

true

​
message
string
Example:

"Deposit has been successfully created."

​
data
object