Checkout Sessions API

Integration style

Embedded checkout (confirming a session directly from your frontend with your publishable key) is not currently available— 3-D Secure requires the card to be entered on Saleonix's own page in both TEST and LIVE. See "Confirm a session" below.

A session charges in exactly one of three modes:

• Price mode — pass price_id (+ optional quantity); the amount is read from your catalog on the server.
• Line items mode (WooCommerce, Shopify, and other cart-plugin integrations) — pass line_items, an array of up to 100 { price_id, quantity } entries; each is resolved from your catalog exactly like price mode, and amount_total is the sum. Use this when a cart contains several distinct registered products — Saleonix is merchant of record and needs to know what was actually sold, not just the total.
• Amount mode (off by default) — pass amount (+ required description); your server states the total directly, with no catalog link. This requires the Amount-mode checkout permission, which Saleonix grants per account on request; without it, requests containing amount are rejected with 400 amount_mode_unsupported. Use price_id or line_items instead.

Passing more than one (or none) of price_id / amount / line_items is rejected. In all threemodes the customer's browser never carries an amount — only your server decides what is charged.

What is required

No single parameter is required on its own. What the endpoint requires is that the body carries exactly one mode selector — either price_id or line_items (or amount, which is disabled). Sending none of them, or more than one, returns 400 parameter_invalid. Choose by what the customer is buying:

Inside line_items, each entry's price_id is required and its quantity is optional (defaults to 1). Every parameter outside the mode selector is optional. The smallest valid request is therefore a single field:

{
  "price_id": "clpr1ce..."
}

The Content-Type: application/json header is required on this endpoint; the Idempotency-Key header is optional but strongly recommended (see below). There is no currency parameter — sending one returns currency_unsupported.

Working with metadata

metadata is a free-form key/value bag for your own bookkeeping — your internal order id, cart id, customer reference, campaign, whatever lets you match a Saleonix session back to a record in your system. Saleonix never interprets it; it is stored with the session and echoed back verbatim on every read, on the hosted checkout result and in webhook payloads.

{
  "price_id": "clpr1ce...",
  "metadata": {
    "order_id": "1066",
    "cart_id": "c_9f2a",
    "customer_ref": "CUST-4471",
    "source": "woocommerce",
    "items": 3,
    "gift": true
  }
}

Rules, all enforced at create time:

• It must be a flat JSON object — arrays, strings and nested objects are rejected with metadata_invalid.
• At most 20 keys. Each key must be 1–40 characters.
• Values may be strings, numbers or booleans only. Numbers and booleans are coerced to strings, so { "qty": 3 } reads back as { "qty": "3" } — compare as strings on your side. null, arrays and objects as values are rejected.
• Each value is at most 500 characters after coercion.
• Omitting metadata (or sending null) is fine — reads then return an empty object, {}, never null.
• Metadata is part of the idempotency request hash: replaying an Idempotency-Key with different metadata returns 409 idempotency_key_reused.

Price mode

curl -X POST https://saleonix.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "price_id": "clpr1ce...",
    "quantity": 1,
    "success_url": "https://example.com/thanks",
    "customer_email": "buyer@example.com",
    "metadata": { "internal_ref": "12345" }
  }'

Line items mode (carts / WooCommerce / Shopify)

# A cart of 2 distinct registered products (WooCommerce/Shopify-style)
curl -X POST https://saleonix.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wc-order-1066" \
  -d '{
    "line_items": [
      { "price_id": "clpr1ce1...", "quantity": 2 },
      { "price_id": "clpr1ce2...", "quantity": 1 }
    ],
    "success_url": "https://shop.example/thanks",
    "customer_email": "buyer@example.com",
    "metadata": { "order_id": "1066" }
  }'

Amount mode (requires the Amount-mode checkout permission)

# A cart of 3 items + shipping − coupon = €43.18 → amount: 4318 (cents)
curl -X POST https://saleonix.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wc-order-1066" \
  -d '{
    "amount": 4318,
    "description": "Order #1066 — example-shop.com (3 items incl. shipping)",
    "success_url": "https://shop.example/thanks",
    "customer_email": "buyer@example.com",
    "metadata": { "order_id": "1066" }
  }'

Response 201

{
  "id": "cs_test_aBcD...",
  "object": "checkout.session",
  "url": "https://saleonix.com/checkout?sid=...&exp=...&sig=...",
  "client_secret": "cs_test_aBcD..._secret_XyZ...",
  "status": "open",
  "payment_status": "unpaid",
  "livemode": false,
  "currency": "eur",
  "amount_subtotal": 10000,
  "amount_tax": 1800,
  "amount_total": 11800,
  "quantity": 1,
  "price_id": "clpr1ce...",
  "product_id": "clxyz...",
  "description": null,
  "order_id": "clabc...",
  "customer_email": "buyer@example.com",
  "success_url": "https://example.com/thanks",
  "cancel_url": null,
  "metadata": { "internal_ref": "12345" },
  "created": 1780000000,
  "expires_at": 1780086400
}

• url — the hosted checkout page (a signed link, valid until the session expires).
• client_secret — returned only here. Store it server-side; pass it to your frontend only for embedded checkout. Treat it like a password for this one payment.

Same shape as create, with client_secret: null and url: null once the session is no longer open (paid or expired). Fulfill the order when status is "complete" and payment_status is "paid". If you created the session in amount mode, also check that amount_total equals the total you expect before fulfilling.

curl https://saleonix.com/api/v1/checkout/sessions/cs_test_aBcD... \
  -H "Authorization: Bearer sk_test_xxx"

Use the hosted checkout flow instead, for both TEST and LIVE: redirect the customer to the session's urlfrom create. The card is entered on Saleonix's hosted page, which simulates the outcome in TEST (via the documented test cards below) and runs a real 3DS authentication against the gateway in LIVE. Then verify with GET /checkout/sessions/{id} before fulfilling, same as any hosted-checkout flow.

Test cards (entered on the hosted page in TEST mode — not sent to this endpoint)

All errors share one envelope:

{ "error": { "type": "card_error", "code": "card_declined", "message": "..." } }

• No browser-facing request ever carries an amount: price mode derives amounts from the catalog; amount mode accepts them only on the secret-key endpoint. The confirm endpoint ignores injected amount fields.
• Currency is never client-settable — EUR is pinned server-side.
• Keys are verified by SHA-256 hash; raw keys are never stored or logged.
• client_secret is hashed at rest and returned exactly once.
• Concurrent confirms cannot double-charge: the order is claimed atomically before the gateway is called.
• Card data is forwarded to the payment gateway only — never persisted or logged.
• TEST and LIVE are fully isolated: keys, sessions, and money never cross.
• Per-IP, per-key and per-session rate limits; all auth failures are audited.