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 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 — 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

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. Possible statuses:
  • 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

Use these endpoints to check payment status:

​
After the Payment

Each payment against a link becomes a normal deposit on your account, so your payout balance is credited the same way as any other collection. 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 normal deposit webhooks, so if you already handle deposits you already handle these. See the deposit 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.