url (hosted) or a session ID and client token (embedded); it never gets the API key or the webhook secret.
The maintained, dependency-free example is the website quickstart server (snippets/code/website-node/server.mjs). This page shows the same pieces in Express. It runs on Node 18 or later with the built-in fetch.
Client
One function sets the origin, the API key, a timeout and theIdempotency-Key. Every POST gets one key, which is reused on each retry, so a retry can never create a second object. Retry only on a network error, 409 request_in_progress, 429 or 5xx, at most twice, honouring Retry-After.
Create a checkout session
Compute the amount from your own order record, never from the request body, and derive theIdempotency-Key from the order so a double click reuses the same session.
mode: "embedded" and return only session.id and session.clientToken to the page that mounts the JavaScript SDK.
Webhook
Fulfil only from a verified webhook, never from the browser’s return. Register the webhook route withexpress.raw() before any express.json(), because the signature covers the exact bytes Zahlo sent. Zahlo-Signature is t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> with your endpoint secret. During a secret rotation two v1 values are sent, and either may match.
Lists
Lists return one page ({ object: "list", data, hasMore }). Most lists, /payments included, page by cursor: pass the last item’s id as startingAfter until hasMore is false. /transactions pages by offset. Every list answers an unknown query parameter or a cursor id it can’t find with a 400 parameter_invalid.
@zahlo/node
The@zahlo/node package wraps the same rules: retries with one Idempotency-Key, typed request bodies, typed errors, for await over every list, and webhooks.constructEvent returning an event typed by event.type. Use it once it is on npm. Until then, the code above is the supported path.