> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kotanipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Links

> Create a hosted payment page and collect payments via mobile money, bank, card, or crypto.

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

<CardGroup cols={3}>
  <Card title="API Key" href="/v3/getting-started/api-keys">
    See API Keys
  </Card>

  <Card title="Fiat Wallet" icon="wallet">
    For the currency you're collecting in
  </Card>

  <Card title="Callback URL" icon="webhook">
    For payment notifications
  </Card>
</CardGroup>

## Create one in the Dashboard

<Steps>
  <Step title="Open Payment Links">
    Log in to [the dashboard](https://backoffice.kotanipay.com) and choose
    **Payment Links** in the left sidebar.
  </Step>

  <Step title="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:

    | Pricing             | Use it for                                       |
    | ------------------- | ------------------------------------------------ |
    | **Fixed**           | One product or service at one price              |
    | **Variable**        | Customer enters an amount within a range you set |
    | **Package**         | A few preset tiers to pick from                  |
    | **Customer choice** | Customer decides — donations, tips, top-ups      |
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Link types

| Type         | What it's for                                                     |
| ------------ | ----------------------------------------------------------------- |
| **Standard** | General collection — products, services, bookings                 |
| **Invoice**  | A specific amount owed by a specific customer, usually single use |
| **Donation** | Open-ended giving, usually customer-choice pricing and multi use  |

## Payment Flow

### 1. Create the Payment Link

Call [Create Payment Link](/v3/api-reference/payment-links/create) (`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](/v3/essentials/webhooks).

### 4. Poll for Status

Use these endpoints to check payment status:

* [`GET /api/v3/payment-links/transactions/:referenceId`](/v3/api-reference/payment-links/list-transactions) — status of a specific payment
* [`GET /api/v3/payment-links/:shortCode/transactions`](/v3/api-reference/payment-links/list-transactions) — all payments for a given link

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

## Creating Links from the API

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](/v3/api-reference/payment-links/list), [fetch payments](/v3/api-reference/payment-links/get), and [deactivate links](/v3/api-reference/payment-links/deactivate).

Payments made through a link arrive as normal deposit webhooks, so if you already
handle deposits you already handle these. See the
[deposit payload](/v3/essentials/webhooks).

<Note>
  Amounts on these deposits follow the same fee rules as the rest of your account.
  Check [Fees & Billing](/v3/essentials/billing-types) before reconciling — the fee
  may be added on top of what your customer paid rather than taken out of it.
</Note>

## Related

* [Fees & Billing](/v3/essentials/billing-types) — who pays the fee, and rounding
* [Webhooks & Events](/v3/essentials/webhooks) — get told about payments automatically