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

# Onramp: Buy Crypto

> Take local currency and deliver crypto to a 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.

***

<Note>
  You need [an API key](/v3/getting-started/api-keys) and a reachable `callbackUrl` — see the [Quickstart](/v3/quickstart) if you haven't set those up. For this flow you also need a [customer record](/v3/api-reference/customers/mobile-money/create) for the person paying, and the crypto wallet address to deliver to.
</Note>

## 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](/v3/api-reference/rates/onramp-rate) with the fiat currency and crypto token.

***

## 2. Initiate the Onramp

Call [Create 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) for both modes, and the [onramp payload](/v3/essentials/webhooks#transactiononrampstatusupdated) for every field you receive with a worked example.
</Note>

***

## 6. Poll for Status

* [Get Onramp Status (by Reference ID)](/v3/api-reference/onramp/get-status) — standard onramp status
* [Get Crypto Onramp Status (by Reference ID)](/v3/api-reference/onramp/get-crypto-status) — crypto delivery status

***

## Monitoring from the Dashboard

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