Payment links

A payment link is a short URL on `pay.cimplify.io/:token` that takes payment for an _already-existing_ order. Use these for invoicing flows: you bill someone offline, generate a token, drop the link into a WhatsApp / email / SMS, and the customer clicks through to settle.

Sessions vs payment links

Concern	Checkout session	Payment link
URL shape	`/s/:sessionId`	`/:token`
Order exists yet?	No (created on submit).	Yes; the link pays an existing order.
Customer picks order type / address?	Yes	No; those came from the order.
Auth flow	OTP via `CheckoutElement`	"Sign in to Link" or "Pay as guest" choice screen, then provider selection.
Use case	E-commerce / DTC checkout.	Invoices, balance settlements, manual quotes.

What the customer sees

Order summary: line items, business name, total.
AuthChoice: "Sign in with Cimplify Link" or "Pay as guest".
If Link: a Link OTP flow loads saved methods. If Guest: the customer enters phone + provider (or card).
Provider does its thing (mobile-money push, 3DS, OTP). The page shows a processing screen with poll updates.
Success: a confirmation card. Guest customers are invited to enroll in Link with one click so the next link skips the auth choice.

When to use a payment link

You sent a quote / invoice and want a one-click pay button in the email.
You took an order via WhatsApp / phone and need to collect payment async.
The order is already in your system (POS, CRM, custom app) and you just need a remote way to settle the balance.
Subscription dunning: re-collect a failed renewal via a one-off link.

For storefronts where the customer is currently in a cart, use checkout sessions; they let the customer choose order type, fill an address, etc.

Generating a link

Payment-link tokens are created server-side off an existing order. The URL is deterministic: once you have a token, the link is https://pay.cimplify.io/<token>.

cURL

# Create a payment link for an existing order. Returns { token, url, expires_at }.
curl https://api.cimplify.io/v1/orders/<order_id>/payment-link \
  -X POST \
  -H "Authorization: Bearer $CIMPLIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Reading a link order

The hosted page reads the order via the public Pay API:

GET /v1/pay/orders/<token>          # the order summary
POST /v1/pay/orders/<token>/init    # initialize a payment (mobile money / card)
GET /v1/pay/orders/<token>/status   # poll until paid

States

The hosted page mirrors the order's payment status:

UI state	When
`loading`	Fetching the order.
`order_loaded` / `auth_choice`	Customer is choosing guest vs Link.
`guest_flow` / `link_flow`	Filling in payment provider details.
`processing`	Provider charge in progress.
`awaiting_authorization`	Approve-on-phone style challenge.
`success`	Settled. Guest sees a Link enrollment offer.
`already_paid`	Token belongs to an order that's already paid.
`error`	Couldn't load order or hit a network failure. Retry button.

Provider redirects

Some payment methods (cards via 3DS, certain mobile-money flows) require a hop through the provider's domain. The hosted page handles the round-trip: the customer is redirected out, completes the challenge, and lands back at pay.cimplify.io/<token>?reference=… where the page resumes polling and shows the success state.

Webhooks

Same as everywhere else: order.completed and payment.succeeded fire when the link successfully settles. Always treat webhooks as the source of truth.

Checkout sessions: For carts that haven't become orders yet
Orders SDK: Read / cancel an order programmatically