Payment Links

Payment Links are permanent, shareable payment URLs, with no expiration date by default. Unlike Checkout Sessions, which are single-use and expire, a Payment Link can be used multiple times, by multiple different customers.

Typical use cases: a payment link in a marketing email, a buy button on a website, a QR code at the point of sale, a link shared on WhatsApp.

Payment Link vs. Checkout Session

Payment Link → permanent, reusable link, shareable at large scale. Ideal for standard products. Checkout Session → single-use session, tied to a specific Customer, expires after a delay. Ideal for personalized e-commerce carts.

Link types

Type	Usage	Required fields
`product`	Sale of one or more defined Products.	`products` (IDs)
`custom`	Free-form amount set by the merchant.	`amount`
`donation`	Open donation — the customer enters the amount.	No amount required

Endpoints

Méthode	Endpoint	Description
POST	`/payment-links/`	Create a payment link
GET	`/payment-links/`	List links
GET	`/payment-links/{id}/`	Retrieve a link
PATCH	`/payment-links/{id}/`	Update a link
DELETE	`/payment-links/{id}/`	Permanently delete
POST	`/payment-links/{id}/archive/`	Archive (disable without deleting)
POST	`/payment-links/{id}/restore/`	Restore an archived link

Is this introduction clear?

Object schema

ResponsePaymentLink object

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Advanced Excel Training",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "products": ["prod_xxx"],
  "status": "active",
  "validity_type": "limited",
  "max_usage": 100,
  "usage_count": 12,
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_url": {
    "success": "https://boutique.com/merci",
    "cancel": "https://boutique.com/panier"
  },
  "payment_method_types": ["mobile_money", "bank_card"],
  "collect_customer_info": true,
  "allow_quantity": false,
  "livemode": true,
  "metadata": { "sku": "FORM-XLS-001" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Create a Payment Link

POSTRequest body

currencyRequis

stringISO 4217ex :XAF

ISO 4217 currency code for the payment link.

payment_link_typeOptionnel

stringdéfaut :product

Link type: product, custom, or donation. Determines the required fields and the behavior of the payment page.

productsOptionnel

array[string]

List of Product IDs to sell via this link. Required if payment_link_type: product.

You can attach up to 20 products per link. If only one product is attached, the payment page displays its details directly. With multiple products, the buyer sees a selection list.

amountOptionnel

integercents

Fixed amount in cents. Required if payment_link_type: custom. Ignored for the product and donation types.

nameOptionnel

string

Name displayed as the title on the payment page. If not provided and type: product, the name of the first product is used.

validity_typeOptionnel

stringdéfaut :unlimited

Validity policy for the link.

Values: unlimited (never expires, never limited), limited (limited by max_usage and/or expires_at), one_time (usable only once — equivalent to max_usage: 1).

max_usageOptionnel

integer

Maximum number of times the link can be used. Once reached, the payment page displays an unavailability message.

Active only if validity_type: limited. Counts a usage as soon as a payment is initiated (processing status), even if the payment later fails. Useful for limited-quantity sales.

expires_atOptionnel

stringISO 8601ex :2026-12-31T23:59:59Z

Date and time the link expires. After this date, the payment page is disabled.

Active only if validity_type: limited. The link can expire before max_usage if both are set.

redirect_urlOptionnel

object

Redirect URLs after payment. Object with the keys success (URL after a successful payment) and cancel (URL if the buyer abandons).

If not provided, Sangho displays a generic confirmation page. Add ?session_id={CHECKOUT_SESSION_ID} to your success URL to retrieve the details server-side.

payment_method_typesOptionnel

array[string]

Payment methods allowed on this link. If omitted, all of the App’s active methods are offered.

collect_customer_infoOptionnel

booleandéfaut :true

If true, the payment page collects the buyer’s information (name, email) and automatically creates a Customer.

Disabling this option (false) produces anonymous payments — less data but a faster experience. Not recommended if you want to send automatic receipts.

allow_quantityOptionnel

booleandéfaut :false

If true, displays a quantity selector on the payment page. The buyer can choose how many units to purchase.

metadataOptionnel

object

Free-form data. Returned in the payment_intent.succeeded webhooks tied to this link.

Are the Payment Link parameters clear?

Create a product link

bash

curl -X POST https://api.sangho.ga/v1/payment-links/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "XAF",
    "payment_link_type": "product",
    "products": ["prod_xxx"],
    "name": "Advanced Excel Training",
    "validity_type": "limited",
    "max_usage": 50,
    "expires_at": "2026-12-31T23:59:59Z",
    "redirect_url": {
      "success": "https://boutique.com/merci",
      "cancel": "https://boutique.com/catalogue"
    },
    "metadata": { "campaign": "newsletter-march-2026" }
  }'

Response201 Created

The link is active immediately. Share link.url with your customers.

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Advanced Excel Training",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "status": "active",
  "validity_type": "limited",
  "max_usage": 50,
  "usage_count": 0,
  "expires_at": "2026-12-31T23:59:59Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

ResponseArchived link

POST /payment-links/{id}/archive/ disables the link without deleting it. The payment page becomes inaccessible but the link remains retrievable via GET.

Archiving is reversible via /restore/. Deletion (DELETE) is permanent.

json

{
  "id": "link_xxxxxxxxxxxx",
  "status": "archived",
  "updated_at": "2026-06-01T12:00:00Z"
}