Integration guides

Sell with payment links

A payment link is a URL that you can share without code on your site. Each buyer who opens it gets a new checkout session and a new transaction.

On this page

Before you start
Choose an amount source
Create the link
Share the URL
Limit the link
Change the link
Track the results

Before you start#

You need an API key with checkout:write and checkout:read, and a webhook endpoint. See Payment links for the model.

Choose an amount source#

A link has exactly one amount source. amountSource.mode selects it. Fields of another source are refused.

`mode`	The buyer pays	Fields
`catalog_items`	Catalog prices and quantities.	`currency`, `lineItems` (up to 100 lines of `priceId` and `quantity`), `allowQuantityEdits`
`fixed_amount`	One amount that you set.	`currency`, `amountMinor`
`buyer_entered_amount`	An amount that the buyer enters.	`currency`, `minimumAmountMinor`, optional `maximumAmountMinor` and `suggestedAmountsMinor`

All amounts are in minor units. amountMinor: 2500 in EUR is €25.00.

When Merxian calculates tax on your account, use catalog_items. A transaction without catalog lines cannot carry calculated tax, so the other two sources can fail when a buyer opens the link.

Create the link#

Create a payment link

curl -X POST https://api.merxian.com/v1/payment-links \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team plan, annual",
    "amountSource": {
      "mode": "catalog_items",
      "currency": "EUR",
      "lineItems": [{ "priceId": "price_4Wm9TqLz2Xb7KdN8r", "quantity": 1 }]
    },
    "successUrl": "https://shop.example.com/thanks",
    "cancelUrl": "https://shop.example.com/pricing",
    "usageLimit": 100
  }'

The response is an active link with its url, for example https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc. See POST/v1/payment-links.

Put the url in an email, a message, or a button on your site. The link has no secret, so anyone with the URL can open it.

Each time a buyer opens the link, Merxian:

Uses one of the link’s uses. usageCount goes up by one.
Creates a new draft transaction from the amount source.
Creates a new checkout session for that transaction and shows the hosted page.

One link therefore makes many sessions and many transactions. A session that a link created stays usable after the link is deactivated.

Limit the link#

Field	Effect
`usageLimit`	The number of sessions that the link can create. No limit when absent.
`expiresAt`	The time, in epoch milliseconds, after which the link stops working. It must be in the future.

To stop the link at once, call POST/v1/payment-links/{paymentLinkId}/deactivate. To start it again, call POST/v1/payment-links/{paymentLinkId}/activate.

Change the link#

PATCH/v1/payment-links/{paymentLinkId} changes only the fields that you send. An absent or null field keeps its value, so you cannot clear a field with an update. An amountSource replaces the full amount source and must be complete.

A change applies to buyers who open the link after the change. Sessions that the link created before keep their transaction.

Track the results#

A link does not have its own result events. Track each visit through the events of the session and the payment:

Event	Meaning
`checkout.created`	A buyer opened the link. The payload has the new session and its `transaction_id`.
`payment.succeeded`	The buyer paid. Fulfil here.
`payment.failed`	A payment attempt failed. The buyer can try again until the session expires.
`checkout.expired`	The session ended without a payment.

To list your links, call GET/v1/payment-links.