> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_links.md).
# Payment links
The payment link object and the allowed CRUD operations on the related resource endpoint
A payment link is a shareable URL that allows customers to complete a payment without going through a checkout flow. Whether a [payment session](/core-api-reference/2026-05/payment_sessions.md) is required upfront depends on the provider:
* [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md) needs a session token before it can display the payment form, so a payment session must already be associated with the link when it's created.
* [Checkout.com](/core-api-reference/2026-05/payment_setting_checkout_coms.md) also requires a payment session to already be associated with the link when it's created.
* [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md) requires no session upfront — one is created automatically once the customer completes the checkout, via the `checkout.session.completed` webhook event. The link is a Stripe payment link that accepts a single completed payment, after which Stripe deactivates it.
{% hint style="success" %}
Adyen, Checkout.com, and Stripe payment settings support payment link creation.
{% endhint %}
{% hint style="warning" %}
Creating a link against any other payment setting is rejected with a `422 Unprocessable Entity` error.
{% endhint %}
A payment link can optionally be associated with an [order](/core-api-reference/2026-05/orders.md). When it is, `amount_cents` and `currency_code` can be omitted and derived automatically instead of set explicitly (more details [below](#amount-and-currency)), and product details are shown on the gateway's hosted page. When it isn't, the link is a standalone request for an explicit amount, with no product breakdown — useful for invoice-style payment flows, payment recovery scenarios, or [order editing](/core-api-reference/2026-05/orders.md#order-editing) scenarios where the updated total exceeds the previously authorized amount: rather than reattaching the whole order, a payment link for just the outstanding delta can be created with a matching order-less payment session.
{% hint style="info" %}
A payment link is tied to a single payment setting and a single amount. Once a payment link is completed or expired, a new one must be created for another payment attempt.
{% endhint %}
## Lifecycle
A payment link transitions through the following statuses:
Status
Description
open
The link is active and can be used to initiate a payment.
expired
The link has expired and can no longer be used.
completed
A successful payment has been made via this link.
{% hint style="info" %}
Adyen and Checkout.com links expire at the gateway. Stripe links never expire on their own: they become `expired` only when cancelled via the [cancel trigger](#triggers).
{% endhint %}
## URLs
Each payment link has two URL attributes:
* `url` — the payment link URL generated by the payment provider, shared with the customer, read-only. For Stripe, it carries the order number, the customer email, and the locale as query parameters, so that the hosted page is prefilled.
* `return_url` — the URL the customer is redirected to after completing the payment, optional.
{% hint style="info" %}
No gateway requires a return URL for the payment link itself. When you omit it, the customer simply stays on the gateway's hosted page once the payment is completed — Stripe shows its own confirmation page, while Adyen shows no **Continue** button at all.
{% endhint %}
{% hint style="warning" %}
The payment session an Adyen link requires is a separate matter: Adyen rejects the session creation unless a return URL is provided in the session's `client_data`, even when the link has none.
{% endhint %}
## Session
A payment link is associated with a payment session — either supplied at creation time (Adyen, Checkout.com) or created automatically once payment completes (Stripe). Once associated, the session is accessible via this relationship and contains the transaction history for the payment made through the link.
Where the session is supplied, it's passed through the `payment_session` relationship in the creation request, and it must already exist: Adyen and Checkout.com build their link request from the session token, so there's nothing to send the gateway without one.
{% hint style="warning" %}
Creating an Adyen or Checkout.com payment link without a payment session is rejected with a `422 Unprocessable Entity` error. For Stripe the relationship is left empty at creation and filled in later by Commerce Layer.
{% endhint %}
## Amount and currency
Both `amount_cents` and `currency_code` can be set explicitly at creation time. When omitted, they default to the associated payment session's amount and currency, or — if no session is present yet — to the associated order's outstanding amount and currency. Neither attribute can be changed after creation.
{% hint style="info" %}
When both a payment session and an order are omitted, amount and currency must be provided explicitly.
{% endhint %}
{% hint style="warning" %}
A payment link is created with one amount, which can't be updated afterwards — just like a payment session's. The amount a link was created with is the amount the customer is charged, and it stays fixed for the life of the link even if the order's outstanding amount changes in the meantime, since none of the supported gateways allows changing a payment link's amount. If you need to collect a different amount, [cancel](#triggers) the link and create a new one.
{% endhint %}
## Billing address
A payment link's billing address is either inherited from the associated order or provided directly via the `billing_address` relationship — the latter takes precedence when both are present. When available, it's sent to the gateway along with the payment link creation request.
{% hint style="warning" %}
Checkout.com requires a billing address in its payment-link creation request: if the associated order has no billing address and none is provided directly on the link, creation fails — the request never reaches the gateway. Adyen and Stripe don't require it.
{% endhint %}
## Display name
The optional `name` attribute lets you control what's shown on the gateway's hosted page, instead of relying on Commerce Layer's defaults (e.g. Stripe falling back to `Order #` or `Payment` when no order is associated). Support depends on the provider:
* **Adyen** and **Checkout.com** — sent as the top-level `description` field of the payment link request.
* **Stripe** — used as the payment link's single line item product name.
## Gateway options
At creation time, a payment link accepts an `options` object whose values are passed straight through to the underlying payment provider, following the same rules as [payment sessions](/core-api-reference/2026-05/payment_sessions.md#gateway-options).
## Triggers
A payment link supports the following trigger attributes:
* `_refresh` — syncs the link status with the provider (e.g. marks the link as completed if the payment was made in the meantime). It doesn't change the link amount.
* `_cancel` — cancels the link.
* `_internal_version` — forces a specific supported [internal payload version](/core-api-reference/2026-05/payment_settings.md#per-request-overrides) for this link's creation request.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_links.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.