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

# Payment links

> A link to share by WhatsApp or SMS. The payer picks M-Pesa or their wallet.

`POST /v1/merchants/{merchantID}/links` needs the `links` scope.

```bash theme={null}
curl -X POST https://api.cloudpay.africa/cloudpay/v1/merchants/$MERCHANT_ID/links \
  -H "Authorization: Bearer $CLOUDPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 350000, "reference": "Order 1042", "max_uses": 1, "expires_at": "2026-11-30T23:59:59+03:00" }'
```

| Field | |
| - | - |
| `amount` | Fixes the amount, in whole KES, written in cents (a multiple of `100`). Leave it out to let the payer choose. |
| `reference`, `description` | Shown to the payer. Up to 100 and 200 characters. |
| `max_uses` | Turns the link off after this many completed payments. |
| `expires_at` | Turns the link off at this time. |
| `till_id` | The till that receives the money. Defaults to your first till. |

The response carries the link's `code`. Share `https://api.cloudpay.africa/cloudpay/pay/{code}`. To turn a link off or back on, use `PATCH …/links/{linkID}`.

## QR codes

Every link also has a QR code, with the Cloudpay logo in the middle:

```text theme={null}
https://api.cloudpay.africa/cloudpay/pay/{code}/qr.png?size=512
```

The QR carries the link itself. The amount, reference and till all come from Cloudpay when it's scanned, so the payer has nothing to type except their M-Pesa PIN. That removes wrong amounts and wrong account numbers. Put it on invoices, receipts, delivery notes or a screen at the counter.

* `size` is 128 to 1024 pixels; the default is 512. Each size scans reliably with the logo in place.
* The `X-Pay-URL` response header gives the URL the QR encodes.
* In the dashboard, each link under **Payment links** shows its QR. Click it to open a full-size copy you can print.

A payer who opens a link that can't take payments sees a clear page. Through the API, the link returns:

| Code | Why |
| - | - |
| `403 link_inactive` | You turned it off |
| `403 link_expired` | Past `expires_at` |
| `403 link_used_up` | `max_uses` reached |
| `400 link_amount` | The payer tried a different amount on a fixed-amount link |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.