LuniPay Docs

API Reference · Checkout Sessions

Create a checkout session

Creates a new checkout session and returns a hosted payment URL.

POST/v1/checkout/sessions

A checkout session is the handoff between your backend and the LuniPay-hosted payment page. Call this endpoint with an amount and a success_url, redirect the customer to the returned url, and LuniPay takes it from there.

Sessions expire after 24 hours by default. Retries with the same `Idempotency-Key` header return the original session instead of creating a duplicate.

Returnscheckout_session object

Body parameters

amountintegerRequired

Amount to charge, in the smallest currency unit (cents for USD).

Constraints: At least 50 for USD. Max 99999999.

currencystringRequired

Lowercase 3-letter ISO 4217 currency code.

success_urlstringRequired

URL to redirect after a successful payment. Supports `{CHECKOUT_SESSION_ID}` as a template variable.

cancel_urlstring

URL the customer is redirected to if they abandon the session.

customerstring

Id of an existing customer to attach. Populates the receipt email and links the resulting payment to that customer.

customer_emailstring

Receipt email when no customer object is attached.

line_itemsarray

Optional itemized breakdown. Each item has `name`, `quantity`, `amount_cents`.

metadataobject

Up to 20 key/value pairs for your own bookkeeping.

Constraints: Max 20 keys. Values are strings, max 500 characters each.

expires_atintegerdefault: +24h

Unix timestamp when the session expires. Must be at least 30 minutes in the future.

Errors

400
parameter_missing

A required parameter was not supplied.

401
invalid_api_key

Missing or malformed Authorization header.

422
amount_too_small

The amount is below the minimum chargeable for the currency.

429
rate_limited

Too many requests. Back off exponentially.