- Create the checkout session on your server.
- Fulfil the order on
checkout.session.completed. - Mark the order
refundedonrefund.succeeded. - Flag the order
disputedondispute.created, and hold the shipment. - Run the refund test: refund a paid test order and check that it shows
refunded(see Reverse on refunds and disputes).
refunded or disputed state yet, add them: a new value in the existing status column is enough.
You need: a Zahlo account and its zk_test_ API key (Developers → API keys, with Test mode on), Node.js 22.5 or later, and cloudflared (brew install cloudflared, or a package from Cloudflare’s downloads page) to receive webhooks on your machine.
1
Set environment variables
Create
.env.local in the project root. Keep it out of version control; the key never reaches the browser..env.local
2
Register your domains
Customers return to your site through Zahlo, which only sends them to hosts you registered. Register your site’s host once per environment, in the dashboard (Developers → Checkout domains) or with the API. It takes effect immediately.A session whose For this quickstart, register
successUrl or cancelUrl uses an unregistered host fails with checkout_domain_not_registered (400). A checkout_domain_pending (409) means Zahlo is still enabling checkout for your account, once, after approval; retry later or contact support.Local development: in test mode (
zk_test_ keys) you can register localhost:3000 (or 127.0.0.1:3000) and use http:// return URLs. Live requires HTTPS.localhost:3000 in test mode.3
Create the catalogue
Test mode and live are separate, so their product and price IDs differ. Your code finds prices by
lookupKey instead. This script creates them once per environment, and running it again creates nothing:scripts/setup-catalog.mjs
4
Add the API client and database
The client sends one The quickstart stores orders in SQLite (
Idempotency-Key per operation and retries only network errors, 409 request_in_progress, 429 and 5xx, at most twice, with the same key.lib/zahlo.ts
node:sqlite, built into Node.js). Use your own database the same way: what matters is the transaction.lib/db.ts
5
Create the Checkout Session
lib/checkout.ts
app/page.tsx
app/api/checkout/route.ts
lib/orders.ts
app/success/page.tsx
6
Handle webhooks
lib/webhook-signature.ts
app/api/webhooks/zahlo/route.ts
- Verify first. Check
Zahlo-Signatureon the raw request body and answer400when it is missing, wrong or older than 5 minutes. - Act on current state. Events can arrive late, twice or out of order. Re-fetch the object (
GET /checkout-sessions/:id,GET /subscriptions/:id) and act on what it says now, not on the event payload. - Commit, then answer. Record the event ID and apply the change in one database transaction, and return
2xxonly after it commits. A duplicate event inserts nothing and changes nothing. If your server crashes before the commit, nothing is saved, and Zahlo’s retry (1 minute, 5 minutes, … up to 3 days) does the work again. Never record the event, answer200, and do the work afterwards.
https://….trycloudflare.com URL:checkout.session.completed and checkout.session.expired for orders, refund.succeeded and dispute.created for reversals. The response shows the signing secret once: put it in ZAHLO_WEBHOOK_SECRET and restart the dev server.7
Handle refunds and disputes
The handler also reacts to reversals. If you adapt it to an existing app instead of copying it, keep these branches and subscribe your webhook endpoint to their events. Without them, a refunded order stays Within a few seconds your server logs a
paid, and a disputed order is never flagged, so it can still ship:refund.succeeded: the order is markedrefunded. Refund from the dashboard or withPOST /refunds; a refund is final only whenrefund.succeededorrefund.failedarrives. See Refunds.dispute.created: the order is markeddisputed. Hold the shipment and respond in the dashboard before the deadline. See Disputes.
refund.succeeded delivery and the order shows refunded. If it still shows paid, your handler is missing the refund.succeeded branch.8
Test a payment
http://localhost:3000, buy 3 T-shirts with the promo code WELCOME15, and pay with the test card 4111 1111 1111 1111, expiry 03/30, CVC 737. Check that:- the hosted page shows €63.75 (3 × €25.00, minus 15%);
- your server logs a
checkout.session.completeddelivery, and the success page shows the order as paid after a reload; - the payment appears under Payments in the dashboard, and the delivery under Developers → Webhooks.
pending, and checkout.session.expired marks it expired when the session ends), and resend a delivery from Developers → Webhooks (nothing changes the second time).Then refund the test order as the previous step shows, and check that it shows refunded.9
Go live
Your live account starts empty, and Test-mode IDs, keys and secrets don’t work there. Recreate what this integration uses, in this order (details: Go live; your live dashboard’s Go live page at
https://merchant.zahlo.eu/merchant/go-live tracks each step):- Create a live API key and set
ZAHLO_API_KEYto it (zk_live_…). Code that readsZAHLO_API_BASEsets it tohttps://merchant.zahlo.eu. - Run
setup-catalogagainst live. It creates the samelookupKeys and coupon codes, so your code needs no change. - Recreate your payment links; live links have new URLs.
- Add your live webhook endpoint, set
ZAHLO_WEBHOOK_SECRETto its new signing secret, and confirm one live delivery arrives. - Register your site’s checkout domain in live (HTTPS only), plus the Apple Pay domain if you embed checkout with wallets.
- Customers, subscriptions and saved payment methods don’t carry over; real checkouts create them.
- Make one small live payment, check that
payment.confirmedand your fulfilment ran, then refund it.