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 allowlist the exact origin that will mount the component. The amount and methods come from your trusted order calculation.

{
  "mode": "embedded",
  "amountMinor": 4990,
  "currency": "EUR",
  "paymentMethodTypes": ["card", "bank"],
  "allowedOrigins": ["https://store.example"],
  "metadata": { "orderId": "order_1001" }
}

Browser step

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

const checkout = new ZahloCheckout({
  apiUrl: "https://merchant.zahlo.eu",
  sessionId,
  clientToken,
  locale: "en",
  appearance: { theme: "auto", spacing: "comfortable" },
  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.

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.