Core concepts

Payment links

A payment link is a reusable URL. Each buyer who opens it gets a new checkout session and a new transaction.

On this page

What a payment link is
What happens when a buyer opens it
Amount sources
Availability
Change a link
What to build

What a payment link is#

A payment link lets you sell without code on your side for each sale. You create the link once and share its URL, for example in an email or on a web page. A payment link ID starts with plink_, for example plink_4Tn8QmW1vX6kB3zLc. Its url has the form https://checkout.merxian.com/live/l/plink_….

What happens when a buyer opens it#

The link uses one of its allowed uses.
Merxian creates a new draft transaction from the amount source of the link.
Merxian creates a new checkout session for that transaction and shows the hosted page.

From here, the flow is the same as for any checkout session. You receive checkout.created, then the payment and transaction events.

Amount sources#

A link has exactly one amount source. amountSource.mode selects it. All amounts are in minor units.

`mode`	What the buyer pays	Fields
`catalog_items`	Catalog prices and quantities	`lineItems` with `priceId` and `quantity`, and optional `allowQuantityEdits`
`fixed_amount`	One fixed amount	`amountMinor`
`buyer_entered_amount`	An amount that the buyer enters within a range	`minimumAmountMinor`, optional `maximumAmountMinor`, optional `suggestedAmountsMinor`

fixed_amount and buyer_entered_amount create transactions without lines. When Merxian calculates tax for your account, a transaction must have lines, so use catalog_items.

Availability#

A link creates sessions while all of these are true:

active is true. Use POST/v1/payment-links/{paymentLinkId}/deactivate and POST/v1/payment-links/{paymentLinkId}/activate to change it.
expiresAt has not passed, when it is set. It is in epoch milliseconds.
usageCount is less than usageLimit, when a limit is set.

A deactivated link creates no new sessions. Sessions that it created before stay usable until they end.

Change a link#

PATCH/v1/payment-links/{paymentLinkId} changes the fields that you send and keeps the others. You cannot clear a field. An amountSource replaces the full amount source.

What to build#

Use checkout.created to record each session that a link creates.
Deliver on payment.succeeded or transaction.completed, as for any checkout.
Set usageLimit when you sell a limited number of units.