Payment links
Create a reusable payment link, share it, deactivate it, and find the payments it produced.
A payment link is a page hosted by 221 Pay, with a fixed amount. The customer chooses a rail among those active on the account, enters their mobile number and pays. The link is reusable: each form submission creates an ordinary payment of the project.
Typical use: sales over messaging apps or social networks, an invoice sent by SMS, no payment page to integrate.
Create a link
curl -X POST "$API_URL/v1/payment-links" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "15000",
"description": "Weekly vegetable basket",
"return_url": "https://shop.example/thanks",
"expiry": "2026-12-31T23:59:59Z"
}'| Field | Required | Description |
|---|---|---|
amount | yes | Amount in XOF, strictly positive digit string. |
description | yes | 1 to 80 characters, shown to the customer. |
return_url | no | https:// URL the customer returns to after paying. |
expiry | no | Future RFC 3339 date. Without expiry, the link does not expire. |
{
"id": "4b0e2d7a-91c3-4f1e-8a6d-0c5b7e2f9d13",
"amount": "15000",
"currency": "XOF",
"description": "Weekly vegetable basket",
"status": "active",
"created_at": "2026-10-07T10:00:00Z",
"expiry": "2026-12-31T23:59:59Z",
"link_to_pay": "https://…/p/4b0e2d7a-91c3-4f1e-8a6d-0c5b7e2f9d13"
}Share link_to_pay: by message, printed QR code or a button on a website.
Statuses
| Status | Meaning |
|---|---|
active | The link accepts payments. |
inactive | Deactivated by the merchant; the page tells the customer the link is unavailable. |
expired | expiry date passed. An expired link cannot be reactivated: create a new one. |
Deactivate or reactivate
curl -X POST "$API_URL/v1/payment-links/$LINK_ID/status" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "inactive"}'status is active or inactive. Reactivating an expired link returns
400 INVALID_REQUEST.
Read and list
curl "$API_URL/v1/payment-links/$LINK_ID" -H "Authorization: Bearer $API_KEY"
curl "$API_URL/v1/payment-links?status=active&limit=20" -H "Authorization: Bearer $API_KEY"Filters: status, from, to (RFC 3339), limit (1 to 100), offset. The
response contains data and total_count.
Payments from a link
Each payment started from a link carries a merchant_reference of the form
link:{link id}:{attempt id}. Find them:
curl "$API_URL/v1/payments?q=link:$LINK_ID" -H "Authorization: Bearer $API_KEY"Each one also returns payment_link_description, the link's description, more
readable than the merchant_reference. These payments follow the normal lifecycle and trigger the same webhooks
(payment.succeeded, payment.failed, payment.expired). See
Payments.