Payment Links
Shareable hosted checkout pages
Create a payment link
Generates a shareable payment link programmatically. The owning business is taken from your API key, so business_id is not accepted in the body.
Tagging: links created through this endpoint are tagged as programmatic. Every payment made on such a link produces a gateway payment entry and triggers your configured webhooks (payment.success / payment.failed) — unlike links created in the dashboard.
Redirects: success_redirect_url and failure_redirect_url must be HTTPS (HTTP is allowed only for localhost). The hosted checkout redirects the payer there after the payment resolves.
Advanced: supports variants, tiered pricing, custom amounts, inventory items, required fields and images for full parity with the dashboard.
Where to send the customer: the response carries checkout_url, the hosted page for this link. Store it rather than building it from the short code yourself. A sandbox link's URL carries ?type=sandbox — keep the query string intact, or the page looks for the link in live data and 404s.
Headers
Idempotency-KeyA unique key you generate per operation (a UUID is ideal). If a request with the same key has already completed, its original response is replayed instead of the operation running twice, and the response carries Idempotent-Replayed: true. Keys are remembered for 24 hours and are scoped to your business. Reusing a key with a different body is an error.
Create a payment link › Request Body
titleName shown on the checkout page
amountAmount to collect, in whole XAF. Minimum 100.
descriptionDescription shown to the payer
currencyCurrency (defaults to XAF)
allow_multiple_paymentsAllow the link to be paid more than once
max_paymentsCap the number of payments allowed
success_redirect_urlHTTPS URL the payer is redirected to after success
failure_redirect_urlHTTPS URL the payer is redirected to after failure
expires_atExpiry timestamp (ISO 8601)
Extra fields the payer must complete
cover_image_urlCover image URL
image_urlsAdditional image URLs
typeLink type: STANDARD, INVENTORY_ITEM or DONATION
inventory_item_idInventory item id (when type is INVENTORY_ITEM)
allow_custom_amountLet the payer choose the amount
min_amountMinimum amount when allow_custom_amount is true. Cannot go below 100.
max_amountMaximum amount when allow_custom_amount is true
quantity_enabledAllow the payer to choose a quantity
has_variantsWhether the link has variants
has_tiered_pricingWhether the link has tiered pricing
custom_slugCustom URL slug (must be unique)
tagsOrganizational tags
Product variants
Quantity-based pricing tiers
Create a payment link › Responses
Delete a payment link
Permanently removes the link. Returns 204 with an empty body.
Use POST /payment-links/{id}/deactivate instead if the link has taken payments — deleting loses the association with them.
path Parameters
idPayment link id
Delete a payment link › Responses
Deleted. No body is returned.
Update a payment link
Partially updates a link: send only the fields you want to change.
Not updatable on purpose: the structural properties chosen at creation — type, inventory item, custom slug and custom-amount bounds. Changing them on a link that already has payments would retroactively alter what a customer agreed to pay, so they are fixed for the life of the link. Create a new link instead.
cover_image_url and image_urls must point at our storage host; get one from POST /files/upload-url.
path Parameters
idPayment link id
Update a payment link › Request Body
titleLink title
descriptionLink description
amountAmount in whole XAF. Minimum 100.
cover_image_urlCover image URL
image_urlsAdditional image URLs
allow_multiple_paymentsAllow the link to be paid more than once
max_paymentsMaximum number of payments
success_redirect_urlRedirect URL after a successful payment
failure_redirect_urlRedirect URL after a failed payment
expires_atExpiry timestamp (ISO 8601)
statusLink status
Update a payment link › Responses
Deactivate a payment link
Stops the link accepting new payments while keeping the link and its payment history intact. The hosted page then shows the link as closed rather than 404-ing.
Prefer this over DELETE for any link that has already been paid: deleting loses the association with those payments.
Deactivating is reversible — PATCH the link with status: "ACTIVE" to reopen it.
path Parameters
idPayment link id