Core concepts

Checkout sessions

A checkout session is a hosted page where one buyer pays one transaction. You create the session, send the buyer to its URL, and Merxian collects the payment.

On this page

What a checkout session is
Create a session
The session URL
Expiry
Lifecycle
End a session
Events
What to build

What a checkout session is#

A checkout session is the buyer interface for one transaction. It is not a financial record. The transaction holds the authoritative amounts, and the session shows a summary of them.

A session ID starts with cs_, for example cs_6HvB2nQx9LmT4kWpR. On the hosted page, the buyer gives their details, sees the price with tax, can enter a promotion code if you allow it, and pays.

Create a session#

Create a session with POST/v1/checkout-sessions. Give exactly one of these:

transactionId: a draft or ready transaction that you created.
transactionDraft: catalog prices and quantities. Merxian creates the transaction.

successUrl and cancelUrl are required. The buyer returns to successUrl after payment, and to cancelUrl after a cancelled or failed payment. Both must use https, except for a localhost URL during local development.

clientReferenceId holds your own reference, for example your cart ID. It is returned with the session and in checkout events.

The session URL#

The url of the session is the hosted page, for example https://checkout.merxian.com/sandbox/s/cs_6HvB2nQx9LmT4kWpR?token=….

The hosted checkout page is in English only.

Expiry#

A session expires 24 hours after it is created, unless you set expiresAt. expiresAt is in epoch milliseconds and must be 30 minutes to 7 days from now. A session after its expiry time reads as expired.

Lifecycle#

The states of a checkout session. A double border marks a final state.

From	To	Cause
(new)	`open`	You create the session, or a buyer opens a payment link.
`open`	`payment_pending`	The buyer starts a payment.
`payment_pending`	`open`	The payment failed, and the session has not expired. The buyer can try again.
`payment_pending`	`complete`	The payment succeeded.
`open`, `payment_pending`	`expired`	The session reached its expiry time, or you expired it.
`expired`	`complete`	A payment that started before the expiry succeeded.
`open`, `payment_pending`	`cancelled`	The buyer cancelled on the hosted page.

complete and cancelled are final. The session also has paymentStatus: unpaid, pending, paid, failed, or cancelled.

In webhook payloads, complete is written completed. See the event catalogue.

End a session#

POST/v1/checkout-sessions/{sessionId}/expire ends an open or payment_pending session. After this, the buyer cannot pay on the page.

When a session ends by expiry, by your request, or by the buyer:

Merxian cancels a payment that the session started and that is still open.
If the session created its own draft transaction and no payment is in progress, Merxian also cancels that transaction.
Merxian sends checkout.expired. A buyer cancellation sends the same event, with the state cancelled.

Events#

Event	Meaning
`checkout.created`	A session was created.
`checkout.completed`	The buyer paid on the hosted page.
`checkout.expired`	The session ended without a payment.

checkout.completed tells you that the buyer finished checkout. To deliver goods, use payment.succeeded or transaction.completed, which report the money.

What to build#

Create the session on your server and redirect the buyer to its url.
Treat the return to successUrl as a display step only. It does not prove payment.
Release held stock on checkout.expired.