Rate is a single call with no branching, so it isn’t diagrammed on its own — it appears as a step inside the flows that need it.
1. Auth — Get an API Key
Server-to-server auth: get an API key once via the magic-link flow, then use that key in every other call. A key can also be generated directly from the dashboard’s API Keys page — choose Integrator Level (not User Bound) for full access to every endpoint./api/v3/auth
Magic link → JWT → API key. /auth/api-key returns the key alone; /auth/api-key/secure also returns a secret for request signing. The JWT expires after 1 hour — use the refresh endpoint rather than repeating the magic-link flow.
2. Customer — Create Once, Reuse Everywhere
Almost every product below needs acustomer_key. Create the record once per person, then pass that key into deposits, withdrawals, and settlement requests.
/api/v3/customer
Create → reuse the key. Mobile money and bank customers follow the same shape, on /customer/mobile-money and /customer/bank.
3. Onramp — Fiat → Crypto
Customer pays in local currency; Kotani Pay converts at a locked rate and sends crypto to the wallet address you provided./api/v3/onramp
Rate quote → payment → crypto delivery. Mobile money and bank checkout both converge on the same delivery step.
4. Offramp — Crypto → Fiat
Customer sends crypto to an escrow address; once confirmed on-chain, Kotani Pay disburses fiat via mobile money or bank./api/v3/offramp
Deposit address → on-chain confirm → fiat disbursed. A failed disbursement triggers an automatic crypto refund.
5. Deposit — Collect Payment
Four collection methods. All four credit the same deposit balance and notify the same way — only the customer-facing step differs./api/v3/deposit
5a. Mobile Money
STK push (M-PESA / Airtel) or USSD prompt (MTN and others).5b. Bank Checkout
One endpoint, three response shapes — what the customer sees depends on the currency.5c. Card
3D Secure runs inline only when the issuer requires it.5d. On-Chain (Receive Crypto)
For merchants who want to receive crypto themselves, not sell it to customers — the reverse of Onramp.6. Withdraw — Disburse to a Customer
Money moves out of your payout balance. A failed disbursement automatically reverses the debit./api/v3/withdraw
6a. Mobile Money
Same flow for/lipa-na-mpesa and /paybill — Kenya-only variants of this endpoint.
6b. Bank
Kenya and South Africa only. Look up bank codes for your currency before initiating.7. Payment Links — Hosted Checkout
A no-code checkout page. One create call, then Kotani Pay handles everything the customer sees./api/v3/payment-links
Create link → customer pays → webhook. Backed by the same deposit transactions as section 5.
8. Settlements — Move Balance Out
Every settlement goes through manual review before funds move. Batch and merge exist to handle many at once./api/v3/integrator/settlements
8a. Single Settlement
Check the schedule and fee before you submit — both are read endpoints.8b. Batch Settlement
Each child settlement is reviewed independently; the batch status reflects the mix.8c. Merge
Groups existing settlements into a batch after the fact — this cannot be undone.9. Bulk Payments — Many Recipients at Once
Upload a CSV, get it validated and batched, then Kotani Pay disburses asynchronously — one batch per currency./api/v3/bulk-payments
Validate → preview → create → disburse. Each individual payment still fires its own withdrawal webhook.