> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kotanipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onramp Flow (Fiat → Crypto)

> How to convert fiat to crypto — customer pays via mobile money or bank, Kotani Pay sends crypto to their wallet

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](/v3/getting-started/api-keys)
* A customer record for the person paying — see [Create Customer](/v3/api-reference/customers/mobile-money/create)
* 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](/v3/api-reference/rates/onramp-rate) with the fiat currency and crypto token.

***

## 2. Initiate the Onramp

Call [POST /api/v3/onramp](/v3/api-reference/onramp/create) 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

<Warning>
  If the crypto transfer fails after fiat is collected, the fiat amount is automatically refunded to your fiat wallet.
</Warning>

***

## 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

<Note>
  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](/v3/essentials/webhooks).
</Note>

***

## 6. Poll for Status

* [GET /api/v3/onramp/:referenceId](/v3/api-reference/onramp/get-status) — standard onramp status
* [GET /api/v3/onramp/crypto/:referenceId](/v3/api-reference/onramp/get-crypto-status) — crypto delivery status

***

## Monitoring from the Dashboard

1. Log in to [integrator.kotanipay.com](https://integrator.kotanipay.com/)
2. Use the **country and currency selector** to filter by market
3. Navigate to **Onramp** in the left sidebar