In-page checkout - Zahlo Merchant Developer Docs

In-page checkout keeps your page layout and navigation while Zahlo owns sensitive payment fields and method-specific interaction. Create the session on your server, then pass the session ID and short-lived client token to the browser.

Server step

Set mode: "embedded" and register the exact origin that will mount the component in merchant settings. The amount and method come from your trusted order calculation.

{
  "mode": "embedded",
  "amountMinor": 4990,
  "currency": "EUR",
  "method": "card",
  "metadata": { "orderId": "order_1001" }
}

Browser step

import { ZahloCheckout } from "@zahlo/sdk";

const checkout = new ZahloCheckout({
  apiUrl: "https://merchant-demo.zahlo.eu",
  sessionId,
  clientToken,
  appearance: {
    theme: "auto",
    locale: "en",
    merchantName: "Example Store",
    logoUrl: "https://store.example/assets/logo.svg",
    colors: {
      primary: "#087A60",
      background: "#FFFFFF",
      text: "#17211D",
      muted: "#5A625D",
    },
    fontFamily: "Inter, system-ui, sans-serif",
    spacing: "comfortable",
    customCss: ".zahlo-checkout-card { border-radius: 12px; }",
  },
  onStatusChange: (status) => renderCheckoutStatus(status),
  onSuccess: () => showPendingConfirmation(),
  onError: (error) => showRetry(error),
});
await checkout.mount("#zahlo-checkout");

Call destroy() when the page unmounts. Mount one instance per container, keep the container accessible, and do not copy sensitive field values into your DOM, state, analytics, or logs. Appearance values style the checkout shell; secure payment fields remain isolated and are styled only through the supported appearance options.

Origin and event rules

The browser may read only its session through the bearer client token. Verify the exact origin before mounting. A callback means the component observed a state change; a signed server event is the fulfillment authority. For asynchronous methods, leave the order pending until confirmation.