Skip to main content
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.
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 funded payout balance in the disbursement currency, and a customer record for the recipient.

​
1. Get a Rate Quote

Fetch the current offramp rate to show the customer how much fiat they’ll receive. Call Get Offramp Exchange Rate with the crypto token and target fiat currency.

​
2. Create the Offramp

Call Create Offramp Request 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.
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.

​
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
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 offramp payload for every field you receive with a worked example.

​
6. Poll for Status

​
Refund Handling

If the automatic refund fails, you can retry: See 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. Cancel Offramp Transaction

​
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 Offramp in the left sidebar
Failed transactions show the reason and refund status.