Payment links (dashboard)

Payment links are created and managed from the merchant dashboard, not with the organization API key. The backend requires a logged-in merchant session (same authentication as Organization & merchant).

Why: payment links are tied to your product catalog snapshot, org limits, and internal labels—operations are scoped to your Organization after staff authentication.

Authentication

Send the dashboard token:

Authorization: Token <access_token>

(The PLATFORM_NAME web app stores access_token in a cookie and attaches this header automatically.)

Do not use Api-Key for these routes—it will not authorize payment link management.

Merchant APIs (session required)

Base path: /api/payment-links/

Method	Path	Description
GET	/api/payment-links/	List payment links for your organization (includes aggregates such as paid count and revenue where implemented).
POST	/api/payment-links/	Create a link: line items from your catalog (product_id + quantity), currency, optional expires_at, max_uses, metadata.
GET	/api/payment-links/<uuid>/	Detail + dashboard stats for one link.
PATCH	/api/payment-links/<uuid>/	Update name, is_active, expires_at, max_uses, metadata.
DELETE	/api/payment-links/<uuid>/	Soft-delete (link becomes unavailable).
GET	/api/payment-links/<uuid>/payments/	List payments (transactions) collected through this link.

Create body (summary)

• name — Internal label.
• products — Array of { "product_id": "<public id>", "quantity": <n> }.
• currency — USD or EUR (defaults to USD if omitted, subject to server validation).
• pricing_mode — Optional; inherits organization default (TAX_INCLUSIVE / TAX_EXCLUSIVE).
• expires_at, max_uses, metadata — Optional.

Totals must respect organization min/max payment bounds enforced server-side.

Customer-facing (public) APIs

These endpoints are for buyers hitting a shareable URL. They do not use your API key or merchant session.

Method	Path	Description
GET	/api/payment-links/public/<link-uuid>/	Load link preview (products snapshot, amounts, org name) if the link is active and not expired or exhausted.
POST	/api/payment-links/public/<link-uuid>/start/	Start hosted checkout: billing fields, optional currency (USD / EUR), optional redirect URLs. Returns checkout session payload (e.g. checkout_url, token) for the customer to complete payment.

Errors may return 410 when the link is inactive, expired, or used up.

Relationship to API key flows

Flow	Auth
Server integration: create checkout for arbitrary line items	API key + POST /checkout/create/
Marketing link with fixed catalog snapshot	Dashboard + payment links above

Currency

Payment links use USD or EUR only, consistent with Currencies (USD & EUR).

---

See also: Organization & merchant · Create payment · Get payment by id