Get started

Create a checkout session

A checkout session is a page that Merxian hosts. The buyer enters details and pays there. Your server creates the session and redirects the buyer.

On this page

Create the session
Keep the URL from the response
Redirect the buyer

Create the session#

Call POST /v1/checkout-sessions from your server. It needs the checkout:write scope.

POST /v1/checkout-sessions

curl -X POST https://api.merxian.com/v1/checkout-sessions \
-H "Authorization: Bearer $MERXIAN_API_KEY" \
-H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
-H "Content-Type: application/json" \
-d '{
  "transactionDraft": {
    "currency": "EUR",
    "lineItems": [{ "priceId": "price_4Wm9TqLz2Xb7KdN8r", "quantity": 1 }]
  },
  "successUrl": "https://shop.example.com/checkout/success",
  "cancelUrl": "https://shop.example.com/checkout/cancel",
  "clientReferenceId": "A-1042",
  "customerEmail": "ada@example.com",
  "customerCountry": "DE"
}'

const response = await fetch('https://api.merxian.com/v1/checkout-sessions', {
method: 'POST',
headers: {
  Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  'Idempotency-Key': crypto.randomUUID(),
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  transactionDraft: {
    currency: 'EUR',
    lineItems: [{ priceId: 'price_4Wm9TqLz2Xb7KdN8r', quantity: 1 }],
  },
  successUrl: 'https://shop.example.com/checkout/success',
  cancelUrl: 'https://shop.example.com/checkout/cancel',
  clientReferenceId: 'A-1042',
  customerEmail: 'ada@example.com',
  customerCountry: 'DE',
}),
})
const session = await response.json()

The Node.js example uses the built-in fetch of Node.js 18 or later. Merxian does not publish an SDK.

Field	Purpose
`transactionDraft`	The currency and the catalog prices. Merxian creates a draft transaction from them. To use a transaction that you created, send `transactionId` instead.
`successUrl`	Where the buyer goes after payment. It must use `https`. A localhost URL is allowed for local development.
`cancelUrl`	Where the buyer goes after a cancel or a failed payment.
`clientReferenceId`	Your own reference, at most 200 characters. It comes back on the session and on checkout events.
`customerEmail`, `customerCountry`	Optional. They prefill the page. The country lets Merxian calculate tax at once.
`expiresAt`	Optional. Epoch milliseconds, 30 minutes to 7 days from now. The default is 24 hours.

All fields are in the API reference.

Keep the URL from the response#

Response · 201

{
  "id": "cs_6HvB2nQx9LmT4kWpR",
  "status": "open",
  "paymentStatus": "unpaid",
  "url": "https://checkout.merxian.com/sandbox/s/cs_6HvB2nQx9LmT4kWpR?token=YOUR_SESSION_TOKEN",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "clientReferenceId": "A-1042",
  "createdAt": 1789377667000,
  "expiresAt": 1789464067000
}

Store the session id and the transactionId with your own record.

Redirect the buyer#

Send the buyer to the url with an HTTP redirect from your server, or with a link in your page. The hosted page shows the lines, the tax, and the total, and it collects the payment details. The page is in English.

After payment, Merxian sends the buyer to your successUrl. After a cancel, it sends the buyer to your cancelUrl. Neither redirect proves the result. The next step shows how to receive it.

Create the session#

Keep the URL from the response#

Redirect the buyer#

Next steps