Checkout Sessions

Create hosted and embedded checkout sessions.

Hosted mode returns a URL to redirect to. Embedded mode returns a client secret for paysio.mountCheckout().

Embedded Checkout includes email, phone, Quick Checkout, cards, bank accounts, addresses, eligible Apple Pay and Google Pay buttons, and 3D Secure. Wallet availability follows Settings > Checkout automatically, so Embedded Checkout does not need a wallet argument.

Create Checkout Session

Create a hosted or embedded checkout session.

POSThttps://paysio.com/api/v1/checkout-sessions

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

line_itemsarrayrequired

Array of line items. Each item can be { product_id, quantity?, unit_price? } to reference an existing product, or { name, amount, currency?, quantity? } to create an ad-hoc product inline. unit_price (cents) pins the line to that rate: required for open_ended products, optional for one_time ones, not allowed on recurring ones.

success_urlstring

URL to redirect to after successful payment

ui_modestring

hosted (default) or embedded

show_order_summaryboolean

Embedded mode only. Defaults to false. Show Paysio line items, totals, tax, shipping, recurring charges, and promo-code controls.

email_field_modestring

Embedded mode only: editable (default), read_only, or hidden. read_only and hidden require customer_email.

phone_field_modestring

Embedded mode only: editable (default), read_only, or hidden. read_only requires customer_phone; hidden also requires it when phone collection is mandatory.

quick_checkout_behaviorstring

Embedded mode only: on_input (default), on_load, or disabled. on_load immediately checks customer_email. Remembered sessions resume only for the same email.

allowed_parent_originsstring[]

Required for embedded mode. Exact HTTPS origins allowed to frame checkout; HTTP localhost is accepted for development.

customer_emailstring

Optional authoritative email prefill. A remembered Quick Checkout session cannot replace it and resumes only when the emails match.

customer_phonestring

Optional phone prefill. Quick Checkout SMS uses only a phone already verified on the customer record.

expires_atstring

Future ISO timestamp. Embedded defaults to 24 hours, maximum 7 days.

appearanceobject

Theme defaults: colors, radii, font family/size, and HTTPS font stylesheets.

metadataobject

Arbitrary key-value metadata

discount_codestring

Discount code to auto-apply on the checkout page. The code is validated at session creation and automatically applied when the customer opens the checkout.

payment_methodsstring[]

Restrict which payment methods this checkout offers: any of card, bank, apple_pay, google_pay. Must include at least card or bank. Omitted = the workspace's configured methods. Always intersected with what the workspace actually supports — this narrows the offered methods, never adds new ones.

Example request — cURL

curl -X POST https://paysio.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": []
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/checkout-sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "line_items": []
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "slug": "api-a1b2c3d4e5f6...",
    "url": "https://paysio.com/pay/api-a1b2c3d4e5f6...",
    "success_url": "https://yoursite.com/success",
    "metadata": { "order_ref": "12345" },
    "sandbox": true,
    "status": "open",
    "ui_mode": "embedded",
    "payment_methods": null,
    "show_order_summary": true,
    "email_field_mode": "read_only",
    "phone_field_mode": "hidden",
    "quick_checkout_behavior": "on_load",
    "client_secret": "ecs_...",
    "embed_url": "https://paysio.com/embedded-checkout/ecs_...",
    "expires_at": "2026-01-16T10:30:00.000Z",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Get Checkout Session

Get authoritative session status. Fulfill from this response or payment.completed webhooks, not the browser completion event alone.

GEThttps://paysio.com/api/v1/checkout-sessions/:id