Skip to main content

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.

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
  • A customer record for the recipient — see Create Customer
  • 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 with the crypto token and target fiat currency.

​
2. Create the Offramp

Call POST /api/v3/offramp 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.

​
6. Poll for Status

​
Refund Handling

If the automatic refund fails, you can retry:
  • Single retry — POST /api/v3/offramp/retry-refund/:referenceId
  • 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 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

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