Overview

Quickstart

Create a checkout session in sandbox, pay it, and read the result. You need a sandbox API key and one catalog price.

On this page

Before you start
Steps
What happened

Before you start#

You need:

A Merxian account. See Create an account.
A sandbox API key that starts with mx_sandbox_ and holds the scopes checkout:write and checkout:read. See Get an API key.
The ID of a price that you created in the dashboard, in the sandbox environment, for example price_4Wm9TqLz2Xb7KdN8r.

Put the key in an environment variable. The examples read it from there.

Shell

export MERXIAN_API_KEY="YOUR_SANDBOX_API_KEY"

Steps#

Create a checkout session.

Send the price in transactionDraft. Merxian creates the transaction and the session.

Create a checkout session

curl -X POST https://api.merxian.com/v1/checkout-sessions \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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"
  }'

Keep the id and the url from the response.

Response · 201

{
  "id": "cs_6HvB2nQx9LmT4kWpR",
  "status": "open",
  "url": "https://checkout.merxian.com/sandbox/s/cs_6HvB2nQx9LmT4kWpR?token=YOUR_SESSION_TOKEN",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "expiresAt": 1789464067000
}

The response has more fields. Only this response has the access token in url. A later read returns the URL without it.

Open the url in a browser and pay.

The sandbox checkout page accepts test payment details only. No real money moves.
Receive the result.

When the payment succeeds, Merxian sends checkout.completed and payment.succeeded to your webhook endpoint, if you have one. Set one up in Receive the result.

Read the session.

Retrieve a checkout session

curl https://api.merxian.com/v1/checkout-sessions/cs_6HvB2nQx9LmT4kWpR \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

After a successful payment, status is complete and paymentStatus is paid.

What happened#

Merxian created a transaction from the price. When tax applies to your account, Merxian calculated it.
The buyer paid on the hosted page. Merxian created a payment and captured it.
Merxian sent events for the session, the payment, and the transaction.

Before you start#

Steps#

What happened#

Next steps