Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt

Use this file to discover all available pages before exploring further.

An onramp converts local fiat currency into cryptocurrency. The customer pays via mobile money or bank checkout; once payment confirms, Kotani Pay sends the crypto to the wallet address you provided.

​
Before You Start

  • An API key — see API Keys
  • A customer record for the person paying — see Create Customer
  • A crypto wallet address to receive the funds
  • A callbackUrl on your server

​
1. Get a Rate Quote

Fetch the current exchange rate before initiating so you can show the customer what crypto amount they’ll receive. Call GET /api/v3/rates/onramp-rate with the fiat currency and crypto token.

​
2. Initiate the Onramp

Call POST /api/v3/onramp with your callbackUrl and the destination crypto wallet address. The API responds immediately with a PENDING transaction. The exchange rate is locked at this point.

​
3. Customer Pays

  • Mobile money — the customer receives an STK push (M-PESA, Airtel) or USSD prompt (MTN, others) and confirms by entering their PIN
  • Bank checkout — the response includes a checkoutUrl; redirect the customer there to complete payment on the bank’s page
The customer has not paid yet when you receive the initial response — they must complete their confirmation step.

​
4. Crypto is Delivered

Once fiat payment confirms, Kotani Pay converts at the locked rate and sends crypto to the wallet:
  • CRYPTO_PENDING — fiat confirmed, crypto transfer in progress
  • PROCESSING — blockchain transaction submitted, awaiting on-chain confirmations
  • SUCCESS — crypto delivered
If the crypto transfer fails after fiat is collected, the fiat amount is automatically refunded to your fiat wallet.

​
5. Kotani Pay Notifies You

Kotani Pay POSTs to your callbackUrl when the transaction reaches a terminal state:
  • SUCCESS — crypto delivered to the wallet
  • FAILED — transaction failed; fiat refunded automatically
If you have a webhook secret configured, the callback arrives in a signed envelope with X-Kotani-Signature, X-Kotani-Event, and X-Kotani-Integrator headers. Without a secret, the transaction fields are posted directly to your callbackUrl. See Webhooks.

​
6. Poll for Status

​
Monitoring from the Dashboard

  1. Log in to backoffice.kotanipay.com
  2. Use the country and currency selector to filter by market
  3. Navigate to Onramp in the left sidebar