The new Payments API. Built for how people pay now.
Commerce Layer’s new Payments API introduces a more composable model for handling multiple payments, wallets, gift cards, payment links, and asynchronous transactions.
Commerce Layer began with a payment model designed around how online shopping worked: one order, one payment method, one payment flow. A shopper chose how to pay, placed the order, and the payment moved forward with it.
As payments evolved, so did Commerce Layer. New gateways, digital wallets, gift cards, and alternative payment methods gave shoppers more ways to pay, and Commerce Layer grew to support them.
Now shopper expectations are evolving again.
Paying with one method is no longer always enough. Shoppers want to combine payment methods: split a purchase across two cards, pay part by card and part with PayPal, redeem multiple gift cards on the same order, or move through payment flows that continue outside the checkout and return later.
The new Payments API is built for this new reality.
A payment is no longer simply part of an order's transition. It becomes a resource with a life of its own: one that can be created, followed, changed, settled, and, when necessary, fail independently. An order can have multiple payments, each with its own method, amount, and lifecycle.
This is more than support for additional payment methods. It changes what a payment can be, making it possible to compose multiple payments around a single order and build checkout experiences that match how shoppers want to pay today.
That distinction is the foundation for everything that follows.
The model at a glance
The new Payments API is made of five resources. Each one does a single job, and together they describe everything that happens between an order and the money that pays for it.
Read the diagram from the order outwards:
- Payment setting
Where a shopper can pay. It is a gateway configured for a market, together with its credentials. Stripe, Adyen, PayPal, a gift card or a manual method all have the same shape. - Payment session
One attempt to pay part, or all, of an order through one setting. An order can have as many sessions as it needs. - Payment transaction
What the gateway actually did, whether an authorization, a capture, a void or a refund. Transactions hang off a session, and each one keeps track of the balance its children draw from. - Payment wallet
A saved payment method that belongs to the customer, not to an order. Any session on any order can reuse it. - Payment link
A hosted page where the shopper completes a session when there is no checkout to embed it in.
The order is no longer where payment logic lives. It is what payments are attached to, and its payment status is the sum of its sessions.
One order, three payments
Take an order for €100 that a shopper pays with a €30 gift card and €70 by credit card.
The checkout opens two sessions: one through the gift card setting for €30 and one through the card setting for €70. Each session records its own authorization transaction. When the gift card authorizes and the card is still pending, the order is partially authorized, and the system treats that as a valid state. When the card authorizes too, the two sessions cover the total and the order counts as authorized.
A week later, before shipping, the merchant edits the order and the total rises to €120. Under the classic workflow that increase would hit a ceiling. Here, a third session covers the €20 difference, and a payment link sends the shopper to the gateway's hosted page to pay it. If the shopper had saved their card in a wallet, the session could have charged it directly. The first two payments stay exactly as they were.
At fulfillment, each authorization is captured separately. If the shopper returns an item, the refund goes against the capture it reverses, and nothing is recalculated on the order as a whole.
None of this needed a feature for split payments, multiple gift cards or post-placement charges. It is the same five resources, combined differently.
Payment setting
A payment setting is a merchant's configured gateway:
- Stripe
- Adyen
- PayPal
- Braintree
- Checkout.com
- A gift card
- An external processor
- A manual payment method
The credentials live here, and every other payment resource has a route back to it. Sessions and wallets connect to it directly, and transactions reach it through their session.
Gift cards are settings too, and that is a real departure from the classic workflow. There, a gift card behaved more like a discount: its value was calculated and taken off the order total. Here it is a gateway like any other. It has sessions, authorization, capture and refund flows, and a balance that can be reconciled. That is why the gift card in the example above needed no special handling, and why two gift cards on one order are simply two sessions.
Every payment setting belongs to a market, and a store can narrow or extend which of those settings its checkout actually offers. Nothing downstream can exist without that relationship: a session cannot validate against a gateway that the order's market has not configured.
The boundaries are established before the payment begins.
Payment session
A payment session is one attempt to collect money through one gateway for one order, up to what the order still owes.
Its status records how far that attempt has gone:
Status | Meaning |
|---|---|
| Nothing has happened yet. |
| Funds are reserved. |
| Part of the authorization has been captured. |
| All of the authorization has been captured. |
| The authorization was released before any capture. |
| Something that appeared settled turned out not to be. |
A session has firm boundaries. It holds at most one authorization, and at most one void against that authorization. The authorization can have many captures, and each capture many refunds. A second authorization, though, is not a retry inside the same session: it is a new session.
The last two statuses close a session without collecting anything. A void is deliberate: the merchant releases funds it no longer needs. An invalidation comes from outside, typically a decline that the gateway reports after an authorization looked successful (see Payment transaction below). Neither counts toward what the order has collected.
Payment transaction
If the session is the attempt to collect money, the transaction is the record of what the gateway actually did.
Each authorization, capture, void and refund is a resource of its own, and each parent tracks its remaining balance against its children. A partial capture belongs to the authorization that produced it, and a partial refund belongs to the capture it reverses. The arithmetic no longer has to be rebuilt against the order as a whole.
In the classic workflow, a transaction is a side effect. A trigger attribute fires on the order, the gateway is called, and the transaction is returned afterwards as evidence of what happened.
The new Payments API turns that around. You create a transaction directly, and it has its own request, its own response and its own event stream. Creating it queues the call to the gateway asynchronously, so the transaction enters its own workflow without holding open the request that created it.
Creation doesn't always start with your API call. Some gateways are built around hosted, browser-driven flows in which the shopper's browser talks to the gateway directly. In those cases the result comes back as an event on the payment session, and the transaction is created without any client asking for it.
Every transaction starts as pending. From there it can move to requires_action while it waits on the shopper (a 3DS challenge or a redirect, for example) or to processing while it waits on the gateway. It ends as succeeded, declined, failed, canceled or expired.
Even a successful outcome is not necessarily final. A gateway may report a decline after an authorization that looked successful. The transaction can reflect that failure after the original response, and its session moves to invalidated. In the classic workflow, an integration had no state in which to represent this.
Payment wallet
In the classic workflow, a saved card travels with the order: the payment source is created as part of the checkout and stays with that order. This fits an order-centric flow, where each payment begins and ends with its order.
A payment wallet takes a different approach. It belongs to a customer and a payment setting rather than to an order, so whether it holds a stored card, a saved PayPal account or a tokenized wallet, it can be addressed in its own right.
A wallet has its own lifecycle, separate from any transaction. It starts as pending and may pass through requires_action (to authenticate the card, for example) and processing. It ends as succeeded or canceled. Once it has succeeded, any session on any order can reference it without asking the shopper for their payment details again.
Two consequences follow:
- Customers can manage saved methods directly
They can add one, remove one, or change what is available to them, without needing an order in progress. - Order subscriptions can point straight at a wallet
Each recurrence opens a new session against it, with no need to refer to the order that started the subscription. The order subscription owns its payment method.
Payment link
A payment link is a hosted payment page tied one-to-one to a payment session. It starts as open and ends as completed or expired.
It covers a simple case: there is no checkout UI to embed, and the merchant needs to give the shopper somewhere to pay. The link can go out by email or message, and the gateway's own hosted page handles the payment experience.
The order is still part of that experience, because the link is built from it. Some gateways construct their hosted page from the order's contents, so the shopper sees what they are paying for rather than a bare amount.
Payment links are currently available for Adyen, Stripe and Checkout.com, because not every gateway offers a hosted-page product that fits this model. Sessions and transactions are fundamental to the new Payments API: payment links are deliberately not universal.
What changes for the order
Once payments are resources of their own, the order's relationship to them changes in three ways.
Payment status is a sum
The order's payment status no longer reflects a single payment event. It is the combined state of all its sessions, recalculated whenever one of them changes. Fulfillment keeps its own state and its own concerns, and payment no longer has to follow it. An order can legitimately be placed while only partly authorized across two sessions. That is a state the system understands, not one to work around.
Payment rules set the bar
By default, an order counts as authorized only when its sessions cover the total in full; anything less is partial, and the status says so. Payment rules decide what follows from that:
- A market can block placement unless the sessions cover a given percentage of the order, or a given amount.
- An order with no payment at all can be refused outright.
- Rules can also act on the settings themselves, making a gateway available only above a certain order total, or only to customers with a certain tag.
The classic workflow guaranteed these things by its structure. Here, the merchant states them deliberately.
Placement is no longer a ceiling
In the classic workflow, an order's total could not rise above the amount it was placed with. Sessions remove that limit. When an edit increases the total, another session covers the difference, either charged to a saved wallet or collected through a payment link, as in the €120 example above. The original payments stay untouched.
A payment no longer has to be one event. It can be a sequence of deliberate ones.
What this makes possible
What the new Payments API ultimately provides is composability.
Once a payment is a resource rather than a property of the order, unusual cases stop requiring unusual architecture:
- A total can be split between two credit cards and two gift cards.
- An order can be edited upward after placement, with the difference collected through another session.
- A subscription can charge a stored wallet.
- A checkout can hand the shopper to a gateway's hosted page and wait for the answer to come back.
None of these is a separate feature. They all follow from the same decision to make sessions, transactions, wallets and links independently addressable resources.
Start simple, stay on one model
The new Payments API isn't reserved for complex checkouts. It is the way to take payments on Commerce Layer, including the simplest case.
One gateway, one method, one payment: that is a single session with a single authorization. SDKs and prebuilt components handle the session, the transaction and the gateway wiring, so the integration is no larger than the classic one. Most of the machinery described here belongs to the API, not to your code.
The classic workflow did offer one guarantee for free: an order is placed if and only if its one payment succeeds. On the new Payments API, that guarantee is a single payment rule that requires sessions to cover the full total before placement. Configure it once and a straightforward checkout behaves exactly as it always has.
Even in the simple case, you get more:
- Every payment is visible. Each one has its own resource, status and event stream, instead of being a side effect of an order transition.
- Late outcomes have somewhere to land. Asynchronous results and delayed declines are recorded where they belong, not lost after the original response.
- Saved methods outlive the order. A card the shopper saves belongs to them, not to the order that created it.
You also get room to grow. When you add gift cards, start editing orders after placement, charge subscriptions to saved wallets or send payment links, you don't need a migration or a second integration. The checkout you built for one payment already works on the model those cases depend on.
Adopting it is also low-risk. It is explicit: the market needs its payment settings configured, and the client declares the new API version. It is also incremental. The two workflows coexist in the same market, so you can move one checkout at a time. Orders already on the classic workflow finish there, because the API keeps each order on a single workflow: a payment session cannot attach to an order with a payment source, and a payment source cannot attach to an order with sessions.
Start with one session. Add the second when you need it.