Choose an integration

Choose the smallest integration surface that gives your business the control it needs. Start with Checkout Sessions for a complete payment page, then use Payment Intents when your application owns confirmation or capture state.

Compare integration modes

Use case	Start with	Your server owns	Zahlo owns
Standard online order	Hosted Checkout Session	Cart, order, webhook fulfillment	Payment UI and method flows
Branded checkout page	In-page Checkout Session	Cart, shell, callbacks, origin policy	Secure fields and method flows
Email or invoice collection	Payment link or hosted session	Link creation and reconciliation	Hosted payment page
Explicit confirmation or manual capture	Payment Intent	Payment state, confirmation, capture	Secure payment details
Save a method without charging	Setup Intent	Consent and customer ownership	Secure setup flow
Recurring access	Subscription and Checkout Session	Customer, price, entitlement	Billing collection and payment method flow

Use Accept a payment for the standard one-time flow. Use Payment intents when you need to separate authorization, confirmation, and capture.

Shared server-to-browser sequence

Every browser integration follows the same boundary:

Resolve the customer, cart, amount, currency, and order on your server
Create one resource with an idempotency key
Return only the resource ID and short-lived client token to browser code
Let the secure component collect payment details and handle customer action
Keep the order pending until a verified event or authoritative retrieval confirms it
Fulfill once, then reconcile refunds, disputes, and delayed events by resource ID

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,
      orderId: order.id,
      successUrl: "https://store.example/checkout/success",
      cancelUrl: "https://store.example/checkout/cancelled",
    }),
  },
);
const { checkoutUrl } = await response.json();

The server owns the API key and authoritative amount. The browser receives only the result needed to render checkout. See Authentication and Fulfill orders safely before connecting production orders.

Choose by control requirement

Hosted checkout reduces UI work and isolates sensitive fields. In-page checkout gives you control over the surrounding layout without moving sensitive data into your application. Payment Intents give you the most lifecycle control, but require explicit handling for action, processing, capture, cancellation, and recovery states. Do not select a lower-level flow only to recreate a higher-level checkout page. Keep method discovery dynamic, register webhooks for every payment flow, and use the flow’s documented test cases before launch.

Start here

Core concepts

Accept payments

Sell online

Subscriptions

Integrations

Operations

Compare integration modes

Shared server-to-browser sequence

Choose by control requirement

​Compare integration modes

​Shared server-to-browser sequence

​Choose by control requirement

Compare integration modes

Shared server-to-browser sequence

Choose by control requirement