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.

​
Environments

Always develop against sandbox first. Production and sandbox share the same API structure — only the base URL and credentials differ.
EnvironmentBase URL
Sandboxhttps://sandbox-api.kotanipay.com
Productionhttps://api.kotanipay.com
Sandbox API keys do not work in production and vice versa. Generate environment-specific credentials for each.

​
Authentication

Every request requires an Authorization: Bearer header. Both API keys and JWT tokens are accepted in the same header format. API keys are the right choice for server-to-server integrations — they do not expire unless revoked. JWT tokens are short-lived (1 hour) and mainly used during the API key generation flow. See API Keys for how to generate a key and the difference between integrator-level and user-bound keys.

​
Request & Response Format

All endpoints accept and return JSON. Set Content-Type: application/json on requests with a body. All responses follow a consistent envelope: Success: 
{
  "success": true,
  "message": "...",
  "data": { }
}
Error: 
{
  "success": false,
  "message": "Descriptive error message",
  "error_code": 400,
  "data": { }
}
See Error Handling for the full status code reference and error payload details.

​
Error Codes

StatusMeaning
200Success
400Bad request — check your request body and parameters
401Unauthorized — API key or JWT is missing or invalid
403Forbidden — key exists but lacks permission for this operation
404Resource not found
429Rate limit exceeded
500Internal server error — contact support if persistent

​
Rate Limits

The API applies per-endpoint, per-key rate limits with three tiers:
TierApplied to
GeneralStandard create/update operations
SensitiveAuthentication and security-critical endpoints
Read-onlyGET/list endpoints
When rate limited, the response includes a retryAfter value in seconds. Specific limits are configurable per integrator — contact your account manager if you need a higher limit for a high-volume integration.

​
Idempotency

For deposits and withdrawals, always send a reference ID. The field name differs by flow:
  • Deposits use reference_id (snake_case)
  • Withdrawals use referenceId (camelCase)
Reference IDs must be unique per integrator. If a request times out or fails at the network level, retrying with the same reference ID will not create a duplicate transaction.

​
Webhooks

Use webhooks instead of polling. Configure your endpoint in the dashboard under Settings. There are two delivery modes — which one you receive depends on whether a webhook secret is configured on your account. When a secret is configured, each request includes an X-Kotani-Signature header you must verify before processing. Without a secret, Kotani Pay posts directly to the callbackUrl on each transaction with no signature headers. See Webhooks for both delivery modes, all event types, payload schemas, and the signature verification code.

​
Going to Production

  1. Switch your base URL to https://api.kotanipay.com
  2. Run the magic link login flow against production to get a production JWT
  3. Generate a production API key using that JWT
  4. Update your webhook endpoint to point to your production server
Sandbox credentials do not work against the production URL. Always generate environment-specific keys.

​
Transaction Flows

Each flow walks through the full lifecycle — what to call, what the customer experiences, how the callback arrives, and how to poll for status.

Deposit Flow

Mobile money, bank checkout, and card collections

Withdrawal Flow

Mobile money and bank disbursements

Onramp Flow

Fiat → crypto via mobile money or bank

Offramp Flow

Crypto → fiat disbursement and refund handling

Payment Links

Hosted checkout pages with multiple payment methods

Bulk Payments

CSV-based mass disbursements with batch tracking