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.

A withdrawal is a disbursement — money moves from your Kotani Pay payout balance to a customer’s mobile money wallet or bank account.
Your payout balance must have funds before you can disburse. If it doesn’t, transfer from your deposit balance first — see Balances & Settlement.

​
Before You Start

  • An API key — see API Keys
  • A funded payout balance in the disbursement currency
  • A customer record for the recipient — see Create Customer
  • A callbackUrl on your server

​
Mobile Money Withdrawal

1. Create the customer if you haven’t already. The customer record holds the recipient’s phone number and network details. 2. Initiate the withdrawal — call POST /api/v3/withdraw/mobile-money with your callbackUrl. The API responds immediately with a PENDING transaction. Your payout balance is debited at this point. 3. The recipient receives funds. If the disbursement succeeds, the customer receives an SMS confirmation from the mobile money network. 4. Kotani Pay notifies you via your callbackUrl when the transaction settles:
  • SUCCESSFUL — funds delivered to the recipient
  • FAILED — disbursement failed (invalid number, network error, etc.); your payout balance is automatically reversed
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.
5. Poll for status if needed — GET /api/v3/withdraw/status/:reference_id.

​
Kenya-Specific Withdrawals

Two additional disbursement methods are available for Kenya: The flow is the same — initiate, wait for callback, poll if needed.

​
Bank Withdrawal

Currently supported in Kenya and South Africa. 1. Get supported banks for the target currency — GET /api/v3/withdraw/v2/bank/supporting-banks/:currency. This gives you the bank codes to use in the request. 2. Initiate the withdrawal — call POST /api/v3/withdraw/v2/bank with your callbackUrl and the recipient’s bank account details. 3. Kotani Pay notifies you via your callbackUrl when the transfer completes or fails — same event structure as mobile money withdrawals. 4. Poll for status if needed — GET /api/v3/withdraw/v2/bank/status/: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 Payouts in the left sidebar
Each row shows the reference, recipient, amount, status, and timestamp. Failed transactions show the error reason.