Hosted checkout - Zahlo Merchant Developer Docs

Hosted checkout is the fastest integration. Your server creates a session and your site redirects to its checkoutUrl. Zahlo owns payment-method interaction, sensitive fields, redirect flows, and responsive payment UI.

Server endpoint

export async function createCheckout(order) {
  const response = await fetch("https://merchant.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,
      paymentMethodTypes: ["card", "bank", "apple_pay", "google_pay"],
      orderId: order.id,
      successUrl: "https://store.example/checkout/success",
      failureUrl: "https://store.example/checkout/failed",
      cancelUrl: "https://store.example/checkout/cancelled",
      metadata: { orderId: order.id },
    }),
  });
  if (!response.ok) throw new Error(`checkout failed: ${response.status}`);
  return response.json();
}

Redirect only to the URL returned by your server. Do not construct a hosted URL from an ID, put a client token in a query string, or reuse an expired session.

Return and confirmation

Your success, failure, and cancellation pages are presentation endpoints. Read the session ID from your own state, retrieve authoritative status on the server, and show a pending result when confirmation has not arrived. Fulfill from a verified event, not from the return URL.

Customize the page

Use session appearance, locale, method configuration, return URLs, and merchant checkout settings. Hosted checkout can use the same branding contract as in-page checkout; see Customize checkout. Register a signed webhook endpoint before going live so delayed or asynchronous payment confirmation reaches your server.