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

# Offramp Flow (Crypto → Fiat)

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

An offramp converts cryptocurrency into local fiat currency. The customer sends crypto to a Kotani Pay escrow address; once confirmed on-chain, Kotani Pay disburses the equivalent fiat to the customer's mobile money wallet or bank account.

***

## Before You Start

* An API key — see [API Keys](/v3/getting-started/api-keys)
* A customer record for the recipient — see [Create Customer](/v3/api-reference/customers/mobile-money/create)
* A funded payout balance in the disbursement currency
* A `callbackUrl` on your server

***

## 1. Get a Rate Quote

Fetch the current offramp rate to show the customer how much fiat they'll receive. Call [GET /api/v3/rates/offramp-rate](/v3/api-reference/rates/offramp-rate) with the crypto token and target fiat currency.

***

## 2. Create the Offramp

Call [POST /api/v3/offramp](/v3/api-reference/offramp/create) with your `callbackUrl`. The API responds with a `PENDING` transaction and a `depositAddress` — this is the on-chain address the customer must send crypto to. Display this address (and optionally a QR code) to them.

***

## 3. Customer Sends Crypto

The customer sends the exact amount to the `depositAddress` from their own wallet. Kotani Pay monitors the address and advances the transaction to `CRYPTO_RECEIVED` once the required confirmations are reached. No further action is needed from your server at this step.

***

## 4. Fiat is Disbursed

Once crypto is confirmed, Kotani Pay initiates the fiat disbursement. The recipient gets an SMS confirmation from the mobile money network when funds arrive.

<Warning>
  If fiat disbursement fails after crypto is received, Kotani Pay automatically initiates a crypto refund 5 minutes after the failure. The transaction moves to `REFUND_PENDING`. Track this via the refund endpoints below.
</Warning>

***

## 5. Kotani Pay Notifies You

Kotani Pay POSTs to your `callbackUrl` at each terminal state:

* `SUCCESS` — fiat delivered to the recipient
* `FAILED` — disbursement failed
* `REFUNDED` — crypto returned to sender after a failed fiat disbursement
* `REFUND_FAILED` — crypto refund failed; contact support

<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/offramp/:referenceId](/v3/api-reference/offramp/get-status) — full transaction status
* [GET /api/v3/offramp/refund-status/:referenceId](/v3/api-reference/offramp/refund-status) — refund status if fiat disbursement failed

***

## Refund Handling

If the automatic refund fails, you can retry:

* **Single retry** — [POST /api/v3/offramp/retry-refund/:referenceId](/v3/api-reference/offramp/retry-refund)
* **Lightning offramps** — if the refund requires a bolt11 invoice, the customer provides one and you submit it via `POST /api/v3/offramp/submit-refund-invoice/:referenceId`

See [Offramp Refunds](/v3/essentials/offramp-refunds) for the full refund states and handling.

***

## Cancel a Transaction

A transaction can only be cancelled while still in `PENDING` — before any crypto is received on-chain.

[GET /api/v3/offramp/cancel/:referenceId](/v3/api-reference/offramp/cancel)

***

## 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 **Offramp** in the left sidebar

Failed transactions show the reason and refund status.