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 deposit is a collection — money moves from your customer into your Kotani Pay deposit balance. There are three collection methods: mobile money, bank checkout, and card.

​
Before You Start

  • An API key — see API Keys
  • A fiat wallet for the currency you’re collecting in
  • A customer record for the person paying — see Create Customer
  • A publicly reachable callbackUrl on your server

​
Mobile Money Deposit

The most common collection method across Kenya, Uganda, Tanzania, Ghana, and other markets. 1. Create the customer if you haven’t already. The customer record holds the phone number and network details needed to trigger the collection. 2. Initiate the deposit — call POST /api/v3/deposit/mobile-money with your callbackUrl. The API responds immediately with a PENDING transaction. The customer has not paid yet. 3. The customer confirms. Depending on the network:
  • M-PESA / Airtel — STK push, customer enters PIN to approve
  • MTN / others — USSD prompt or SMS confirmation
4. Kotani Pay notifies you via your callbackUrl when the transaction settles:
  • SUCCESSFUL — funds collected, your deposit balance will be credited
  • FAILED — collection failed (declined, insufficient funds, timeout)
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/deposit/mobile-money/status/:reference_id.

​
Bank Checkout Deposit

Kotani Pay generates a checkout URL and the customer completes payment on the bank’s hosted page. 1. Initiate the checkout — call POST /api/v3/deposit/bank-checkout with your callbackUrl and a redirectUrl (where to send the customer after they finish on the bank page). 2. Redirect the customer to the checkoutUrl in the response. They complete payment there. 3. Kotani Pay notifies you via your callbackUrl when the bank confirms — same event structure as mobile money. 4. Poll for status if needed — GET /api/v3/deposit/bank-checkout/status/:reference_id.

​
Card Deposit

1. Initiate the charge — call POST /api/v3/deposit/card with your callbackUrl. 2. Handle 3DS if required. If the response includes a redirect URL, send the customer there to complete 3D Secure authentication before the charge can settle. 3. Kotani Pay notifies you via your callbackUrl when the charge settles. 4. Poll for status if needed — GET /api/v3/deposit/card/status/:reference_id.

​
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 Collections in the left sidebar
Each row shows the reference, amount, status, customer, and timestamp. Click any row for the full detail including provider reference and callback history.
Successful deposits land in your deposit balance, not your payout balance. To use collected funds for withdrawals, transfer them to your payout balance first — see Balances & Settlement.