Node SDK (@zylopay/node)

InstallCopy Anchor Link

Coming soon on npm. Once published:

npm install @zylopay/node

Node.js 18 or later (it uses the built-in fetch). No runtime dependencies; ESM and CommonJS; TypeScript types generated from the OpenAPI spec. Secret keys only: the constructor refuses a publishable key.

ConfigureCopy Anchor Link

import ZyloPay from '@zylopay/node';

const zp = new ZyloPay(process.env.ZYLOPAY_SECRET_KEY!);

Options, as a second argument:

const zp = new ZyloPay(process.env.ZYLOPAY_SECRET_KEY!, { maxNetworkRetries: 3, timeout: 20_000, apiVersion: '2026-09-28' });

The key's prefix sets the mode: a zp_test_sk_ key works on the testnet sandbox, a zp_live_sk_ key on mainnet.

ResourcesCopy Anchor Link

Every method follows one pattern: (id?, params?, requestOptions?). Methods without parameters take the request options second. Responses are the API's JSON objects, with the same snake_case fields.

Request options, the last argument of every method: idempotencyKey, apiVersion, timeout, maxNetworkRetries and signal (an AbortSignal; an aborted request throws ConnectionError with code: "aborted" and is never retried).

import { randomUUID } from 'node:crypto';

const intent = await zp.paymentIntents.create(
  { amount: 2500000, terminal: 'tml_ZP-4821-K', order_id: 'A7K2Q9XZ' },
  { idempotencyKey: `intent-${orderId}` },
);

const refund = await zp.refunds.create({ payment: 'pay_1042', amount: 1000000 }, { idempotencyKey: randomUUID() });

PaginationCopy Anchor Link

list methods can be awaited for one page, or iterated with for await to walk every page:

const page = await zp.payments.list({ limit: 50 });
console.log(page.data, page.has_more, page.next_cursor);

for await (const payment of zp.payments.list({ limit: 50 })) {
  console.log(payment.id);
}

Retries and timeoutsCopy Anchor Link

The SDK retries automatically, up to maxNetworkRetries times, with exponential backoff and jitter, on:

• network errors and timeouts;
• 409 idempotency_request_in_progress;
• 429, honouring Retry-After and RateLimit-Reset;
• 5xx.

Every POST, PATCH and DELETE gets an idempotency key generated by the SDK (a UUID v4) and reused across its retries, so retries never create a second object. Pass your own idempotencyKey when your application may re-submit the same operation later, for example after a crash: an SDK-generated key does not survive a restart.

WebhooksCopy Anchor Link

const event = zp.webhooks.constructEvent(rawBody, req.headers['zylopay-signature'], process.env.ZYLOPAY_WEBHOOK_SECRET!);

rawBody must be the body exactly as received (a string or Buffer). constructEvent checks the timestamp (5 minutes by default, or the fourth argument in seconds), accepts any matching v1 signature, and returns the parsed event. It throws ZyloPay.errors.SignatureVerificationError otherwise, with a code such as malformed, no_matching_signature or timestamp_out_of_tolerance. ZyloPay.webhooks.constructEvent(…) works without a client or API key. See Verify signatures.

To test your handler without ZyloPay, sign a payload yourself:

const header = ZyloPay.webhooks.generateTestHeaderString({ payload: rawBody, secret: 'whsec_test_secret' });
// Pass several secrets to simulate a rotation overlap: { payload, secret: [newSecret, oldSecret] }

ErrorsCopy Anchor Link

Every error extends ZyloPay.errors.ZyloPayError and has .type, .code, .param, .message, .requestId, .statusCode and .headers.

try {
  await zp.paymentIntents.cancel(intentId, { idempotencyKey: `cancel-${intentId}` });
} catch (err) {
  if (err instanceof ZyloPay.errors.InvalidRequestError && err.code === 'payment_intent_unexpected_state') {
    // already paid: refund instead
  } else {
    throw err;
  }
}

Request IDsCopy Anchor Link

Each result exposes the response metadata:

const payment = await zp.payments.retrieve('pay_1042');
console.log(payment.lastResponse.requestId, payment.lastResponse.statusCode);

const refund = await zp.refunds.create({ payment: 'pay_1042' }, { idempotencyKey: 'refund-R-2211' });
console.log(refund.lastResponse.idempotencyKey, refund.lastResponse.idempotentReplayed);

lastResponse also carries the response headers and the apiVersion it was rendered with. It is non-enumerable, so it does not appear when you serialize the object.