@hypay/typescript-sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1067 @@
+import {
+  buildItemsString,
+  calculateItemsTotal,
+  isTestMasof,
+  isValidEmail,
+  isValidIsraeliId,
+  isValidMasof,
+  isValidToken,
+  parsePaymentPageResponse,
+  parseQueryString,
+  parseRedirectUrl,
+  parseTokef,
+  serializeParams,
+  toQueryString
+} from "./chunk-LKIXYEBZ.mjs";
+
+// src/types.ts
+var Coin = /* @__PURE__ */ ((Coin2) => {
+  Coin2[Coin2["ILS"] = 1] = "ILS";
+  Coin2[Coin2["USD"] = 2] = "USD";
+  Coin2[Coin2["EUR"] = 3] = "EUR";
+  Coin2[Coin2["GBP"] = 4] = "GBP";
+  return Coin2;
+})(Coin || {});
+var PageLang = /* @__PURE__ */ ((PageLang2) => {
+  PageLang2["HEB"] = "HEB";
+  PageLang2["ENG"] = "ENG";
+  return PageLang2;
+})(PageLang || {});
+var TashType = /* @__PURE__ */ ((TashType2) => {
+  TashType2[TashType2["Regular"] = 1] = "Regular";
+  TashType2[TashType2["Credit"] = 6] = "Credit";
+  return TashType2;
+})(TashType || {});
+var Bank = /* @__PURE__ */ ((Bank2) => {
+  Bank2[Bank2["Isracard"] = 1] = "Isracard";
+  Bank2[Bank2["VisaCal"] = 2] = "VisaCal";
+  Bank2[Bank2["Diners"] = 3] = "Diners";
+  Bank2[Bank2["Amex"] = 4] = "Amex";
+  Bank2[Bank2["MAX"] = 6] = "MAX";
+  Bank2[Bank2["BIT"] = 99] = "BIT";
+  return Bank2;
+})(Bank || {});
+var Brand = /* @__PURE__ */ ((Brand2) => {
+  Brand2[Brand2["PL"] = 0] = "PL";
+  Brand2[Brand2["MasterCard"] = 1] = "MasterCard";
+  Brand2[Brand2["Visa"] = 2] = "Visa";
+  Brand2[Brand2["Diners"] = 3] = "Diners";
+  Brand2[Brand2["Amex"] = 4] = "Amex";
+  Brand2[Brand2["Isracard"] = 5] = "Isracard";
+  return Brand2;
+})(Brand || {});
+var Issuer = /* @__PURE__ */ ((Issuer2) => {
+  Issuer2[Issuer2["Foreign"] = 0] = "Foreign";
+  Issuer2[Issuer2["Isracard"] = 1] = "Isracard";
+  Issuer2[Issuer2["VisaCal"] = 2] = "VisaCal";
+  Issuer2[Issuer2["JCB"] = 5] = "JCB";
+  Issuer2[Issuer2["MAX"] = 6] = "MAX";
+  return Issuer2;
+})(Issuer || {});
+var HKNewStatus = /* @__PURE__ */ ((HKNewStatus2) => {
+  HKNewStatus2[HKNewStatus2["Terminate"] = 1] = "Terminate";
+  HKNewStatus2[HKNewStatus2["Activate"] = 2] = "Activate";
+  return HKNewStatus2;
+})(HKNewStatus || {});
+var SpecialCardType = /* @__PURE__ */ ((SpecialCardType2) => {
+  SpecialCardType2["Default"] = "00";
+  SpecialCardType2["Immediate"] = "01";
+  SpecialCardType2["Club"] = "70";
+  SpecialCardType2["PetrolCard"] = "03";
+  SpecialCardType2["DualCard"] = "04";
+  SpecialCardType2["DualClub"] = "74";
+  SpecialCardType2["PetrolClub"] = "75";
+  SpecialCardType2["Chargeable"] = "06";
+  SpecialCardType2["Petrol"] = "08";
+  SpecialCardType2["Tourist"] = "99";
+  return SpecialCardType2;
+})(SpecialCardType || {});
+var HypayError = class extends Error {
+  constructor(message, code, raw, params) {
+    super(message);
+    this.name = "HypayError";
+    this.code = code;
+    this.raw = raw;
+    this.params = params;
+  }
+};
+var HypayNetworkError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "HypayNetworkError";
+    this.cause = cause;
+  }
+};
+var HypayTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.name = "HypayTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// src/errors.ts
+var HYPAY_ERROR_CODES = {
+  "33": "Refund amount is greater than the original transaction amount",
+  "250": "Deal does not exist or already committed",
+  "400": "Sum of items differs from transaction amount",
+  "401": "First or last name is required",
+  "402": "Transaction information (Info) is required",
+  "600": "Checking card number (J2)",
+  "700": "Approved without charge (J5 credit line reservation)",
+  "800": "Postpone transaction (delayed charge)",
+  "901": "Terminal is not permitted to work in this method",
+  "902": "Authentication error \u2014 reference differs from configured method",
+  "903": "Number of payments exceeds terminal configuration",
+  "905": "Wrong parameter value",
+  "906": "Agreement does not exist",
+  "910": "Token request from invalid transaction \u2014 add allowFalse=True",
+  "920": "Deal does not exist or already committed/cancelled",
+  "990": "Card details not fully readable",
+  "996": "Terminal is not permitted to use token",
+  "997": "Token is not valid",
+  "998": "Deal cancelled",
+  "999": "Communication error"
+};
+var SHVA_ERROR_CODES = {
+  "0": "Approved",
+  "000": "Approved",
+  "1": "Card blocked \u2014 confiscate card",
+  "001": "Card blocked",
+  "2": "Stolen card \u2014 confiscate card",
+  "002": "Stolen card \u2014 confiscate card",
+  "3": "Call credit card company",
+  "003": "Call credit card company",
+  "4": "Transaction not approved",
+  "004": "Transaction not approved",
+  "5": "Forged card \u2014 confiscate card",
+  "005": "Forged card \u2014 confiscate card",
+  "6": "Incorrect ID or CVV",
+  "006": "Rejected: incorrect CVV2",
+  "7": "Must call credit card company",
+  "007": "Rejected: incorrect CAVV/UCAF",
+  "8": "Error building encryption key for blocked file",
+  "008": "Rejected: incorrect AVS",
+  "9": "Could not connect \u2014 call credit card company",
+  "009": "Rejection \u2014 communication disconnect",
+  "010": "Partial approval",
+  "011": "Rejected: insufficient points/stars/miles/benefit",
+  "012": "Card not authorized at this terminal",
+  "013": "Rejected: incorrect balance code",
+  "014": "Rejected: card not associated with network",
+  "015": "Rejected: card not valid (expired)",
+  "016": "Rejected: currency not authorized",
+  "017": "Rejected: credit type not authorized for transaction",
+  "026": "Rejected: incorrect ID",
+  "033": "Invalid card",
+  "036": "Expired card",
+  "041": "Must query due to ceiling only for J2 transaction",
+  "042": "Must query (not ceiling-only) for J2 transaction",
+  "173": "Duplicate transaction"
+};
+var ALL_ERROR_CODES = {
+  ...SHVA_ERROR_CODES,
+  ...HYPAY_ERROR_CODES
+};
+function getErrorMessage(ccode) {
+  return ALL_ERROR_CODES[ccode] ?? `Unknown error (CCode=${ccode})`;
+}
+function isSuccessCode(ccode) {
+  return ccode === "0" || ccode === "600" || ccode === "700" || ccode === "800";
+}
+function isShvaError(ccode) {
+  const num = parseInt(ccode, 10);
+  return !isNaN(num) && num >= 1 && num <= 200;
+}
+function isHypayError(ccode) {
+  const num = parseInt(ccode, 10);
+  if (isNaN(num)) return false;
+  if (num === 600 || num === 700 || num === 800) return false;
+  return num >= 201 && num <= 999;
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://pay.hyp.co.il/p/";
+var DEFAULT_TIMEOUT = 3e4;
+var HypayClient = class {
+  constructor(config) {
+    this.masof = config.masof;
+    this.apiKey = config.apiKey;
+    this.passP = config.passP;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/?$/, "/");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.fetchFn = config.fetch ?? globalThis.fetch;
+    this.hooks = config.hooks ?? {};
+  }
+  // ─── Low-level HTTP ──────────────────────────────────────────────────────
+  /**
+   * Make a GET request to the Hypay API.
+   * All API calls use GET by default, which is the most common method for Hypay.
+   */
+  async requestGet(action, params) {
+    const serialized = serializeParams(params);
+    const qs = toQueryString(serialized);
+    const url = `${this.baseUrl}?${qs}`;
+    const context = {
+      action,
+      method: "GET",
+      url,
+      params: Object.fromEntries(
+        Object.entries(serialized).filter(([, v]) => v !== void 0).map(([k, v]) => [k, String(v)])
+      )
+    };
+    await this.hooks.onRequest?.(context);
+    const start = Date.now();
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        response = await this.fetchFn(url, { signal: controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        throw new HypayTimeoutError(this.timeout);
+      }
+      throw new HypayNetworkError(
+        `Network error while calling Hypay API: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    }
+    const text = await response.text();
+    const parsed = parseQueryString(text);
+    const durationMs = Date.now() - start;
+    await this.hooks.onResponse?.({
+      ...context,
+      statusCode: response.status,
+      raw: text,
+      parsedParams: parsed,
+      durationMs
+    });
+    return { raw: text, params: parsed };
+  }
+  /**
+   * Make a POST request to the Hypay API.
+   * Use for actions that send large payloads (e.g., WalletToken with Apple Pay).
+   */
+  async requestPost(action, params) {
+    const serialized = serializeParams(params);
+    const body = toQueryString(serialized);
+    const context = {
+      action,
+      method: "POST",
+      url: this.baseUrl,
+      params: Object.fromEntries(
+        Object.entries(serialized).filter(([, v]) => v !== void 0).map(([k, v]) => [k, String(v)])
+      )
+    };
+    await this.hooks.onRequest?.(context);
+    const start = Date.now();
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        response = await this.fetchFn(this.baseUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body,
+          signal: controller.signal
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        throw new HypayTimeoutError(this.timeout);
+      }
+      throw new HypayNetworkError(
+        `Network error while calling Hypay API: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    }
+    const text = await response.text();
+    const parsed = parseQueryString(text);
+    const durationMs = Date.now() - start;
+    await this.hooks.onResponse?.({
+      ...context,
+      statusCode: response.status,
+      raw: text,
+      parsedParams: parsed,
+      durationMs
+    });
+    return { raw: text, params: parsed };
+  }
+  /**
+   * Unified request method. Defaults to GET, uses POST for wallet/large payloads.
+   */
+  async request(action, params, method = "GET") {
+    return method === "POST" ? this.requestPost(action, params) : this.requestGet(action, params);
+  }
+  authParams() {
+    return {
+      Masof: this.masof,
+      PassP: this.passP
+    };
+  }
+  throwIfError(parsed, raw, context) {
+    if (parsed.CCode && !isSuccessCode(parsed.CCode)) {
+      const error = new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+      if (context) {
+        this.hooks.onError?.(error, context);
+      }
+      throw error;
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  PAY PROTOCOL — Payment Page
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * **Step 1** — Sign payment page parameters (APISign + What=SIGN).
+   *
+   * This generates a `signature` that must be appended to the payment page URL.
+   * The signature prevents parameter tampering on the client side.
+   *
+   * Requires "Verify by signature in the payment page" enabled in terminal settings.
+   *
+   * @example
+   * ```ts
+   * const result = await client.sign({
+   *   Info: "Order #123",
+   *   Amount: 100,
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   Coin: Coin.ILS,
+   *   Sign: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   *   MoreData: true,
+   * });
+   * console.log(result.signature);
+   * ```
+   */
+  async sign(params) {
+    const allParams = {
+      action: "APISign",
+      What: "SIGN",
+      KEY: this.apiKey,
+      ...this.authParams(),
+      ...params
+    };
+    const { raw, params: parsed } = await this.request("APISign", allParams);
+    return {
+      raw,
+      signature: parsed.signature ?? "",
+      params: parsed
+    };
+  }
+  /**
+   * **Step 2** — Build the full payment page URL from a signed query string.
+   *
+   * @param signedQueryString - The raw result from `sign()`.
+   */
+  buildPaymentPageUrl(signedQueryString) {
+    return `${this.baseUrl}?${signedQueryString}`;
+  }
+  /**
+   * **Steps 1 + 2 combined** — Sign parameters and return the full payment page URL.
+   *
+   * @example
+   * ```ts
+   * const url = await client.createPaymentPageUrl({
+   *   Info: "Order #123",
+   *   Amount: 100,
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   Coin: Coin.ILS,
+   *   Sign: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * // Redirect the customer to `url`
+   * ```
+   */
+  async createPaymentPageUrl(params) {
+    const signResult = await this.sign(params);
+    return this.buildPaymentPageUrl(signResult.raw);
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  VERIFICATION — Verify transaction signature
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * **Step 4** — Verify a transaction using parameters from the success page.
+   *
+   * Takes the query parameters from the success/failure redirect URL and verifies
+   * them against the Hypay server. Returns `verified: true` when `CCode === "0"`,
+   * `CCode === "902"` means verification failed.
+   *
+   * Requires "Verify by signature in the payment page" enabled in terminal settings.
+   *
+   * @example
+   * ```ts
+   * import { parseRedirectUrl } from "@hypay/typescript-sdk";
+   *
+   * const successParams = parseRedirectUrl(req.url);
+   * const result = await client.verify(successParams);
+   *
+   * if (result.verified) {
+   *   // Transaction is legitimate — process the order
+   * } else {
+   *   // Verification failed — do not process
+   * }
+   * ```
+   */
+  async verify(params) {
+    const allParams = {
+      action: "APISign",
+      What: "VERIFY",
+      KEY: this.apiKey,
+      ...this.authParams(),
+      ...params
+    };
+    const { raw, params: parsed } = await this.request("APISign-VERIFY", allParams);
+    return {
+      verified: parsed.CCode === "0",
+      CCode: parsed.CCode ?? "",
+      raw,
+      params: parsed
+    };
+  }
+  /**
+   * Convenience method: parse a success page URL and verify it in one call.
+   *
+   * @example
+   * ```ts
+   * const result = await client.verifyRedirectUrl(
+   *   "https://yoursite.com/success?Id=123&CCode=0&Amount=10&..."
+   * );
+   * if (result.verified) { /* OK *\/ }
+   * ```
+   */
+  async verifyRedirectUrl(redirectUrl) {
+    const { parseRedirectUrl: parseRedirectUrl2 } = await import("./helpers-T6ONVODW.mjs");
+    const params = parseRedirectUrl2(redirectUrl);
+    return this.verify(params);
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  SOFT PROTOCOL — Server-side transactions
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Execute a server-side transaction using the Soft protocol.
+   *
+   * Used for:
+   * - Token-based charges (after obtaining a token via `getToken()`)
+   * - Apple Pay / Google Pay via WalletToken
+   * - Direct credit card charges (PCI-compliant environments)
+   *
+   * Automatically uses POST for WalletToken requests (large payload).
+   *
+   * @throws {HypayError} When CCode indicates an error
+   *
+   * @example
+   * ```ts
+   * // Token-based transaction
+   * const result = await client.soft({
+   *   CC: "1315872608557940000",
+   *   Tmonth: "04",
+   *   Tyear: "2025",
+   *   Amount: 50,
+   *   Info: "Subscription renewal",
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   Token: true,
+   *   MoreData: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Apple Pay / Google Pay
+   * const result = await client.soft({
+   *   WalletToken: walletTokenJson,
+   *   Amount: 100,
+   *   Info: "Purchase",
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   * });
+   * ```
+   */
+  async soft(params) {
+    const allParams = {
+      action: "soft",
+      ...this.authParams(),
+      ...params
+    };
+    const method = "WalletToken" in params && params.WalletToken ? "POST" : "GET";
+    const { raw, params: parsed } = await this.request("soft", allParams, method);
+    if (parsed.CCode && !isSuccessCode(parsed.CCode)) {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      Amount: parsed.Amount ?? "",
+      ACode: parsed.ACode ?? "",
+      Fild1: parsed.Fild1,
+      Fild2: parsed.Fild2,
+      Fild3: parsed.Fild3,
+      Hesh: parsed.Hesh,
+      UID: parsed.UID,
+      errMsg: parsed.errMsg,
+      raw,
+      params: parsed
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  TOKENS — Get and manage tokens
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Obtain a token for a previously completed transaction.
+   *
+   * The token (19 digits) replaces credit card information for future Soft transactions.
+   * The transaction must be in one of these statuses: Approved (0), 600, 700, 800, 998.
+   *
+   * **Important:** Save the Tokef (card validity) and customer details (UserId, etc.)
+   * as they are NOT stored in Hypay servers.
+   *
+   * The response includes convenience fields `Tmonth` and `Tyear` parsed from `Tokef`.
+   *
+   * @throws {HypayError} When CCode indicates an error (901, 902, 910, 990)
+   *
+   * @example
+   * ```ts
+   * const token = await client.getToken({ TransId: "12788261" });
+   *
+   * // Save for future charges:
+   * // token.Token  = "1315872608557940000"
+   * // token.Tmonth = "04"
+   * // token.Tyear  = "2025"
+   *
+   * // Use in a soft transaction:
+   * await client.soft({
+   *   CC: token.Token,
+   *   Tmonth: token.Tmonth,
+   *   Tyear: token.Tyear,
+   *   Token: true,
+   *   Amount: 50,
+   *   Info: "Charge via token",
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   * });
+   * ```
+   */
+  async getToken(params) {
+    const allParams = {
+      action: "getToken",
+      ...this.authParams(),
+      TransId: params.TransId,
+      Fild1: params.Fild1,
+      Fild2: params.Fild2,
+      Fild3: params.Fild3,
+      allowFalse: params.allowFalse
+    };
+    const { raw, params: parsed } = await this.request("getToken", allParams);
+    if (parsed.CCode && parsed.CCode !== "0") {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    let Tmonth = "";
+    let Tyear = "";
+    if (parsed.Tokef && parsed.Tokef.length === 4) {
+      const parsed_tokef = parseTokef(parsed.Tokef);
+      Tmonth = parsed_tokef.Tmonth;
+      Tyear = parsed_tokef.Tyear;
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      Token: parsed.Token ?? "",
+      Tokef: parsed.Tokef ?? "",
+      Tmonth,
+      Tyear,
+      Fild1: parsed.Fild1,
+      Fild2: parsed.Fild2,
+      Fild3: parsed.Fild3,
+      raw,
+      params: parsed
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  TRANSACTION J5 — Charge a J5 reservation
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Charge a J5 (credit line reservation) transaction.
+   *
+   * When a Pay/Soft request was made with `J5=True` and `MoreData=True`,
+   * you can later charge the reserved amount using the UID and ACode from the response.
+   *
+   * **If charge amount <= original J5 amount:** use this method (soft + additional params).
+   * **If charge amount > original J5 amount:** use the regular token flow instead.
+   *
+   * @param tokenParams - Standard Soft token parameters (CC, Tmonth, Tyear, etc.)
+   * @param j5Params - J5-specific parameters (originalUid, originalAmount, AuthNum)
+   *
+   * @throws {HypayError} When CCode indicates an error
+   *
+   * @example
+   * ```ts
+   * const result = await client.chargeJ5(
+   *   {
+   *     CC: token.Token,
+   *     Tmonth: token.Tmonth,
+   *     Tyear: token.Tyear,
+   *     Token: true,
+   *     Amount: 50,
+   *     Info: "J5 charge",
+   *     UserId: "203269535",
+   *     ClientName: "Israel",
+   *   },
+   *   {
+   *     "inputObj.originalUid": originalResponse.UID,
+   *     "inputObj.originalAmount": 5000, // 50 ILS in agorot
+   *     AuthNum: originalResponse.ACode,
+   *     "inputObj.authorizationCodeManpik": 7,
+   *   }
+   * );
+   * ```
+   */
+  async chargeJ5(tokenParams, j5Params) {
+    const allParams = {
+      action: "soft",
+      ...this.authParams(),
+      ...tokenParams,
+      ...j5Params
+    };
+    const { raw, params: parsed } = await this.request("soft-J5", allParams);
+    if (parsed.CCode && !isSuccessCode(parsed.CCode)) {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      Amount: parsed.Amount ?? "",
+      ACode: parsed.ACode ?? "",
+      Fild1: parsed.Fild1,
+      Fild2: parsed.Fild2,
+      Fild3: parsed.Fild3,
+      Hesh: parsed.Hesh,
+      UID: parsed.UID,
+      errMsg: parsed.errMsg,
+      raw,
+      params: parsed
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  POSTPONE — Commit delayed transactions
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Commit a postponed transaction (CCode 800).
+   *
+   * Postponed transactions should be committed within 72 hours.
+   * If not committed, leave at status 800 (do not cancel).
+   *
+   * @throws {HypayError} When CCode indicates an error (250 = doesn't exist / already committed)
+   *
+   * @example
+   * ```ts
+   * const result = await client.commitTransaction({
+   *   TransId: "5343635",
+   *   SendHesh: true,
+   *   heshDesc: "Payment for order 1234",
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * console.log(result.HeshASM); // Invoice number
+   * ```
+   */
+  async commitTransaction(params) {
+    const allParams = {
+      action: "commitTrans",
+      ...this.authParams(),
+      ...params
+    };
+    const { raw, params: parsed } = await this.request("commitTrans", allParams);
+    if (parsed.CCode && parsed.CCode !== "0") {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      HeshASM: parsed.HeshASM,
+      Fild1: parsed.Fild1,
+      Fild2: parsed.Fild2,
+      Fild3: parsed.Fild3,
+      raw,
+      params: parsed
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  CANCEL — Cancel a transaction
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Cancel a transaction.
+   *
+   * **Rules:**
+   * - Only on the same day, before 23:20 (before SHVA deposit)
+   * - Cancelled transactions CANNOT be restored
+   * - No cost to the business (transaction won't be presented to credit card companies)
+   * - If invoice module is active, a credit memo will be issued
+   *
+   * @throws {HypayError} When CCode indicates an error (920 = doesn't exist / already committed)
+   *
+   * @example
+   * ```ts
+   * const result = await client.cancelTransaction({ TransId: "5890796" });
+   * console.log(result.CCode); // "0" = success
+   * ```
+   */
+  async cancelTransaction(params) {
+    const allParams = {
+      action: "CancelTrans",
+      ...this.authParams(),
+      TransId: params.TransId
+    };
+    const { raw, params: parsed } = await this.request("CancelTrans", allParams);
+    if (parsed.CCode && parsed.CCode !== "0") {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      TransId: parsed.TransId ?? "",
+      CCode: parsed.CCode ?? "",
+      Hesh: parsed.Hesh,
+      raw,
+      params: parsed
+    };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  REFUND — Refund transactions
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Refund a transaction by its original transaction ID (zikoyAPI).
+   *
+   * **Rules:**
+   * - Refund amount must not exceed the original transaction amount
+   * - Can be done at any stage, even after 23:00
+   * - A credit refund is like a new deal for the credit card company
+   * - Does NOT require a token or the secret refund password
+   *
+   * @throws {HypayError} When CCode indicates an error (33 = amount exceeds original)
+   *
+   * @example
+   * ```ts
+   * const result = await client.refund({
+   *   TransId: "12290620",
+   *   Amount: 10,
+   *   Tash: 1,
+   *   SendHesh: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * console.log(`Refund ID: ${result.Id}`);
+   * ```
+   */
+  async refund(params) {
+    const allParams = {
+      action: "zikoyAPI",
+      ...this.authParams(),
+      ...params
+    };
+    const { raw, params: parsed } = await this.request("zikoyAPI", allParams);
+    if (parsed.CCode && parsed.CCode !== "0") {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      ACode: parsed.ACode,
+      HeshASM: parsed.HeshASM,
+      raw,
+      params: parsed
+    };
+  }
+  /**
+   * Refund a transaction using a token and the secret refund password (PAYout).
+   *
+   * This uses the Soft protocol with the `zPass` parameter.
+   * The refund password is sent to the terminal owner's cell phone and is non-interchangeable.
+   *
+   * @throws {HypayError} When CCode indicates an error
+   *
+   * @example
+   * ```ts
+   * const result = await client.refundByToken({
+   *   CC: "6907500685494032346",
+   *   Tmonth: "04",
+   *   Tyear: "2023",
+   *   Amount: 2,
+   *   Info: "Refund for order 123",
+   *   zPass: "1234",
+   *   Token: true,
+   *   UserId: "000000000",
+   *   ClientName: "Israel",
+   *   SendHesh: true,
+   *   sendemail: true,
+   * });
+   * ```
+   */
+  async refundByToken(params) {
+    return this.soft(params);
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  HK MODULE — Standing Orders / Subscriptions
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Create a subscription (HK / standing order) payment page URL.
+   *
+   * This is a convenience wrapper around `createPaymentPageUrl` with HK-specific params.
+   *
+   * @example
+   * ```ts
+   * const url = await client.createSubscriptionUrl({
+   *   Info: "Monthly subscription",
+   *   Amount: 120,
+   *   HK: true,
+   *   Tash: 999,              // Unlimited payments
+   *   freq: 1,                 // Monthly
+   *   FirstDate: "2025-06-01",
+   *   OnlyOnApprove: true,
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   email: "customer@example.com",
+   *   Coin: Coin.ILS,
+   *   UTF8: true,
+   *   UTF8out: true,
+   *   Sign: true,
+   *   MoreData: true,
+   * });
+   * ```
+   */
+  async createSubscriptionUrl(params) {
+    return this.createPaymentPageUrl(params);
+  }
+  /**
+   * Create a subscription with an initial transaction of a different amount.
+   *
+   * @example
+   * ```ts
+   * const url = await client.createSubscriptionWithInitialPayment({
+   *   Info: "Plan with setup fee",
+   *   Amount: 120,               // Monthly amount
+   *   HK: true,
+   *   Tash: 999,
+   *   freq: 1,
+   *   TashFirstPayment: 50,      // Setup fee
+   *   FirstPaymentTash: 3,       // Charge setup fee for 3 months
+   *   FixTash: true,
+   *   OnlyOnApprove: true,
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   Coin: Coin.ILS,
+   *   UTF8: true,
+   *   UTF8out: true,
+   *   Sign: true,
+   *   MoreData: true,
+   * });
+   * ```
+   */
+  async createSubscriptionWithInitialPayment(params) {
+    return this.createPaymentPageUrl(params);
+  }
+  /**
+   * Change the status of a standing order (HK) agreement.
+   *
+   * @throws {HypayError} When CCode indicates an error (905 = wrong param, 906 = not found)
+   *
+   * @example
+   * ```ts
+   * // Terminate
+   * await client.updateHKStatus({
+   *   HKId: "64239",
+   *   NewStat: HKNewStatus.Terminate,
+   * });
+   *
+   * // Reactivate
+   * await client.updateHKStatus({
+   *   HKId: "64239",
+   *   NewStat: HKNewStatus.Activate,
+   * });
+   * ```
+   */
+  async updateHKStatus(params) {
+    const allParams = {
+      action: "HKStatus",
+      ...this.authParams(),
+      HKId: params.HKId,
+      NewStat: params.NewStat
+    };
+    const { raw, params: parsed } = await this.request("HKStatus", allParams);
+    if (parsed.CCode && parsed.CCode !== "0") {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      HKId: parsed.HKId ?? "",
+      CCode: parsed.CCode ?? "",
+      raw,
+      params: parsed
+    };
+  }
+  /**
+   * Terminate a standing order agreement. Shorthand for `updateHKStatus`.
+   */
+  async terminateSubscription(hkId) {
+    return this.updateHKStatus({ HKId: hkId, NewStat: 1 });
+  }
+  /**
+   * Activate a standing order agreement. Shorthand for `updateHKStatus`.
+   */
+  async activateSubscription(hkId) {
+    return this.updateHKStatus({ HKId: hkId, NewStat: 2 });
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  EZCOUNT INVOICES — Print and manage invoices
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Generate a signed URL for printing/viewing an EzCount invoice.
+   *
+   * Uses a two-step process:
+   * 1. Sign the request with APISign (What=SIGN, ACTION=PrintHesh)
+   * 2. Build the final URL from the signed response
+   *
+   * **Note:** `ACTION=PrintHesh` is uppercase, `action=APISign` is lowercase.
+   *
+   * @example
+   * ```ts
+   * const url = await client.getInvoiceUrl({
+   *   TransId: "55373520",
+   *   type: "EZCOUNT",
+   * });
+   * // Redirect user or fetch the invoice PDF
+   * ```
+   */
+  async getInvoiceUrl(params) {
+    const signParams = {
+      action: "APISign",
+      What: "SIGN",
+      Masof: this.masof,
+      KEY: this.apiKey,
+      PassP: this.passP,
+      ACTION: "PrintHesh",
+      type: params.type
+    };
+    if (params.TransId) signParams.TransId = params.TransId;
+    if (params.asm) signParams.asm = params.asm;
+    if (params.HeshORCopy !== void 0) signParams.HeshORCopy = params.HeshORCopy;
+    const { raw } = await this.request("PrintHesh-SIGN", signParams);
+    return `${this.baseUrl}?${raw}`;
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  OFFLINE INVOICES — Cash, Check, Multi
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Create an invoice for an offline transaction (Cash, Check, or Multi-check).
+   *
+   * Uses the Soft protocol with the `TransType` parameter.
+   *
+   * @throws {HypayError} When CCode indicates an error
+   *
+   * @example
+   * ```ts
+   * // Cash invoice
+   * const result = await client.createOfflineInvoice({
+   *   TransType: "Cash",
+   *   Info: "Cash payment",
+   *   Amount: 200,
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   email: "customer@example.com",
+   *   Pritim: true,
+   *   heshDesc: "[001~Product A~2~50][002~Product B~1~100]",
+   *   SendHesh: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Check invoice
+   * const result = await client.createOfflineInvoice({
+   *   TransType: "Check",
+   *   Info: "Check payment",
+   *   Amount: 200,
+   *   Bank: "10",
+   *   Snif: "912",
+   *   PAN: "1234456",
+   *   CheckNum: "11111111",
+   *   Date: "20250211",
+   *   UserId: "203269535",
+   *   ClientName: "Israel",
+   *   SendHesh: true,
+   *   UTF8: true,
+   *   UTF8out: true,
+   * });
+   * ```
+   */
+  async createOfflineInvoice(params) {
+    const allParams = {
+      action: "soft",
+      ...this.authParams(),
+      ...params
+    };
+    const { raw, params: parsed } = await this.request("soft-offline", allParams);
+    if (parsed.CCode && !isSuccessCode(parsed.CCode)) {
+      throw new HypayError(getErrorMessage(parsed.CCode), parsed.CCode, raw, parsed);
+    }
+    return {
+      Id: parsed.Id ?? "",
+      CCode: parsed.CCode ?? "",
+      Amount: parsed.Amount ?? "",
+      ACode: parsed.ACode ?? "",
+      Fild1: parsed.Fild1,
+      Fild2: parsed.Fild2,
+      Fild3: parsed.Fild3,
+      Hesh: parsed.Hesh,
+      UID: parsed.UID,
+      errMsg: parsed.errMsg,
+      raw,
+      params: parsed
+    };
+  }
+};
+export {
+  ALL_ERROR_CODES,
+  Bank,
+  Brand,
+  Coin,
+  HKNewStatus,
+  HYPAY_ERROR_CODES,
+  HypayClient,
+  HypayError,
+  HypayNetworkError,
+  HypayTimeoutError,
+  Issuer,
+  PageLang,
+  SHVA_ERROR_CODES,
+  SpecialCardType,
+  TashType,
+  buildItemsString,
+  calculateItemsTotal,
+  getErrorMessage,
+  isHypayError,
+  isShvaError,
+  isSuccessCode,
+  isTestMasof,
+  isValidEmail,
+  isValidIsraeliId,
+  isValidMasof,
+  isValidToken,
+  parsePaymentPageResponse,
+  parseQueryString,
+  parseRedirectUrl,
+  parseTokef,
+  serializeParams,
+  toQueryString
+};