Skip to main content
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.
You need an API key and a reachable callbackUrl — see the Quickstart if you haven’t set those up. For this flow you also need a funded payout balance in the disbursement currency, and a customer record for the recipient.

​
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 Mobile Money Withdrawal 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 for both modes, and the withdrawal payload for every field you receive with a worked example.
5. Poll for status if needed — Mobile Money Withdrawal Status.

​
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/customer/support/banks. This gives you the bank codes to use in the request. 2. Initiate the withdrawal — call Bank Withdrawal 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 — Bank Withdrawal Status.

​
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.