Build checkout

Zahlo checkout supports hosted redirects and in-page experiences. Both use the same server-created session, dynamic payment methods, short-lived client token, return URLs, webhook events, and secure payment-field boundary.

Before you start

Choose Demo or production in Environments.
Store the merchant API key and webhook secret in your server secret manager.
Register the exact in-page origins in merchant settings and use registered return URLs.
Create or resolve the order on the server and calculate its amount in minor units.

The minimal lifecycle is: create an order → create one session with an idempotency key → render hosted or in-page checkout → keep the order pending → verify the payment event → fulfill once.

Hosted checkout

Create a checkout session from your server, then submit its client token to the hosted redirect endpoint. Hosted checkout is the fastest path and works well for email, invoices, and payment links.

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: "hosted",
    amountMinor: order.totalMinor,
    currency: order.currency,
    method: "card",
    orderId: order.id,
    successUrl: "https://store.example/checkout/success",
    cancelUrl: "https://store.example/checkout/cancelled",
    metadata: { orderId: order.id },
  }),
});
const session = await response.json();
// Return session.id and session.clientToken to the browser handoff.

Embedded checkout

Create a session with mode: "embedded", load the Zahlo SDK from your website, and mount the session in a customer-owned container. Register the exact website origin before rendering it. See Customize checkout for the full appearance contract.

const checkout = new ZahloCheckout({
  apiUrl: "https://merchant-demo.zahlo.eu",
  sessionId,
  clientToken,
  locale: "en",
  onStatusChange: (status) => console.log(status),
});
await checkout.mount("#zahlo-checkout");

Request fields

Use amountMinor, currency, mode, one canonical method, order metadata, registered return URLs, and appearance. Validate all values on the server. Do not send raw card number, security code, or expiry fields to your server.

Completion

Treat the checkout UI and browser callbacks as presentation signals. Your server should fulfill only after a verified payment.confirmed or equivalent terminal event. For a pending or asynchronous method, show a pending state and reconcile by session or payment ID rather than creating a replacement session.

Start here

Core concepts

Accept payments

Sell online

Subscriptions

Integrations

Operations

Before you start

Hosted checkout

Embedded checkout

Request fields

Completion

​Before you start

​Hosted checkout

​Embedded checkout

​Request fields

​Completion

Before you start

Hosted checkout

Embedded checkout

Request fields

Completion