Skip to main content
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.
You need an API key and a reachable callbackUrl — see the Quickstart if you haven’t set those up. For this flow you also need a customer record for the person paying, and the crypto wallet address to deliver to.

​
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 Onramp Exchange Rate with the fiat currency and crypto token.

​
2. Initiate the Onramp

Call Create 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 for both modes, and the onramp payload for every field you receive with a worked example.

​
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