Create a checkout session

POST /v1/checkout-sessions — requires checkout_sessions:write and an Idempotency-Key header.

Amounts are integers in minor units (cents). The server recomputes the total from items, shipping_amount and tax_amount and rejects any mismatch.

curl -X POST https://<your-orion-host>/v1/checkout-sessions \
  -H "Authorization: Bearer $ORION_KEY" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "order_reference": "NW-1042",
    "currency": "CAD",
    "items": [{ "name": "Trail Pack", "quantity": 2, "unit_amount": 5000 }],
    "shipping_amount": 1000,
    "tax_amount": 1430,
    "amount": 12430,
    "return_url": "https://northwind-outfitters.test/thanks",
    "payment_methods": ["card", "usdc"]
  }'

Field	Type	Notes
order_reference	string	Your order ID. Letters, digits, . _ : -, max 64. One paid order cannot be paid again.
currency	string	CAD or USD
items	array	name, quantity, unit_amount (minor units)
shipping_amount, tax_amount	integer	Minor units, default 0
amount	integer	Must equal the computed total
return_url	URL	Must be on an approved website (exact host match)
cancel_url	URL	Optional; same rule
payment_methods	array	Optional subset of card, usdc, interac approved for your connection

Response — 201

{
  "id": "cs_8k2m4n6p8q0r2s4t6v8w",
  "object": "checkout_session",
  "status": "open",
  "environment": "sandbox",
  "url": "https://<your-orion-host>/checkout/cs_8k2m4n6p8q0r2s4t6v8w",
  "order_id": "cmabc123…",
  "payment_methods": ["card", "usdc"],
  "expires_at": "2026-10-19T23:30:00.000Z"
}

Redirect the customer to url. Sessions expire after 30 minutes.

GET /v1/checkout-sessions/{id} returns the same object (requires payments:read).

The customer's return to return_url is not proof of payment. Confirm with GET /v1/payments/{id} or a verified webhook.