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 checkout presentation. It cannot read payment values, change the amount, or disable validation.

Choose a mode

Mode	How the customer enters checkout	Best for
Hosted	Redirect to the session `checkoutUrl`	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,
    paymentMethodTypes: ["card", "bank", "apple_pay", "google_pay"],
    allowedOrigins: ["https://store.example"],
    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

Redirect from a server response or a user action using the returned checkoutUrl. 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",
    },
  });

  checkout.on("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

Choose a mode

Server configuration

Hosted checkout

In-page checkout

Allowed origins and return URLs

Locale and accessibility

Updating a session

​Choose a mode

​Server configuration

​Hosted checkout

​In-page checkout

​Allowed origins and return URLs

​Locale and accessibility

​Updating a session

Choose a mode

Server configuration

Hosted checkout

In-page checkout

Allowed origins and return URLs

Locale and accessibility

Updating a session