Skip to main content
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. If you only need to take a payment, this is the fastest way to do it — no API key, no integration, no webhook handler.

​
Before You Start

API Key

See API Keys

Fiat Wallet

For the currency you’re collecting in

Callback URL

For payment notifications

​
Create one in the Dashboard

1

Open Payment Links

Log in to the dashboard and choose Payment Links in the left sidebar.
2

Name it and set the price

Give the link a name your customer will recognise on the checkout page, then choose how the amount works:
3

Choose how they can pay

Enable the payment methods you want to accept: mobile money, bank checkout, card, or crypto. Only methods enabled for your account and currency will appear.
4

Set how many times it can be used

Single use expires after one payment — good for invoices. Limited use caps it at a number you choose. Multi use stays open until you deactivate it or it reaches its expiry date.
5

Decide what to collect

Ask for name, email or phone — each one required, optional, or off. Collect only what you actually need; every extra field costs you completions.
6

Share it

Copy the URL, or download the QR code to print or put on a screen. Both are on the link’s page in the dashboard.

​
Payment Flow

Call Create Payment Link (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 hosted link URL. 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 — customer enters their phone number; Kotani Pay sends an STK push or USSD prompt; customer confirms with their PIN
  • Bank checkout — customer is redirected to the bank’s hosted page to authenticate and authorise the payment
  • Card — 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; customer sends from their own wallet; page updates as confirmations arrive

​
3. Kotani Pay Notifies You

When a payment succeeds, Kotani Pay fires a payment.confirmed event — to the link’s own callbackUrl if it has one, otherwise to your integrator-level webhook URL. The payload carries payment-link-specific fields (referenceId, shortCode, paymentMethod, amount, currency, plus token/network/transactionHash for crypto payments) rather than the standard deposit payload — it is not the same shape as transaction.deposit.status.updated. There’s no equivalent event for a failed or expired payment — use Poll for Status to catch those. 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 payload is posted directly to your callbackUrl. See payment.confirmed in Webhooks for the full field reference.

​
4. Poll for Status

Use these endpoints to check payment status:

​
After the Payment

Each mobile money, bank, or card payment against a link becomes a normal deposit on your account, so your deposit balance is credited the same way as any other collection. Crypto payments against a link are different: they credit a separate crypto wallet balance (per network) rather than your fiat deposit balance. Settle crypto payment-link proceeds the same way as any crypto settlement — see Settlement Request. From the link’s page in the dashboard you can:
  • See every payment made through it, and its status
  • Download a PDF receipt for an individual payment
  • Deactivate the link to stop accepting payments, and reactivate it later
  • Export the transactions
If you need a link per order rather than one you share repeatedly, links can be created programmatically with the same options as the dashboard form. You can also list your links, fetch payments, and deactivate links. Payments made through a link arrive as payment.confirmed events, not standard deposit webhooks — see Webhooks for the payload.
Amounts on these deposits follow the same fee rules as the rest of your account. Check Fees & Billing before reconciling — the fee may be added on top of what your customer paid rather than taken out of it.