#When a link is enough
Most integrations need a checkout the buyer reaches from your own site or app. Some do not need an integration at all: an invoice, a deposit, a one-off sale in a chat, a price for a single product. For those, create a payment link and send the URL.
A link fixes three things — what is being paid for, the amount and the currency — and nothing else. The buyer opens it, sees the amount, presses Pay, and lands in the same hosted checkout every other payment uses. You get the same payment object, the same webhook and the same balance, so a link needs no separate reporting and no new reconciliation.
#Create a link
curl -X POST "$PAYGATE_URL/v1/payment_links" \
-H "Authorization: DPoP $ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF" \
-H "Content-Type: application/json" \
-d '{
"description": "Invoice 204 — design work",
"amount": 1500
}'
{
"id": "lnk_01JB8Z3K4Q",
"token": "9Xh2pQ...",
"description": "Invoice 204 — design work",
"amount": "1500.00",
"amount_minor": 150000,
"currency": "KES",
"active": true,
"environment": "sandbox",
"url": "https://api.paygate.example/l/9Xh2pQ..."
}
amount is major units, like every other write to the API; the response also reports it in minor units. The currency defaults to the app's collection currency. The link is created in the environment of the credential you used, so a sandbox link can never take real money.
url is the whole product: send it. It needs no authentication, no cookie and no app install.
#What the buyer sees
The link page shows the merchant name, the description and the amount, with a single Pay button. The button creates the payment and hands over to hosted checkout, where the buyer picks mobile money or card. Card details are entered on that page and never reach your server.
Reloading the link after paying opens a fresh payment, not the previous one. Every click is its own payment, with a reference that names the link (link_<token>_<suffix>), so two customers never share a reference.
#See what a link has collected
curl "$PAYGATE_URL/v1/payment_links/lnk_01JB8Z3K4Q" \
-H "Authorization: DPoP $ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF"
The response adds the payments made through the link and two totals:
{
"paid_count": 2,
"collected": "3000.00",
"collected_minor": 300000,
"payments": [
{
"reference": "link_9Xh2pQ_4f1c2a",
"status": "succeeded",
"amount": "1500.00"
}
]
}
collected counts succeeded payments only. Anything still in requires_action or processing is listed in payments but not counted, because the money has not arrived yet.
GET /v1/payment_links returns the same paid_count, collected and collected_minor on every row, so a console can show what each link has collected in one request instead of calling the detail endpoint per link.
#Close a link
curl -X POST "$PAYGATE_URL/v1/payment_links/lnk_01JB8Z3K4Q/active" \
-H "Authorization: DPoP $ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF" \
-H "Content-Type: application/json" \
-d '{ "active": false }'
A closed link explains itself to the buyer and refuses to create new payments. Payments already made through it are untouched. Sending { "active": true } reopens it at the same URL.