LuniPay Docs

API Reference

Checkout Sessions

A checkout session is a single payment in progress. Your backend creates one, your customer pays at the returned url, and LuniPay emits a webhook when the session completes.

Checkout sessions are the highest-level primitive in the LuniPay API. If you just need to collect a one-time payment, this is the only resource you need — no customer object, no invoice, no payment intent. LuniPay hosts the payment page, handles 3DS and receipts, fires webhooks, and the session transitions from OPEN to COMPLETE or EXPIRED.

The checkout_session object

idstring

Unique identifier, prefixed with `cs_`.

objectstring

Always `"checkout_session"`. Use this to type-discriminate when deserializing webhook payloads.

livemodeboolean

True if the session was created with a live-mode secret key. Test and live sessions share the same schema but never mix in queries.

statusstring

Lifecycle state. `OPEN` is the default after creation; `COMPLETE` after a successful payment; `EXPIRED` after the expires_at timestamp or an explicit expire call.

Values: OPEN COMPLETE EXPIRED

payment_statusstring

Payment state, independent of the session status. An OPEN session may already have `payment_status=paid` briefly before the status transitions to COMPLETE.

Values: unpaid paid no_payment_required

amount_centsinteger

Total amount the customer will be charged, in the smallest currency unit.

currencystring

Lowercase 3-letter ISO 4217 currency code.

success_urlstring

URL the customer is redirected to after a successful payment. Supports `{CHECKOUT_SESSION_ID}` as a template variable — LuniPay replaces it with the session id before redirecting.

cancel_urlstringnullable

URL the customer is redirected to if they abandon the session. If omitted, the cancel button is hidden.

customer_idstringnullable

Id of the customer attached to the session, if any.

customer_emailstringnullable

Email shown on the receipt when no customer object is attached.

line_itemsarraynullable

Optional itemized breakdown shown on the checkout page. Each item has `name`, `quantity`, and `amount_cents`.

payment_intent_idstringnullable

Stripe PaymentIntent id created for this session. Populated once the customer starts payment.

payment_idstringnullable

Id of the resulting LuniPay `payment` object, set when the session completes successfully.

metadataobjectnullable

Up to 20 arbitrary key/value pairs. Round-trips through webhook payloads for reconciliation.

expires_atinteger

Unix timestamp after which the session can no longer be paid. Defaults to 24 hours from creation.

completed_atintegernullable

Unix timestamp when the session moved to COMPLETE. Null until the payment succeeds.

urlstring

The hosted checkout URL. Redirect your customer here to complete payment.

createdinteger

Creation timestamp (unix).

updatedinteger

Last-updated timestamp (unix).

{
  "id": "cs_01JRZK8WV3FYMPEQRXJ9HA5NTB",
  "object": "checkout_session",
  "livemode": false,
  "status": "OPEN",
  "payment_status": "unpaid",
  "amount_cents": 5000,
  "currency": "usd",
  "success_url": "https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://example.com/cart",
  "customer_id": null,
  "customer_email": null,
  "line_items": null,
  "payment_intent_id": null,
  "payment_id": null,
  "metadata": {
    "order_id": "ORD-9821"
  },
  "expires_at": 1713187200,
  "completed_at": null,
  "url": "https://lunipay.io/checkout/cs_01JRZK8WV3FYMPEQRXJ9HA5NTB",
  "created": 1713100800,
  "updated": 1713100800
}

Endpoints