Customize checkout

Checkout customization has two layers: merchant-owned page layout and a secure Zahlo checkout component. Configure the first with your site CSS and the second with the session appearance options. Sensitive payment fields remain inside the secure component in both hosted and in-page modes. The custom CSS option is scoped to the Zahlo-owned shell. It cannot read payment values, change the amount, disable validation, or style provider-owned sensitive iframe fields. It is capped at 4,000 characters and wrapped in @scope (.zahlo-checkout-root).

Supported appearance contract

The SDK accepts the same neutral appearance object for hosted and in-page checkout:

Field	Supported values	Owned by
`theme`	`light`, `dark`, `auto`	Zahlo shell
`locale`	`en`, `de`	Zahlo labels and status
`merchantName`	Up to 80 characters	Zahlo shell text
`logoUrl`, `iconUrl`	Same-origin relative path or HTTPS asset URL	Zahlo shell asset
`colors`	Hex `primary`, `background`, `text`, `muted` values	Zahlo shell
`fontFamily`	Safe font-family text, up to 160 characters	Zahlo shell
`spacing`	`compact`, `normal`, `comfortable`	Zahlo shell
`customCss`	Shell-scoped CSS, up to 4,000 characters	Zahlo shell only

The server must validate these values before storing or sending them to the browser. The SDK keeps the existing top-level theme and locale fields as compatibility aliases; appearance is canonical. Secure payment fields can only be styled through the supported appearance options.

Choose a mode

Mode	How the customer enters checkout	Best for
Hosted	Submit the session client token to the redirect endpoint	Fast launch, email, invoices, and payment links
In-page	Mount the session into your container	A checkout that stays inside your site

Create the session on your server. The server validates the cart, selects the allowed methods, supplies the appearance, and returns only the session ID and short-lived client token to browser code.

Server configuration

const response = await fetch("https://merchant-demo.zahlo.eu/api/v1/checkout-sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.ZAHLO_API_KEY,
    "Idempotency-Key": `checkout-${order.id}`,
  },
  body: JSON.stringify({
    mode: "embedded",
    amountMinor: order.totalMinor,
    currency: order.currency,
    method: "card",
    successUrl: "https://store.example/checkout/success",
    failureUrl: "https://store.example/checkout/failed",
    cancelUrl: "https://store.example/checkout/cancelled",
    appearance: {
      theme: "light",
      logoUrl: "https://store.example/assets/logo.svg",
      iconUrl: "https://store.example/assets/icon.svg",
      fontFamily: "Inter, system-ui, sans-serif",
      colors: { primary: "#087A60", background: "#FFFFFF", text: "#17211D" },
      spacing: "comfortable",
      customCss: ".zahlo-checkout { border-radius: 12px; }",
    },
    metadata: { orderId: order.id },
  }),
});
if (!response.ok)
  throw new Error(`checkout creation failed: ${response.status}`);
const session = await response.json();

Use HTTPS assets hosted on a controlled origin. Validate the URLs and appearance values on the server; never let arbitrary customer input become CSS or an asset URL.

Hosted checkout

Submit the client token to the session redirect endpoint from a server response or browser handoff. Keep the order pending at this point. The success, failure, or cancellation page should display the session result but must not fulfill the order. Fulfill only after a verified payment event.

In-page checkout

<div id="zahlo-checkout" aria-live="polite"></div>
<script type="module">
  import { ZahloCheckout } from "@zahlo/sdk";

  const checkout = new ZahloCheckout({
    apiUrl: "https://merchant-demo.zahlo.eu",
    sessionId: "cs_demo_1001",
    clientToken: "client_token_from_your_server",
    locale: "en",
    appearance: {
      theme: "light",
      colors: { primary: "#087A60" },
      spacing: "comfortable",
    },
    onStatusChange: (status) => {
    document.querySelector("#zahlo-checkout").dataset.status = status;
    },
  });
  await checkout.mount("#zahlo-checkout");
</script>

The SDK owns payment-field collection and method-specific interaction. Your callbacks update presentation only. Do not read, log, persist, or proxy payment field values.

Allowed origins and return URLs

Register each exact HTTPS origin that can mount in-page checkout. An origin is a scheme, host, and optional port; a path is not an origin. Keep return URLs on an allowlist and include only your own order reference. Never put an API key, webhook secret, or client token in a query string.

Locale and accessibility

Set locale explicitly for a multilingual storefront. Keep the checkout container visible, keyboard reachable, and announced with an aria-live status region. Test narrow screens, zoom, focus order, validation text, contrast, and reduced motion. Format money using the returned currency and minor-unit amount; do not derive totals from localized labels.

Updating a session

If the cart, customer, address, tax, shipping, or selected method changes, recalculate on the server and use the documented update path for the session. If the session can no longer represent the order, expire it and create one new session with a new idempotency key only after reconciling the original.

Start here

Core concepts

Accept payments

Sell online

Subscriptions

Integrations

Operations

Supported appearance contract

Choose a mode

Server configuration

Hosted checkout

In-page checkout

Allowed origins and return URLs

Locale and accessibility

Updating a session

​Supported appearance contract

​Choose a mode

​Server configuration

​Hosted checkout

​In-page checkout

​Allowed origins and return URLs

​Locale and accessibility

​Updating a session

Supported appearance contract

Choose a mode

Server configuration

Hosted checkout

In-page checkout

Allowed origins and return URLs

Locale and accessibility

Updating a session