Hosted checkout with Next.js

ZAHLO_API_KEY=zk_test_your_sandbox_key
ZAHLO_WEBHOOK_SECRET=set_in_step_6
SITE_URL=http://localhost:3000

// Creates the store's products, prices and coupon once per environment (sandbox, then live).
// Run: node --env-file=.env.local scripts/setup-catalog.mjs
// Safe to run again: it finds existing prices by lookupKey and coupons by code, and creates nothing twice.
const apiKey = process.env.ZAHLO_API_KEY;
if (!apiKey) throw new Error("Set ZAHLO_API_KEY");
const apiBase =
  process.env.ZAHLO_API_BASE ??
  (apiKey.startsWith("zk_live_") ? "https://merchant.zahlo.eu" : "https://merchant-demo.zahlo.eu");

const PRODUCTS = [
  { lookupKey: "tshirt", name: "T-shirt", unitAmountMinor: 2500 },
  { lookupKey: "mug", name: "Mug", unitAmountMinor: 1200 },
];
const COUPONS = [{ code: "WELCOME15", name: "Welcome 15%", percentOff: 15, duration: "once" }];

async function call(method, path, body, idempotencyKey) {
  for (let attempt = 0; ; attempt += 1) {
    const response = await fetch(`${apiBase}/api/v1${path}`, {
      body: body === undefined ? undefined : JSON.stringify(body),
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
      },
      method,
    });
    if (response.ok) return response.json();
    const error = (await response.json().catch(() => ({}))).error ?? {};
    const retry = response.status === 429 || response.status >= 500 || error.code === "request_in_progress";
    if (retry && attempt < 2) {
      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
      continue;
    }
    throw new Error(`${method} ${path} -> ${response.status} ${error.code}: ${error.message}`);
  }
}

async function listAll(path) {
  const items = [];
  for (let after = ""; ; ) {
    const page = await call("GET", `${path}?limit=100${after ? `&startingAfter=${after}` : ""}`);
    items.push(...page.data);
    if (!page.hasMore || page.data.length === 0) return items;
    after = page.data.at(-1).id;
  }
}

const prices = await listAll("/prices");
for (const item of PRODUCTS) {
  if (prices.some((price) => price.active && price.lookupKey === item.lookupKey)) {
    console.log(`price ${item.lookupKey}: exists`);
    continue;
  }
  const product = await call("POST", "/products", { name: item.name }, `setup-product-${item.lookupKey}`);
  await call(
    "POST",
    "/prices",
    {
      currency: "EUR",
      lookupKey: item.lookupKey,
      productId: product.id,
      type: "one_time",
      unitAmountMinor: item.unitAmountMinor,
    },
    `setup-price-${item.lookupKey}`
  );
  console.log(`price ${item.lookupKey}: created`);
}

const coupons = await listAll("/coupons");
for (const coupon of COUPONS) {
  if (coupons.some((existing) => existing.code === coupon.code)) {
    console.log(`coupon ${coupon.code}: exists`);
    continue;
  }
  await call("POST", "/coupons", coupon, `setup-coupon-${coupon.code}`);
  console.log(`coupon ${coupon.code}: created`);
}

// Server-only Zahlo API client. Never import this file from a client component.
const apiKey = process.env.ZAHLO_API_KEY ?? "";

/** zk_test_ keys use the sandbox, zk_live_ keys use live. */
export const apiBase =
  process.env.ZAHLO_API_BASE ??
  (apiKey.startsWith("zk_live_")
    ? "https://merchant.zahlo.eu"
    : "https://merchant-demo.zahlo.eu");

export class ZahloError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,
    message: string,
    readonly requestId: string | null
  ) {
    super(message);
  }
}

const MAX_RETRIES = 2;
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
const backoff = (attempt: number, response?: Response) =>
  Number(response?.headers.get("retry-after") ?? 0) * 1000 ||
  500 * 2 ** attempt;

/** Retry only what can succeed on a second try: network errors, 409 request_in_progress, 429 and 5xx. */
const retryable = (status: number, code: string) =>
  status === 429 ||
  status >= 500 ||
  (status === 409 && code === "request_in_progress");

/**
 * Calls the Zahlo API. Every POST carries one Idempotency-Key, reused on each retry,
 * so a retried request can never create a second object.
 */
export async function zahlo<T>(
  method: "GET" | "POST" | "PATCH" | "DELETE",
  path: string,
  options: { body?: unknown; idempotencyKey?: string } = {}
): Promise<T> {
  const idempotencyKey =
    method === "POST"
      ? (options.idempotencyKey ?? crypto.randomUUID())
      : undefined;
  for (let attempt = 0; ; attempt += 1) {
    let response: Response;
    try {
      response = await fetch(`${apiBase}/api/v1${path}`, {
        body:
          options.body === undefined ? undefined : JSON.stringify(options.body),
        headers: {
          "content-type": "application/json",
          "x-api-key": apiKey,
          ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
        },
        method,
        signal: AbortSignal.timeout(15_000),
      });
    } catch (error) {
      if (attempt < MAX_RETRIES) {
        await sleep(backoff(attempt));
        continue;
      }
      throw error;
    }
    if (response.ok) {
      return (response.status === 204 ? undefined : await response.json()) as T;
    }
    const payload = await response.json().catch(() => ({}));
    const code: string = payload?.error?.code ?? "unknown";
    if (attempt < MAX_RETRIES && retryable(response.status, code)) {
      await sleep(backoff(attempt, response));
      continue;
    }
    throw new ZahloError(
      response.status,
      code,
      payload?.error?.message ?? response.statusText,
      payload?.error?.requestId ?? response.headers.get("x-request-id")
    );
  }
}

/** Lists return one page at a time; follow startingAfter until hasMore is false. */
export async function listAll<T extends { id: string }>(
  path: string
): Promise<T[]> {
  const items: T[] = [];
  let startingAfter = "";
  for (;;) {
    const page = await zahlo<{ data: T[]; hasMore: boolean }>(
      "GET",
      `${path}?limit=100${startingAfter ? `&startingAfter=${startingAfter}` : ""}`
    );
    items.push(...page.data);
    const last = page.data.at(-1);
    if (!(page.hasMore && last)) {
      return items;
    }
    startingAfter = last.id;
  }
}

import { DatabaseSync } from "node:sqlite";

// Any database with transactions works; SQLite keeps the quickstart self-contained.
export const db = new DatabaseSync(process.env.DATABASE_PATH ?? "store.db");

db.exec(`
  CREATE TABLE IF NOT EXISTS orders (
    id TEXT PRIMARY KEY,
    items TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending', -- pending | paid | expired | refunded | disputed
    session_id TEXT UNIQUE,
    payment_id TEXT,
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
  );
  CREATE TABLE IF NOT EXISTS processed_events (
    event_id TEXT PRIMARY KEY,
    processed_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
  );
  -- Work that cannot join the transaction (emails, shipping APIs) is queued here inside it.
  CREATE TABLE IF NOT EXISTS jobs (
    id INTEGER PRIMARY KEY,
    kind TEXT NOT NULL,
    order_id TEXT NOT NULL,
    done INTEGER NOT NULL DEFAULT 0,
    UNIQUE (kind, order_id)
  );
`);

/** Runs fn in one transaction: all of its writes commit together, or none do. */
export function transaction<T>(fn: () => T): T {
  db.exec("BEGIN IMMEDIATE");
  try {
    const result = fn();
    db.exec("COMMIT");
    return result;
  } catch (error) {
    db.exec("ROLLBACK");
    throw error;
  }
}

export type Order = {
  id: string;
  items: string;
  status: string;
  session_id: string | null;
  payment_id: string | null;
};

import { db } from "./db";
import { listAll, zahlo } from "./zahlo";

type Price = { id: string; lookupKey: string | null; active: boolean };
type Coupon = { id: string; code: string | null; active: boolean };
export type CheckoutSession = {
  id: string;
  url: string | null;
  clientToken: string | null;
  status: "open" | "complete" | "expired" | "failed";
  paymentStatus: "unpaid" | "paid" | "no_payment_required";
  paymentId: string | null;
  reference: string | null;
};

const siteUrl = process.env.SITE_URL ?? "http://localhost:3000";

/**
 * Saves a pending order and creates its Checkout Session. Prices are found by lookupKey, so the same
 * code works in sandbox and live, where every ID differs.
 */
export async function createOrderSession(input: {
  items: { lookupKey: string; quantity: number }[];
  promoCode?: string;
  mode: "hosted" | "embedded";
}): Promise<CheckoutSession> {
  const prices = await listAll<Price>("/prices");
  const lineItems = input.items.map((item) => {
    const price = prices.find((p) => p.active && p.lookupKey === item.lookupKey);
    if (!price) {
      throw new Error(`No price with lookupKey ${item.lookupKey}; run scripts/setup-catalog.mjs`);
    }
    return { priceId: price.id, quantity: item.quantity };
  });
  let couponId: string | undefined;
  if (input.promoCode) {
    const coupons = await listAll<Coupon>("/coupons");
    couponId = coupons.find(
      (c) => c.active && c.code?.toUpperCase() === input.promoCode?.toUpperCase()
    )?.id;
  }

  const orderId = crypto.randomUUID();
  db.prepare("INSERT INTO orders (id, items) VALUES (?, ?)").run(
    orderId,
    JSON.stringify(input.items)
  );
  const session = await zahlo<CheckoutSession>("POST", "/checkout-sessions", {
    // One key per order: a retried request returns the same session instead of a second one.
    idempotencyKey: `order-${orderId}`,
    body: {
      type: "payment",
      mode: input.mode,
      lineItems,
      couponId,
      reference: orderId,
      successUrl: `${siteUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancelUrl: `${siteUrl}/`,
    },
  });
  db.prepare("UPDATE orders SET session_id = ? WHERE id = ?").run(session.id, orderId);
  return session;
}

/** Reads an item list from a form: lookupKey, quantity and an optional promo code. */
export function cartFromForm(form: FormData) {
  return {
    items: [
      {
        lookupKey: String(form.get("lookupKey") ?? "tshirt"),
        quantity: Math.max(1, Number(form.get("quantity") ?? 1)),
      },
    ],
    promoCode: String(form.get("promoCode") ?? "").trim() || undefined,
  };
}

// The shop page: a plain form, so it works without client JavaScript.
export default function ShopPage() {
  return (
    <main>
      <h1>Shop</h1>
      <form action="/api/checkout" method="post">
        <label>
          Product
          <select name="lookupKey">
            <option value="tshirt">T-shirt (€25.00)</option>
            <option value="mug">Mug (€12.00)</option>
          </select>
        </label>
        <label>
          Quantity <input name="quantity" type="number" min="1" max="999" defaultValue="1" />
        </label>
        <label>
          Promo code <input name="promoCode" />
        </label>
        <button type="submit">Pay</button>
      </form>
    </main>
  );
}

import { cartFromForm, createOrderSession } from "../../../lib/checkout";
import { ZahloError } from "../../../lib/zahlo";

// Hosted checkout: create the session on the server, then send the browser to session.url.
export async function POST(request: Request) {
  try {
    const session = await createOrderSession({
      ...cartFromForm(await request.formData()),
      mode: "hosted",
    });
    return Response.redirect(session.url ?? "", 303);
  } catch (error) {
    if (error instanceof ZahloError) {
      console.error("checkout failed", error.code, error.requestId);
      return new Response(error.message, { status: error.status >= 500 ? 502 : 400 });
    }
    throw error;
  }
}

import { db, type Order } from "./db";
import { type CheckoutSession } from "./checkout";
import { zahlo } from "./zahlo";

/**
 * What the success page shows. It reads state and never fulfils: only the webhook marks an order paid,
 * because a customer can open the success URL without paying.
 */
export async function orderForSuccessPage(sessionId: string) {
  const session = await zahlo<CheckoutSession>("GET", `/checkout-sessions/${encodeURIComponent(sessionId)}`);
  const order = db.prepare("SELECT * FROM orders WHERE session_id = ?").get(session.id) as Order | undefined;
  return { order, paid: order?.status === "paid" };
}

import { orderForSuccessPage } from "../../lib/orders";

export const dynamic = "force-dynamic";

export default async function SuccessPage({
  searchParams,
}: {
  searchParams: Promise<{ session_id?: string }>;
}) {
  const { session_id: sessionId } = await searchParams;
  if (!sessionId) return <p>Missing session.</p>;
  const { order, paid } = await orderForSuccessPage(sessionId);
  if (!order) return <p>Order not found.</p>;
  return paid ? (
    <p>Thank you! Order {order.id} is paid.</p>
  ) : (
    // The webhook usually arrives within seconds; reload to check again.
    <p>Payment processing. Order {order.id} will be confirmed by email.</p>
  );
}

import { createHmac, timingSafeEqual } from "node:crypto";

export type ZahloEvent = {
  id: string;
  type: string;
  livemode: boolean;
  createdAt: string;
  data: { object: { id: string } & Record<string, unknown> };
};

/**
 * Checks `Zahlo-Signature: t=<unix>,v1=<hex>` against the raw request body and returns the parsed event,
 * or null when the signature is missing, wrong or older than 5 minutes. During a secret rotation the
 * header carries one v1 per secret, so any matching v1 is accepted.
 */
export function verifyZahloEvent(
  rawBody: string,
  header: string | null,
  secret: string,
  toleranceSeconds = 300
): ZahloEvent | null {
  const parts = (header ?? "").split(",").map((part) => part.trim().split("="));
  const timestamp = Number(parts.find(([key]) => key === "t")?.[1]);
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value ?? "");
  if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
    return null;
  }
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")
  );
  const valid = signatures.some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
  return valid ? (JSON.parse(rawBody) as ZahloEvent) : null;
}

import { type CheckoutSession } from "../../../../lib/checkout";
import { db, transaction } from "../../../../lib/db";
import { verifyZahloEvent } from "../../../../lib/webhook-signature";
import { zahlo } from "../../../../lib/zahlo";

type Refund = { id: string; paymentId: string; status: "pending" | "succeeded" | "failed" };
type Dispute = { id: string; paymentId: string; status: string };

export async function POST(request: Request) {
  // 1. Verify the signature on the raw body before trusting anything in it.
  const rawBody = await request.text();
  const event = verifyZahloEvent(
    rawBody,
    request.headers.get("zahlo-signature"),
    process.env.ZAHLO_WEBHOOK_SECRET ?? ""
  );
  if (!event) return new Response("Invalid signature", { status: 400 });

  // 2. Re-fetch the object and act on its current state, so a late, older event cannot undo a newer one.
  const id = encodeURIComponent(event.data.object.id);
  let apply: () => void = () => {};
  if (event.type === "checkout.session.completed" || event.type === "checkout.session.expired") {
    const session = await zahlo<CheckoutSession>("GET", `/checkout-sessions/${id}`);
    apply = () => {
      if (session.paymentStatus === "paid") {
        const paid = db
          .prepare("UPDATE orders SET status = 'paid', payment_id = ? WHERE session_id = ? AND status = 'pending'")
          .run(session.paymentId, session.id);
        if (paid.changes === 1) {
          db.prepare("INSERT OR IGNORE INTO jobs (kind, order_id) VALUES ('confirmation_email', ?)").run(
            session.reference
          );
        }
      } else if (session.status === "expired") {
        db.prepare("UPDATE orders SET status = 'expired' WHERE session_id = ? AND status = 'pending'").run(session.id);
      }
    };
  } else if (event.type === "refund.succeeded") {
    const refund = await zahlo<Refund>("GET", `/refunds/${id}`);
    apply = () => {
      if (refund.status === "succeeded") {
        db.prepare("UPDATE orders SET status = 'refunded' WHERE payment_id = ?").run(refund.paymentId);
      }
    };
  } else if (event.type === "dispute.created") {
    const dispute = await zahlo<Dispute>("GET", `/disputes/${id}`);
    apply = () => {
      // Hold the shipment and answer the dispute in the dashboard.
      db.prepare("UPDATE orders SET status = 'disputed' WHERE payment_id = ? AND status = 'paid'").run(dispute.paymentId);
    };
  }

  // 3. Record the event and apply the change in ONE transaction, and answer 2xx only after it commits.
  //    A crash before the commit rolls back both, so Zahlo's retry does the work again.
  transaction(() => {
    const fresh = db
      .prepare("INSERT INTO processed_events (event_id) VALUES (?) ON CONFLICT DO NOTHING")
      .run(event.id);
    if (fresh.changes === 1) apply();
  });
  return new Response("ok");
}