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.

​
Prerequisites

You need a Kotani Pay integrator account. Sandbox accounts are self-service — create one now using the Create Integrator endpoint. Production accounts require a provisioned account from the Kotani Pay team.

​
1. Get Your API Key

The fastest way is from the dashboard — no code required.
  1. Log in to backoffice.kotanipay.com
  2. Navigate to API Keys in the left sidebar
  3. Click Generate New Key
  4. Copy and store the key securely — it won’t be shown again
If you need a key with a signing secret (for webhook payload verification), use Generate Secure Key instead. This returns both a key and a secret. See API Keys for the difference.
Prefer the API? You can also generate a key programmatically via a magic link flow — see API Keys for that method.

​
2. Make Your First Call

Use the API key in the Authorization: Bearer header: 
curl -X GET https://sandbox-api.kotanipay.com/health \
  -H "Authorization: Bearer <your-api-key>"
A successful response confirms your key is valid: 
{
  "success": true,
  "message": "Health check",
  "data": {
    "status": "ok"
  }
}

​
3. Pick Your Flow

Now that you have a key, choose what you’re building:

Collect payments

Customer pays you via mobile money, bank checkout, or card. Funds land in your deposit balance.

Disburse funds

Send money to a customer’s mobile money wallet or bank account from your payout balance.

Buy crypto (Onramp)

Customer pays fiat via mobile money or bank; Kotani Pay sends crypto to their wallet.

Sell crypto (Offramp)

Customer sends crypto to an escrow address; Kotani Pay disburses fiat to their mobile money or bank.

Payment links

Generate a hosted checkout page — no frontend required. Share the URL and start collecting.

Bulk payments

Disburse to hundreds of recipients at once via CSV upload — payroll, commissions, refunds.

​
4. Fund Your Payout Balance

Only needed if you’re sending money out — withdrawals, offramp, or bulk payments.
Deposits credit your deposit balance. Withdrawals draw from your payout balance. These are separate — you need to transfer between them before you can disburse. In the dashboard: Wallets → Transfer Deposit Balance See Balances & Settlement for the full explanation.

​
5. Set Up Webhooks

Every transaction request accepts a callbackUrl — Kotani Pay posts the result directly to that URL when the transaction settles. No extra configuration needed for this. If you want callbacks to arrive with a signature you can verify, configure a webhook secret:
  1. Log in to the dashboard → Settings
  2. Copy the generated signing secret and store it as an environment variable
With a secret configured, every callback includes X-Kotani-Signature, X-Kotani-Event, and X-Kotani-Integrator headers. See Webhooks for both delivery modes, payload structures, and signature verification.

​
6. Go Live

  1. Contact Kotani Pay via your usual communication channel to request a production account
  2. Once provisioned, log in to backoffice.kotanipay.com and switch to Production using the environment selector in the top right
  3. Generate a production API key from API Keys in the sidebar
  4. Switch your base URL to https://api.kotanipay.com
See Accessing the Dashboard for how the environment gate and selector work.
Sandbox credentials do not work in production and vice versa. Always confirm the environment is set correctly before going live.