Checkout

Create a hosted or embedded checkout session

Create a hosted or embedded checkout session. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

post/api/v1/checkout-sessions

Request

Base URL
https://merchant.zahlo.eu
Auth
API key in header x-api-key

Headers

Idempotency-Keystring

Retry-safe key for create operations.

Request body

mode'hosted' | 'embedded'

amountMinorinteger

Simple mode: one total, no line items.

currencystring

Required with amountMinor or ad-hoc line items; defaults to the prices' currency.

descriptionstring

referencestring

customerEmailstring email

customerIdstring

An existing customer. Required with setupFutureUsage and type setup.

setupFutureUsage'off_session'

Save the card to customerId for later off-session charges (type payment, card only). You must have shown the customer your terms for later charges.

paymentMethodTypesstring[]

Default: the merchant's default methods, else everything enabled for the currency.

Deprecated single-method form of paymentMethodTypes.

locale'auto' | 'cz' | 'de' | 'en' | 'es' | 'fr' | 'hr' | 'hu' | 'il' | 'it' | 'kr' | 'lt' | 'pl' | 'ro' | 'ru' | 'tr'

expiresInSecondsinteger

successUrlstring uri

May contain {CHECKOUT_SESSION_ID}; must be on a registered checkout domain.

failureUrlstring uri

cancelUrlstring uri

type'payment' | 'setup' | 'subscription'

subscription: a recurring price (the first one), further recurring prices as add-ons billed with it every period, and optional one-time prices charged once with the first period (setup fees, never discounted), paymentMethodTypes ["card"] and customerEmail. A price with a trial charges nothing now (paymentStatus no_payment_required). setup: saves a card to customerId without charging it; no lineItems or amountMinor.

couponIdstring

Applies to lineItems; on a subscription it discounts the periods its duration covers.

promotionCodestring

A coupon's code as the customer typed it (case-insensitive), instead of couponId. Applies to lineItems; an unknown code is 404 resource_missing.

allowPromotionCodesboolean

One-time sessions with lineItems, hosted or embedded: the details page shows a promotion code field with an Apply button and a live total; the total and the payment link are re-made. Not with promotionCode or couponId.

submitType'auto' | 'pay' | 'book' | 'donate'

The details page's button label: auto Continue to payment, pay, book or donate.

metadataobject

Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

Example request

{
  "currency": "EUR"
}

Response

Checkout session created

idstring required

object'checkout_session' required

livemodeboolean

createdAtstring date-time

type'payment' | 'setup' | 'subscription' required

mode'hosted' | 'embedded' required

status'open' | 'complete' | 'expired' | 'failed' required

paymentStatus'unpaid' | 'paid' | 'no_payment_required' required

urlstring uri nullable

Hosted only, while open: redirect the customer here.

clientTokenstring nullable

Embedded only, while open: pass it to the browser SDK.

detailsRequiredboolean

Embedded only: true until the payer completed Zahlo's details step (the browser SDK mounts it first); embedUrl is null meanwhile.

embedUrlstring uri nullable

expiresAtstring date-time required

currencystring required

amountSubtotalinteger

amountDiscountinteger

amountShippinginteger

The chosen shipping option, inside amountTotal; 0 without one.

amountTotalinteger required

customerIdstring nullable

setupFutureUsage'off_session' nullable

Set when the session saves the card for off-session charges.

customerEmailstring nullable

couponIdstring nullable

paymentIdstring nullable

subscriptionIdstring nullable

referencestring nullable

allowPromotionCodesboolean

submitType'auto' | 'pay' | 'book' | 'donate'

successUrlstring

cancelUrlstring

localestring