API reference

Checkout Sessions

A checkout session is one payment for one order on the hosted payment page. Create one when the buyer is ready to pay, redirect them to its url, and retrieve it to confirm payment.

The session object

Fields

idstring: Unique id, cs_live_… or cs_test_….
objectstring: Always checkout.session.
statusenum: open, complete, expired or cancelled.
payment_statusenum: unpaid, partially_paid or paid, from amount_received.
amountstring: The amount to collect, as a decimal string.
currencyenum: USDC or EURC.
amount_receivedstring: Everything verified on chain so far, including any excess.
overpaymentstring: Received above amount. Refund it to the buyer.
amount_refundedstring: Refunded so far. Always "0" until refunds ship.
urlstring: The hosted payment page. Redirect the buyer here.
success_urlstring: Where the buyer goes after paying, as you sent it.
cancel_urlstring | null: Where “Cancel and return” goes, or null.
client_reference_idstring | null: Your order id, or null. Never shown to the buyer.
customer_emailstring | null: The buyer's email, or null. Never shown on the page.
descriptionstring | null: What the buyer sees, or null.
line_itemsarray: Display lines: { name, quantity, unit_amount }.
metadataobject: Your key–value strings. Never shown to the buyer.
paymentsarray: Each verified transfer: tx_hash, amount, method (wallet, saphraone, card_or_bank, cross_chain or manual), paid_at, explorer_url.
refundsarray: Refund objects. Empty until refunds ship.
livemodeboolean: true in live, false in the sandbox.
created_attimestamp: When the session was created.
expires_attimestamp: When it stops accepting payments (unless a slow payment is on its way).
completed_attimestamp | null: When the full amount arrived, or null.

{
  "amount": "25",
  "amount_received": "25",
  "amount_refunded": "0",
  "cancel_url": "https://shop.example/cart",
  "client_reference_id": "1042",
  "completed_at": "2026-10-17T09:34:12+00:00",
  "created_at": "2026-10-17T09:30:00+00:00",
  "currency": "USDC",
  "customer_email": "ada@example.com",
  "description": "Order #1042",
  "expires_at": "2026-10-17T10:30:00+00:00",
  "id": "cs_live_4f9k2m7q1x8v4b6n0c5d2h7j",
  "line_items": [
    {
      "name": "Linen shirt",
      "quantity": 1,
      "unit_amount": "18.00"
    },
    {
      "name": "Delivery",
      "quantity": 1,
      "unit_amount": "7.00"
    }
  ],
  "livemode": true,
  "metadata": {
    "cart_id": "c_8812"
  },
  "object": "checkout.session",
  "overpayment": "0",
  "payment_status": "paid",
  "payments": [
    {
      "amount": "25",
      "explorer_url": "https://explorer.arc.io/tx/0x7c1e…",
      "method": "wallet",
      "paid_at": "2026-10-17T09:34:12+00:00",
      "tx_hash": "0x7c1e…"
    }
  ],
  "refunds": [],
  "status": "complete",
  "success_url": "https://shop.example/thanks?session_id={CHECKOUT_SESSION_ID}",
  "url": "https://app.saphra.one/checkout/cs_live_4f9k2m7q1x8v4b6n0c5d2h7j"
}

Create a session

POST/v1/checkout/sessions

Creates a session and returns it with status 201. Send an Idempotency-Key header so retries are safe.

Body parameters

amountstringrequired: Amount to collect as a decimal string, 0.50 to 10,000, up to 6 decimals. Example "25.00".
success_urlstringrequired: https URL for after payment. {CHECKOUT_SESSION_ID} is replaced with the id. http is allowed for localhost with test keys.
currencystring: USDC (default) or EURC. Card and cross-chain payment need USDC.
cancel_urlstring: https URL for “Cancel and return”.
descriptionstring: Shown to the buyer. Up to 140 characters.
line_itemsarray: Up to 20 { name, quantity, unit_amount }. quantity defaults to 1. They must add up to amount exactly.
client_reference_idstring: Your order id, up to 200 characters.
customer_emailstring: The buyer's email, kept for your records.
metadataobject: Up to 20 keys (40 chars) with string values (500 chars). Numbers and booleans are stored as strings.
expires_in_minutesinteger: How long the session can be paid: 30 to 1,440. Default 60.

curl https://api.saphra.one/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": "25.00",
    "currency": "USDC",
    "description": "Order #1042",
    "client_reference_id": "1042",
    "success_url": "https://shop.example/thanks?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://shop.example/cart"
  }'

{
  "amount": "25",
  "amount_received": "0",
  "amount_refunded": "0",
  "cancel_url": "https://shop.example/cart",
  "client_reference_id": "1042",
  "completed_at": null,
  "created_at": "2026-10-17T09:30:00+00:00",
  "currency": "USDC",
  "customer_email": "ada@example.com",
  "description": "Order #1042",
  "expires_at": "2026-10-17T10:30:00+00:00",
  "id": "cs_live_4f9k2m7q1x8v4b6n0c5d2h7j",
  "line_items": [
    {
      "name": "Linen shirt",
      "quantity": 1,
      "unit_amount": "18.00"
    },
    {
      "name": "Delivery",
      "quantity": 1,
      "unit_amount": "7.00"
    }
  ],
  "livemode": true,
  "metadata": {
    "cart_id": "c_8812"
  },
  "object": "checkout.session",
  "overpayment": "0",
  "payment_status": "unpaid",
  "payments": [],
  "refunds": [],
  "status": "open",
  "success_url": "https://shop.example/thanks?session_id={CHECKOUT_SESSION_ID}",
  "url": "https://app.saphra.one/checkout/cs_live_4f9k2m7q1x8v4b6n0c5d2h7j"
}

Retrieve a session

GET/v1/checkout/sessions/{id}

Returns the session as it stands. This is how you confirm payment. Retrieving also prompts SaphraONE to check for card and cross-chain payments in progress, so polling keeps them moving. Another business’s id returns 404.

curl https://api.saphra.one/v1/checkout/sessions/cs_live_4f9k2m7q1x8v4b6n0c5d2h7j \
  -H "Authorization: Bearer sk_live_…"

List sessions

GET/v1/checkout/sessions

Returns your sessions, newest first. See Pagination.

Query parameters

limitinteger: 1 to 100. Default 10.
starting_afterstring: Return sessions after this session id.
statusenum: Only sessions with this status: open, complete, expired or cancelled.

curl "https://api.saphra.one/v1/checkout/sessions?status=open&limit=20" \
  -H "Authorization: Bearer sk_live_…"

Expire a session

POST/v1/checkout/sessions/{id}/expire

Ends an unpaid session so its link can’t be paid, for example when the cart changed. Returns the session. Expiring an already expired or cancelled session returns it unchanged.

When	Result
`open`, nothing received	`200`, now `expired`
`open`, a payment arrived	`409` `session_state_invalid`
`complete`	`409` `session_state_invalid`

curl -X POST https://api.saphra.one/v1/checkout/sessions/cs_live_4f9k2m7q1x8v4b6n0c5d2h7j/expire \
  -H "Authorization: Bearer sk_live_…"