Skip to main content

​
Prerequisites

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

​
1. Get Your API Key

The fastest way is from the dashboard — no code required.
  1. Log in to integrator.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 details.
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

Include your API key in the Authorization: Bearer header: 
curl -X GET https://sandbox-api.kotanipay.io/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

Collect payments

Accept payments via mobile money, bank checkout, or card.

Disburse funds

Send money to a customer’s mobile money wallet or bank account.

Buy crypto (Onramp)

Accept fiat via mobile money or bank and deliver crypto to a wallet.

Sell crypto (Offramp)

Accept crypto and disburse fiat to a mobile money wallet or bank account.

Payment links

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

Bulk payments

Disburse to multiple recipients at once — ideal for payroll, commissions, and refunds.

​
4. Fund Your Payout Balance

Only needed if you’re sending money out — payouts, offramp, or bulk payments.
Deposits credit your deposit balance. Payouts draw from your payout balance. These are separate, so you’ll need to transfer between them before you can disburse funds. From the dashboard: Wallets → Transfer Deposit Balance

​
6. Set Up Webhooks

Every transaction request accepts a callbackUrl — Kotani Pay posts the result to that URL when the transaction settles. To receive signed callbacks, configure a webhook secret from the dashboard:
  1. Log in → Settings
  2. Copy the 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 payload structures and signature verification.

​
7. Go Live

  1. Contact the Kotani Pay team to request a production account
  2. Once provisioned, log in to integrator.kotanipay.com and switch to Production using the environment selector
  3. Generate a production API key from API Keys in the sidebar
  4. Switch your base URL to https://api.kotanipay.io
Sandbox credentials do not work in production and vice versa. Always confirm the correct environment before going live.