@zahlo/node
v1.2.0
Published
Zahlo server SDK for Node.js and Bun: checkout sessions, payments, refunds, subscriptions and webhook verification
Readme
@zahlo/node
Server SDK for the Zahlo merchant API. Zero dependencies, Node.js ≥ 18 and Bun, ESM and CommonJS.
npm install @zahlo/nodeimport { Zahlo } from "@zahlo/node";
const zahlo = new Zahlo(process.env.ZAHLO_API_KEY!); // zk_test_… → sandbox, zk_live_… → live
const session = await zahlo.checkoutSessions.create({
mode: "hosted",
currency: "EUR",
lineItems: [{ name: "T-shirt", unitAmountMinor: 2500, quantity: 1 }],
successUrl: "https://shop.example/success?session={CHECKOUT_SESSION_ID}",
cancelUrl: "https://shop.example/cart",
});
// Redirect the browser to session.urlTyped request bodies
Every create, update and cancel takes the body type from the API contract (CheckoutSessionCreateParams, RefundCreateParams, …, all exported), so a missing required field or a wrong enum value fails at compile time. The types are generated from the merchant API's OpenAPI document.
Lists
list() resolves to one page ({ data, hasMore }) and is also async-iterable over every item, fetching later pages as needed:
for await (const refund of zahlo.refunds.list({ limit: 100 })) {
console.log(refund.id, refund.status);
}
const recent = await zahlo.payments.list().autoPagingToArray({ limit: 500 });Webhooks
Verify against the raw request body. The result is typed by event.type:
const event = zahlo.webhooks.constructEvent(
await request.text(),
request.headers.get("zahlo-signature"),
process.env.ZAHLO_WEBHOOK_SECRET!
);
if (event.type === "checkout.session.completed") {
await fulfil(event.data.object.id); // a CheckoutSession
}Retries and idempotency
Every POST, PATCH and DELETE sends an Idempotency-Key (a UUID unless you pass idempotencyKey). Requests are retried up to maxRetries (default 2) on network errors, timeouts, 409 request_in_progress, 429 and 5xx, always with the same key, honouring Retry-After. Other 4xx errors are never retried.
Errors
Failures throw ZahloError subclasses (ZahloInvalidRequestError, ZahloAuthenticationError, ZahloPermissionError, ZahloPaymentBlockedError, ZahloIdempotencyError, ZahloRateLimitError, ZahloProviderError, ZahloAPIError, ZahloConnectionError; constructEvent throws ZahloSignatureVerificationError) with type, code, param, requestId and statusCode.
Anything without a typed method is reachable with zahlo.request(method, path, { body, query, idempotencyKey }).
Full guide: https://docs.zahlo.eu/integrations/node
