Checkout Sessions API

Two integration styles

A session charges in exactly one of two modes:

• Price mode — pass price_id (+ optional quantity); the amount is read from your catalog on the server.
• Amount mode — pass amount (+ required description); your server states the total directly. Built for carts, shipping, fees and discounts.

Passing both (or neither) of price_id / amount is rejected. In bothmodes the customer's browser never carries an amount — only your server decides what is charged.

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" }
  }'

Amount mode

# 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"

Call this from the customer's browser. Both credentials are required: the publishable key identifies your store; the client_secret proves this specific session was created by your server.

// Runs in the customer's browser with your PUBLISHABLE key.
// clientSecret was injected by your server after creating the session.
const res = await fetch(
  `https://saleonix.com/api/v1/checkout/sessions/${sessionId}/confirm`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer pk_test_xxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_secret: clientSecret,
      card: {
        number: "4242424242424242",
        exp_month: 12,
        exp_year: 2030,
        cvc: "123",
      },
      customer_email: "buyer@example.com",
    }),
  }
);

const data = await res.json();
if (res.ok) {
  window.location.href = data.redirect_url;
} else {
  showError(data.error.message);
}

Success 200

{
  "id": "cs_test_aBcD...",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  "order_id": "clabc...",
  "redirect_url": "https://example.com/thanks?session_id=cs_test_aBcD..."
}

Test cards (test mode only)

Any other number returns 400 unsupported_test_card. The session stays payable, but the attempt still counts toward the per-session limit.

Failure semantics

• Invalid card input (invalid_card_number, invalid_expiry, expired_card, invalid_cvc) returns HTTP 402 with type: "card_error" and is rejected before any charge attempt — the session stays payable.
• A gateway decline (card_declined, also HTTP 402) is terminal for the session: create a new session to retry. This is deliberate anti-card-testing behavior.
• Each confirm call counts toward a per-session attempt budget (default 5), including validation failures and wrong client_secret; beyond that it returns 429 too_many_attempts.
• Rare gateway or settlement failures may return HTTP 500 with payment_outcome_unknown or settlement_failed — do not retry the payment; contact support.

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.