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 payment link is a hosted checkout page that Kotani Pay generates for you. Create the link once, share the URL anywhere, and Kotani Pay handles the checkout experience. No need to build your own payment form.

​
Before You Start

  • An API key — see API Keys
  • A fiat wallet for the currency you’re collecting in
  • A callbackUrl on your server for payment notifications
Call POST /api/v3/payment-links. At a minimum you’ll configure:
  • Pricing type — fixed amount, variable (customer chooses within a range), package tiers, or open customer choice
  • Payment methods — which of mobile money, bank checkout, card, and crypto to enable
  • Usage limit — single-use, limited to a max count, or unlimited
  • callbackUrl — where to receive payment notifications
The response includes the link URL (e.g. https://pay.kotanipay.com/l/{shortCode}). Share it via SMS, email, social, or embed it as a button.

​
2. Customer Pays

The customer opens the link in their browser. What happens next depends on the method they select:
  • Mobile money — the customer enters their phone number; Kotani Pay sends an STK push or USSD prompt; the customer confirms with their PIN
  • Bank checkout — the customer is redirected to the bank’s hosted page to authenticate and authorise the payment
  • Card — the customer enters card details on a secure page; 3DS challenge is handled inline if required
  • Crypto — Kotani Pay shows a deposit address and QR code; the customer sends from their own wallet; the page updates as confirmations arrive

​
3. Kotani Pay Notifies You

Payment link transactions are backed by standard deposit transactions. When a payment settles, Kotani Pay fires a transaction.deposit.status.updated event to your callbackUrl. The payload includes the standard deposit fields plus identifiers for the originating payment link.
  • SUCCESSFUL — payment received, your deposit balance will be credited
  • FAILED — payment failed or timed out
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.

​
4. Poll for Status

  • GET /api/v3/payment-links/transactions/:referenceId — status of a specific payment
  • GET /api/v3/payment-links/:shortCode/transactions — all payments for a given link

​
Monitoring from the Dashboard

  1. Log in to backoffice.kotanipay.com
  2. Navigate to Payment Links in the left sidebar
  3. Click any link to see all transactions associated with it