@hypay/typescript-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1363 @@
+interface HypayConfig {
+    /** Terminal number in Hypay (10 digits). Starts with 00100 for test terminals. */
+    masof: string;
+    /** API key from terminal settings */
+    apiKey: string;
+    /** Password authentication value */
+    passP?: string;
+    /** Base URL override (defaults to https://pay.hyp.co.il/p/) */
+    baseUrl?: string;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /**
+     * Custom fetch implementation. Defaults to globalThis.fetch.
+     * Useful for injecting a custom HTTP client (e.g., undici, node-fetch, or test mocks).
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Lifecycle hooks for logging, metrics, and debugging.
+     */
+    hooks?: HypayHooks;
+}
+interface HypayHooks {
+    /** Called before every HTTP request */
+    onRequest?: (context: RequestContext) => void | Promise<void>;
+    /** Called after every HTTP response */
+    onResponse?: (context: ResponseContext) => void | Promise<void>;
+    /** Called when an error occurs */
+    onError?: (error: HypayError, context: RequestContext) => void | Promise<void>;
+}
+interface RequestContext {
+    /** The action being performed (e.g., "soft", "getToken", "APISign") */
+    action: string;
+    /** HTTP method used */
+    method: "GET" | "POST";
+    /** Full request URL (for GET) or base URL (for POST) */
+    url: string;
+    /** Request parameters (serialized) */
+    params: Record<string, string>;
+}
+interface ResponseContext extends RequestContext {
+    /** HTTP status code */
+    statusCode: number;
+    /** Raw response text */
+    raw: string;
+    /** Parsed response parameters */
+    parsedParams: Record<string, string>;
+    /** Request duration in milliseconds */
+    durationMs: number;
+}
+declare enum Coin {
+    ILS = 1,
+    USD = 2,
+    EUR = 3,
+    GBP = 4
+}
+declare enum PageLang {
+    HEB = "HEB",
+    ENG = "ENG"
+}
+declare enum TashType {
+    Regular = 1,
+    Credit = 6
+}
+declare enum Bank {
+    Isracard = 1,
+    VisaCal = 2,
+    Diners = 3,
+    Amex = 4,
+    MAX = 6,
+    BIT = 99
+}
+declare enum Brand {
+    PL = 0,
+    MasterCard = 1,
+    Visa = 2,
+    Diners = 3,
+    Amex = 4,
+    Isracard = 5
+}
+declare enum Issuer {
+    Foreign = 0,
+    Isracard = 1,
+    VisaCal = 2,
+    JCB = 5,
+    MAX = 6
+}
+declare enum HKNewStatus {
+    Terminate = 1,
+    Activate = 2
+}
+declare enum SpecialCardType {
+    Default = "00",
+    Immediate = "01",
+    Club = "70",
+    PetrolCard = "03",
+    DualCard = "04",
+    DualClub = "74",
+    PetrolClub = "75",
+    Chargeable = "06",
+    Petrol = "08",
+    Tourist = "99"
+}
+interface ClientData {
+    /** Client ID (9 digits, send 000000000 if not required) */
+    UserId: string;
+    /** Client first name */
+    ClientName: string;
+    /** Client last name */
+    ClientLName?: string;
+    /** Street name and house number */
+    street?: string;
+    /** City name */
+    city?: string;
+    /** Zip code */
+    zip?: string;
+    /** Phone number */
+    phone?: string;
+    /** Cell number */
+    cell?: string;
+    /** Client email */
+    email?: string;
+}
+interface InvoiceParams {
+    /** Send invoice in email */
+    SendHesh?: boolean;
+    /** Invoice description or items string */
+    heshDesc?: string;
+    /** Invoice description contains items */
+    Pritim?: boolean;
+    /** Block transaction if item totals don't match Amount */
+    blockItemValidation?: boolean;
+    /** Invoice language: "he" or "en" */
+    "EZ.lang"?: string;
+    /** Additional text in email body */
+    "EZ.email_text"?: string;
+    /** Additional text in invoice body */
+    "EZ.comment"?: string;
+    /** CC emails (comma-separated, max 10) */
+    "EZ.cc_emails"?: string;
+    /** Invoice VAT rate (default 0.18, 1 = 1.00, 0 = 0.00) */
+    "EZ.vat"?: number;
+    /** Additional description in invoice header */
+    "EZ.description"?: string;
+    /** Customer company number/ID (BN Number). Required by law when > 5,000 ILS */
+    "EZ.customer_crn"?: string;
+    /** Create original documents in English/foreign currency (default 0) */
+    "EZ.create_org_as_foreign"?: 0 | 1;
+}
+interface InvoiceItem {
+    /** Item code for bookkeeping (use "0" if unavailable) */
+    code: string;
+    /** Description of the item */
+    description: string;
+    /** Quantity */
+    quantity: number;
+    /** Price per item (including VAT) */
+    price: number;
+}
+interface PayPageParams extends ClientData, InvoiceParams {
+    /** Transaction information (displayed in reports) */
+    Info: string;
+    /** Purchase amount. If omitted, the client will be asked to type an amount (donations). */
+    Amount?: number;
+    /** Internal field for the website owner (returned to success page, not saved in Hypay) */
+    Order?: string;
+    /** Max number of payments selectable by the customer */
+    Tash?: number;
+    /** Payment type: regular (1) or credit (6) */
+    tashType?: TashType;
+    /** Fix payments to a fixed number (requires Tash) */
+    FixTash?: boolean;
+    /** Send payment confirmation by email */
+    sendemail?: boolean;
+    /** Different first payment amount */
+    TashFirstPayment?: number;
+    /** Return more data on the transaction (Bank, Brand, Issuer, L4digit, etc.) */
+    MoreData?: boolean;
+    /** Set 20-minute timeout on payment page (recommended) */
+    pageTimeOut?: boolean;
+    /** Payment page language */
+    PageLang?: PageLang;
+    /** Template number (1-15+) */
+    tmp?: number;
+    /** Billing currency */
+    Coin?: Coin;
+    /** Delayed transaction - code 800 */
+    Postpone?: boolean;
+    /**
+     * Preserving line of credit.
+     * - `true` = J5: preserve credit line for 3 days without cancel option
+     * - `"J2"` = check card credibility without checking credit line
+     */
+    J5?: boolean | "J2";
+    /** Show Tash text in English */
+    ShowEngTashText?: boolean;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+    /** Sign sent parameters in the response */
+    Sign?: boolean;
+    /** Hide payment buttons (Apple Pay, Google Pay, Bit) on the payment page */
+    hideBtns?: boolean;
+}
+interface PayPageSubscriptionParams extends PayPageParams {
+    /** Pay Page in HK (standing order/subscription) mode */
+    HK: true;
+    /** Payment frequency in months */
+    freq?: number;
+    /** First payment date (YYYY-MM-DD) */
+    FirstDate?: string;
+    /** Number of payments (999 for unlimited) */
+    Tash: number;
+    /** Only close deal if first payment is approved */
+    OnlyOnApprove?: boolean;
+    /** Amount of a single initial transaction */
+    TashFirstPayment?: number;
+    /** Number of charges for the initial single transaction */
+    FirstPaymentTash?: number;
+}
+interface APISignResponse {
+    /** The full signed query string including the signature parameter */
+    raw: string;
+    /** The signature value */
+    signature: string;
+    /** Parsed key-value pairs from the response */
+    params: Record<string, string>;
+}
+interface VerifyParams {
+    /** Transaction ID */
+    Id: string;
+    /** Credit card company answer code */
+    CCode: string;
+    /** Amount charged */
+    Amount: string;
+    /** Confirmation code */
+    ACode: string;
+    /** Internal field */
+    Order?: string;
+    /** Client first and last name */
+    Fild1?: string;
+    /** Client email */
+    Fild2?: string;
+    /** Client phone */
+    Fild3?: string;
+    /** Signature from the success page */
+    Sign?: string;
+    /** Additional MoreData fields */
+    Bank?: string;
+    Payments?: string;
+    UserId?: string;
+    Brand?: string;
+    Issuer?: string;
+    L4digit?: string;
+    street?: string;
+    city?: string;
+    zip?: string;
+    cell?: string;
+    Coin?: string;
+    Tmonth?: string;
+    Tyear?: string;
+    Hesh?: string;
+    errMsg?: string;
+    /** Catch-all for any additional parameters */
+    [key: string]: string | undefined;
+}
+interface VerifyResponse {
+    /** Whether the verification succeeded (CCode === "0") */
+    verified: boolean;
+    /** CCode from the verify response */
+    CCode: string;
+    /** Raw response string */
+    raw: string;
+    /** Parsed parameters */
+    params: Record<string, string>;
+}
+/** Standard Soft request with token/credit card details */
+interface SoftTokenParams extends ClientData, InvoiceParams {
+    /** Token number (19 digits) or credit card number */
+    CC: string;
+    /** Month credit card validity (MM) */
+    Tmonth: string;
+    /** Year credit card validity (YYYY) */
+    Tyear: string;
+    /** Transaction information */
+    Info: string;
+    /** Purchase amount */
+    Amount: number;
+    /** Number of installments */
+    Tash?: number;
+    /** Payment type */
+    tashType?: TashType;
+    /** Different first payment amount */
+    TashFirstPayment?: number;
+    /** Billing currency */
+    Coin?: Coin;
+    /** Delayed transaction */
+    Postpone?: boolean;
+    /** Making a deal with token (required when CC is a token) */
+    Token?: boolean;
+    /** Terminal owner of the token (requires special authorization) */
+    tOwner?: string;
+    /** Preserving line of credit */
+    J5?: boolean | "J2";
+    /** Confirmation number for reuse */
+    AuthNum?: string;
+    /** CVV (not saved, required if terminal demands it) */
+    cvv?: string;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+    /** Return more data */
+    MoreData?: boolean;
+    /** Send payment confirmation by email */
+    sendemail?: boolean;
+    /** Send invoice by SMS (requires SMS package) */
+    sendHeshSMS?: boolean;
+    /** Free text fields (returned, not saved in Hypay) */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /** Internal field for website owner (not saved in Hypay) */
+    Order?: string;
+    /** Refund password (for PAYout refund transactions) */
+    zPass?: string;
+}
+/** Soft request with WalletToken (Apple Pay / Google Pay) - replaces CC, Tmonth, Tyear */
+interface SoftWalletParams extends ClientData, InvoiceParams {
+    /** Wallet token JSON from Apple Pay or Google Pay */
+    WalletToken: string;
+    /** Transaction information */
+    Info: string;
+    /** Purchase amount */
+    Amount: number;
+    /** Number of installments */
+    Tash?: number;
+    /** Payment type */
+    tashType?: TashType;
+    /** Different first payment amount */
+    TashFirstPayment?: number;
+    /** Billing currency */
+    Coin?: Coin;
+    /** Delayed transaction */
+    Postpone?: boolean;
+    /** Preserving line of credit */
+    J5?: boolean | "J2";
+    /** CVV */
+    cvv?: string;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+    /** Return more data */
+    MoreData?: boolean;
+    /** Send payment confirmation by email */
+    sendemail?: boolean;
+    /** Send invoice by SMS */
+    sendHeshSMS?: boolean;
+    /** Free text fields */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /** Internal field */
+    Order?: string;
+}
+/** Union type: either token-based or wallet-based soft request */
+type SoftParams = SoftTokenParams | SoftWalletParams;
+interface SoftResponse {
+    /** Transaction ID in Hypay */
+    Id: string;
+    /** Credit card company answer (0 = success) */
+    CCode: string;
+    /** Amount actually charged */
+    Amount: string;
+    /** Confirmation code from credit card company */
+    ACode: string;
+    /** Free text fields */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /** Invoice number (returns "EZ" for EzCount) */
+    Hesh?: string;
+    /** UID for binding between transaction steps (e.g., J5 charge) */
+    UID?: string;
+    /** Error message from credit card company */
+    errMsg?: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters (includes MoreData fields when MoreData=True) */
+    params: Record<string, string>;
+}
+/** All additional fields returned when MoreData=True in Soft/Pay responses */
+interface MoreDataFields {
+    /** Acquirer: Isracard=1, VisaCal=2, Diners=3, Amex=4, MAX=6, BIT=99 */
+    Bank?: string;
+    /** Transaction type (Contactless, EMV, ApplePay, GooglePay, etc.) */
+    TransType?: string;
+    /** Number of payments charged */
+    Payments?: string;
+    /** Number of regular payments (excluding first) */
+    noKPayments?: string;
+    /** First payment amount */
+    nFirstPayment?: string;
+    /** First payment calculated */
+    firstPayment?: string;
+    /** Client ID */
+    UserId?: string;
+    /** Brand: PL=0, MasterCard=1, Visa=2, Diners=3, Amex=4, Isracard=5 */
+    Brand?: string;
+    /** Issuer: Isracard=1, VisaCal=2, JCB=5, MAX=6, Foreign=0 */
+    Issuer?: string;
+    /** Last 4 digits of credit card */
+    L4digit?: string;
+    /** Client first name */
+    firstname?: string;
+    /** Client last name */
+    lastname?: string;
+    /** Transaction info */
+    info?: string;
+    /** Street */
+    street?: string;
+    /** City */
+    city?: string;
+    /** Zip */
+    zip?: string;
+    /** Cell */
+    cell?: string;
+    /** Email */
+    email?: string;
+    /** Currency: 1=ILS, 2=USD, 3=EUR, 4=GBP */
+    Coin?: string;
+    /** Month credit card validity (MM) */
+    Tmonth?: string;
+    /** Year credit card validity (YYYY) */
+    Tyear?: string;
+    /** Invoice number */
+    Hesh?: string;
+    /** UID for future bindings */
+    UID?: string;
+    /** Special card type (00=default, 01=Immediate, 70=Club, etc.) */
+    spType?: string;
+    /** BIN - first 6 digits of payment card */
+    bincard?: string;
+    /** Card name (e.g., "(????) Cal") */
+    CardName?: string;
+    /** Payment type used */
+    tashType?: string;
+    /** TashFirstPayment returned */
+    TashFirstPayment?: string;
+}
+interface GetTokenParams {
+    /** Transaction number from a previous Pay/Soft transaction */
+    TransId: string;
+    /** Free text fields (returned, not saved) */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /**
+     * Allow token from invalid transaction status.
+     * Must be True to get token from transactions with non-standard statuses.
+     */
+    allowFalse?: boolean;
+}
+interface GetTokenResponse {
+    /** Transaction number */
+    Id: string;
+    /** Status code (0 = success) */
+    CCode: string;
+    /** Token number (19 digits) */
+    Token: string;
+    /** Credit card validity in YYMM format (save for future use) */
+    Tokef: string;
+    /** Parsed month from Tokef (MM) - convenience field */
+    Tmonth: string;
+    /** Parsed year from Tokef (YYYY) - convenience field */
+    Tyear: string;
+    /** Free text fields */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters */
+    params: Record<string, string>;
+}
+interface CommitTransParams {
+    /** Transaction ID to commit */
+    TransId: string;
+    /** Send invoice in email */
+    SendHesh?: boolean;
+    /** Invoice description */
+    heshDesc?: string;
+    /** Invoice contains items */
+    Pritim?: boolean;
+    /** Send invoice by SMS */
+    sendHeshSMS?: boolean;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+}
+interface CommitTransResponse {
+    /** Transaction ID */
+    Id: string;
+    /** Status code (0 = success, 250 = doesn't exist or already committed) */
+    CCode: string;
+    /** Invoice number created */
+    HeshASM?: string;
+    /** Free text fields */
+    Fild1?: string;
+    Fild2?: string;
+    Fild3?: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters */
+    params: Record<string, string>;
+}
+interface CancelTransParams {
+    /** Transaction ID to cancel */
+    TransId: string;
+}
+interface CancelTransResponse {
+    /** Transaction ID */
+    TransId: string;
+    /** Status code (0 = success, 920 = doesn't exist or already committed) */
+    CCode: string;
+    /** Invoice number (returns "EZ" for EzCount) */
+    Hesh?: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters */
+    params: Record<string, string>;
+}
+interface RefundParams {
+    /** Original transaction ID to refund */
+    TransId: string;
+    /** Refund amount (must not exceed original transaction amount) */
+    Amount: number;
+    /** Number of refund payments */
+    Tash?: number;
+    /** Send credit invoice in email */
+    SendHesh?: boolean;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+}
+interface RefundResponse {
+    /** New refund transaction ID in Hypay */
+    Id: string;
+    /** Status code (0 = success, 33 = amount exceeds original) */
+    CCode: string;
+    /** Confirmation code from credit card company */
+    ACode?: string;
+    /** Invoice number created */
+    HeshASM?: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters */
+    params: Record<string, string>;
+}
+interface RefundByTokenParams extends ClientData, InvoiceParams {
+    /** Token number (19 digits) */
+    CC: string;
+    /** Month credit card validity (MM) */
+    Tmonth: string;
+    /** Year credit card validity (YYYY) */
+    Tyear: string;
+    /** Refund amount (positive number) */
+    Amount: number;
+    /** Transaction information */
+    Info: string;
+    /**
+     * Secret refund password (sent to terminal owner's cell phone).
+     * Non-interchangeable.
+     */
+    zPass: string;
+    /** Making a deal with token */
+    Token?: boolean;
+    /** Internal field */
+    Order?: string;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+    /** CVV (if required by terminal) */
+    cvv?: string;
+    /** Send payment confirmation by email */
+    sendemail?: boolean;
+}
+interface HKStatusParams {
+    /** Agreement number */
+    HKId: string;
+    /** New status: 1 = Terminate, 2 = Activate */
+    NewStat: HKNewStatus;
+}
+interface HKStatusResponse {
+    /** Agreement number */
+    HKId: string;
+    /** Status code (0 = success, 905 = wrong param, 906 = agreement doesn't exist) */
+    CCode: string;
+    /** Raw response string */
+    raw: string;
+    /** All parsed parameters */
+    params: Record<string, string>;
+}
+interface PrintInvoiceParams {
+    /** Transaction ID of the wanted invoice (if passed, asm is not required) */
+    TransId?: string;
+    /** Invoice ID for printing */
+    asm?: string;
+    /**
+     * Invoice type:
+     * - `HTML`: Returns old-system invoice in HTML format
+     * - `PDF`: Returns digitally signed PDF (may take up to 20 min from transaction)
+     * - `EZCOUNT`: New EZCount system invoice
+     * - `NEW`: Prints all unprinted invoices in HTML
+     */
+    type: "HTML" | "PDF" | "EZCOUNT" | "NEW";
+    /** True = authentic copy ("נאמן למקור"), False = copy ("העתק") */
+    HeshORCopy?: boolean;
+}
+interface OfflineInvoiceBaseParams extends ClientData, InvoiceParams {
+    /** Transaction information */
+    Info: string;
+    /** Total amount */
+    Amount: number;
+    /** Data encoded in UTF-8 */
+    UTF8?: boolean;
+    /** Return answer in UTF-8 */
+    UTF8out?: boolean;
+}
+interface CashInvoiceParams extends OfflineInvoiceBaseParams {
+    /** Transaction type */
+    TransType: "Cash";
+}
+interface CheckInvoiceParams extends OfflineInvoiceBaseParams {
+    /** Transaction type */
+    TransType: "Check";
+    /** Bank number */
+    Bank: string;
+    /** Branch number */
+    Snif: string;
+    /** Account number */
+    PAN: string;
+    /** Check number */
+    CheckNum: string;
+    /** Check date (YYYYMMDD) */
+    Date: string;
+}
+interface MultiCheckInvoiceParams extends OfflineInvoiceBaseParams {
+    /** Transaction type */
+    TransType: "Multi";
+    /** Bank numbers (comma-separated, use space for cash entries) */
+    Bank: string;
+    /** Branch numbers (comma-separated) */
+    Snif: string;
+    /** Account numbers (comma-separated) */
+    PAN: string;
+    /** Check numbers (comma-separated) */
+    CheckNum: string;
+    /** Check dates (comma-separated, YYYYMMDD format) */
+    Date: string;
+    /** Amounts per check (comma-separated) */
+    Amount: number;
+}
+type OfflineInvoiceParams = CashInvoiceParams | CheckInvoiceParams | MultiCheckInvoiceParams;
+interface PaymentPageResponse {
+    /** Transaction ID in Hypay */
+    Id: string;
+    /** Credit card company answer (0 = success, 902 = verification error) */
+    CCode: string;
+    /** Amount charged */
+    Amount: string;
+    /** Confirmation code */
+    ACode: string;
+    /** Internal field (returned, not saved) */
+    Order?: string;
+    /** Client first and last name */
+    Fild1?: string;
+    /** Client email */
+    Fild2?: string;
+    /** Client phone */
+    Fild3?: string;
+    /** Signature (only when Sign=True was sent) */
+    Sign?: string;
+    /** HK agreement ID (only for subscription payments) */
+    HKId?: string;
+    /** Error message */
+    errMsg?: string;
+    /** All MoreData fields (when MoreData=True was sent) */
+    Bank?: string;
+    TransType?: string;
+    Payments?: string;
+    UserId?: string;
+    Brand?: string;
+    Issuer?: string;
+    L4digit?: string;
+    street?: string;
+    city?: string;
+    zip?: string;
+    cell?: string;
+    Coin?: string;
+    Tmonth?: string;
+    Tyear?: string;
+    Hesh?: string;
+    UID?: string;
+    spType?: string;
+    bincard?: string;
+    /** Catch-all */
+    [key: string]: string | undefined;
+}
+interface J5ChargeParams {
+    /** UID from the original J5 transaction response (MoreData=True required) */
+    "inputObj.originalUid": string;
+    /**
+     * Amount to charge in agorot (100 agorot = 1 ILS).
+     * Must be equal to or less than the original J5 transaction amount.
+     * Example: 500 = 5 ILS
+     */
+    "inputObj.originalAmount": number;
+    /** ACode from the original J5 transaction response */
+    AuthNum: string;
+    /** Static SHVA parameter, always 7 */
+    "inputObj.authorizationCodeManpik": 7;
+}
+declare class HypayError extends Error {
+    /** CCode error number */
+    readonly code: string;
+    /** Full raw response */
+    readonly raw: string;
+    /** All parsed response parameters */
+    readonly params: Record<string, string>;
+    constructor(message: string, code: string, raw: string, params: Record<string, string>);
+}
+declare class HypayNetworkError extends Error {
+    /** The original cause */
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+declare class HypayTimeoutError extends Error {
+    /** Timeout in milliseconds */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+/**
+ * The main client class for interacting with the Hypay API.
+ *
+ * @example
+ * ```ts
+ * const client = new HypayClient({
+ *   masof: "your-masof",
+ *   apiKey: "your-api-key",
+ *   passP: "your-passp",
+ * });
+ * ```
+ */
+declare class HypayClient {
+    private readonly masof;
+    private readonly apiKey;
+    private readonly passP?;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchFn;
+    private readonly hooks;
+    constructor(config: HypayConfig);
+    /**
+     * Make a GET request to the Hypay API.
+     * All API calls use GET by default, which is the most common method for Hypay.
+     */
+    private requestGet;
+    /**
+     * Make a POST request to the Hypay API.
+     * Use for actions that send large payloads (e.g., WalletToken with Apple Pay).
+     */
+    private requestPost;
+    /**
+     * Unified request method. Defaults to GET, uses POST for wallet/large payloads.
+     */
+    private request;
+    private authParams;
+    private throwIfError;
+    /**
+     * **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);
+     * ```
+     */
+    sign(params: PayPageParams | PayPageSubscriptionParams): Promise<APISignResponse>;
+    /**
+     * **Step 2** — Build the full payment page URL from a signed query string.
+     *
+     * @param signedQueryString - The raw result from `sign()`.
+     */
+    buildPaymentPageUrl(signedQueryString: string): string;
+    /**
+     * **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`
+     * ```
+     */
+    createPaymentPageUrl(params: PayPageParams | PayPageSubscriptionParams): Promise<string>;
+    /**
+     * **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
+     * }
+     * ```
+     */
+    verify(params: VerifyParams): Promise<VerifyResponse>;
+    /**
+     * 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 *\/ }
+     * ```
+     */
+    verifyRedirectUrl(redirectUrl: string): Promise<VerifyResponse>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    soft(params: SoftParams): Promise<SoftResponse>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    getToken(params: GetTokenParams): Promise<GetTokenResponse>;
+    /**
+     * 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,
+     *   }
+     * );
+     * ```
+     */
+    chargeJ5(tokenParams: SoftTokenParams, j5Params: J5ChargeParams): Promise<SoftResponse>;
+    /**
+     * 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
+     * ```
+     */
+    commitTransaction(params: CommitTransParams): Promise<CommitTransResponse>;
+    /**
+     * 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
+     * ```
+     */
+    cancelTransaction(params: CancelTransParams): Promise<CancelTransResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    refund(params: RefundParams): Promise<RefundResponse>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    refundByToken(params: RefundByTokenParams): Promise<SoftResponse>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    createSubscriptionUrl(params: PayPageSubscriptionParams): Promise<string>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    createSubscriptionWithInitialPayment(params: PayPageSubscriptionParams): Promise<string>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    updateHKStatus(params: HKStatusParams): Promise<HKStatusResponse>;
+    /**
+     * Terminate a standing order agreement. Shorthand for `updateHKStatus`.
+     */
+    terminateSubscription(hkId: string): Promise<HKStatusResponse>;
+    /**
+     * Activate a standing order agreement. Shorthand for `updateHKStatus`.
+     */
+    activateSubscription(hkId: string): Promise<HKStatusResponse>;
+    /**
+     * 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
+     * ```
+     */
+    getInvoiceUrl(params: PrintInvoiceParams): Promise<string>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    createOfflineInvoice(params: OfflineInvoiceParams): Promise<SoftResponse>;
+}
+
+/**
+ * Parse a URL-encoded query string (key=value&key2=value2) into a Record.
+ * Handles edge cases: empty strings, missing values, encoded characters.
+ */
+declare function parseQueryString(qs: string): Record<string, string>;
+/**
+ * Convert a Record to a URL-encoded query string.
+ * Skips undefined values.
+ */
+declare function toQueryString(params: Record<string, string | number | boolean | undefined>): string;
+/**
+ * Convert boolean values to "True"/"False" strings as expected by the Hypay API.
+ * Passes through strings and numbers unchanged. Filters undefined.
+ */
+declare function serializeParams(params: Record<string, unknown>): Record<string, string | number | boolean | undefined>;
+/**
+ * Parse a success/failure page redirect URL into its query parameters.
+ *
+ * @example
+ * const params = parseRedirectUrl(
+ *   "https://example.com/success?Id=123&CCode=0&Amount=10&ACode=0012345"
+ * );
+ * // { Id: "123", CCode: "0", Amount: "10", ACode: "0012345" }
+ */
+declare function parseRedirectUrl(url: string): Record<string, string>;
+/**
+ * Parse a success/failure page redirect URL into a typed PaymentPageResponse.
+ *
+ * @example
+ * const response = parsePaymentPageResponse(
+ *   "https://example.com/success?Id=123&CCode=0&Amount=10&ACode=0012345&Fild1=John"
+ * );
+ * console.log(response.Id); // "123"
+ * console.log(response.CCode); // "0"
+ */
+declare function parsePaymentPageResponse(url: string): PaymentPageResponse;
+/**
+ * Parse a Tokef value (YYMM format) into separate Tmonth and Tyear values
+ * as required by the Soft protocol.
+ *
+ * @example
+ * parseTokef("2504"); // { Tmonth: "04", Tyear: "2025" }
+ * parseTokef("3112"); // { Tmonth: "12", Tyear: "2031" }
+ */
+declare function parseTokef(tokef: string): {
+    Tmonth: string;
+    Tyear: string;
+};
+/**
+ * Build the heshDesc items string for EzCount invoices.
+ *
+ * Each item is formatted as: [code~description~quantity~price]
+ *
+ * **Important:** The total (sum of quantity * price for each item) must match
+ * the Amount parameter, otherwise CCode=16 is returned. If blockItemValidation=True
+ * is set, CCode=400 is returned instead.
+ *
+ * @example
+ * buildItemsString([
+ *   { code: "0", description: "Item 1", quantity: 1, price: 8 },
+ *   { code: "0", description: "Item 2", quantity: 2, price: 1 },
+ * ]);
+ * // "[0~Item 1~1~8][0~Item 2~2~1]"  (total = 10)
+ */
+declare function buildItemsString(items: InvoiceItem[]): string;
+/**
+ * Calculate the total amount from a list of invoice items.
+ * Useful for validating that items match the Amount parameter before sending.
+ *
+ * @example
+ * calculateItemsTotal([
+ *   { code: "0", description: "Item 1", quantity: 1, price: 8 },
+ *   { code: "0", description: "Item 2", quantity: 2, price: 1 },
+ * ]);
+ * // 10
+ */
+declare function calculateItemsTotal(items: InvoiceItem[]): number;
+/**
+ * Validate a Masof (terminal number) format.
+ * Must be exactly 10 digits. Starts with 00100 for test terminals.
+ */
+declare function isValidMasof(masof: string): boolean;
+/**
+ * Check if a Masof is a test terminal (starts with 00100).
+ */
+declare function isTestMasof(masof: string): boolean;
+/**
+ * Validate a token format. Must be exactly 19 digits.
+ */
+declare function isValidToken(token: string): boolean;
+/**
+ * Validate an email format (basic check).
+ * Note: The Hypay API does NOT validate email format.
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Validate Israeli ID number (Teudat Zehut) using the Luhn-like algorithm.
+ * Returns true for valid IDs, or for the special test values (000000000, 890108558).
+ */
+declare function isValidIsraeliId(id: string): boolean;
+
+/**
+ * Mapping of Hypay-specific error codes (201-999) to their English descriptions.
+ */
+declare const HYPAY_ERROR_CODES: Record<string, string>;
+/**
+ * Shva EMV error codes (000-777).
+ * Errors 0-200 are from Shva (the Israeli credit card clearing house).
+ */
+declare const SHVA_ERROR_CODES: Record<string, string>;
+/**
+ * Combined error codes lookup (Hypay + Shva).
+ */
+declare const ALL_ERROR_CODES: Record<string, string>;
+/**
+ * Look up the description for a CCode value from all known error codes.
+ * Returns the description if known, or a generic message.
+ */
+declare function getErrorMessage(ccode: string): string;
+/**
+ * Check whether a CCode indicates a successful/valid response.
+ * Codes 0, 600, 700, and 800 are considered non-error statuses:
+ * - 0: Approved
+ * - 600: Checking card number (J2)
+ * - 700: Approved without charge (J5)
+ * - 800: Postpone transaction
+ */
+declare function isSuccessCode(ccode: string): boolean;
+/**
+ * Check whether a CCode is a Shva error (0-200 range, excluding success codes).
+ */
+declare function isShvaError(ccode: string): boolean;
+/**
+ * Check whether a CCode is a Hypay server error (201-999 range, excluding valid codes).
+ */
+declare function isHypayError(ccode: string): boolean;
+
+export { ALL_ERROR_CODES, type APISignResponse, Bank, Brand, type CancelTransParams, type CancelTransResponse, type CashInvoiceParams, type CheckInvoiceParams, type ClientData, Coin, type CommitTransParams, type CommitTransResponse, type GetTokenParams, type GetTokenResponse, HKNewStatus, type HKStatusParams, type HKStatusResponse, HYPAY_ERROR_CODES, HypayClient, type HypayConfig, HypayError, type HypayHooks, HypayNetworkError, HypayTimeoutError, type InvoiceItem, type InvoiceParams, Issuer, type J5ChargeParams, type MoreDataFields, type MultiCheckInvoiceParams, type OfflineInvoiceBaseParams, type OfflineInvoiceParams, PageLang, type PayPageParams, type PayPageSubscriptionParams, type PaymentPageResponse, type PrintInvoiceParams, type RefundByTokenParams, type RefundParams, type RefundResponse, type RequestContext, type ResponseContext, SHVA_ERROR_CODES, type SoftParams, type SoftResponse, type SoftTokenParams, type SoftWalletParams, SpecialCardType, TashType, type VerifyParams, type VerifyResponse, buildItemsString, calculateItemsTotal, getErrorMessage, isHypayError, isShvaError, isSuccessCode, isTestMasof, isValidEmail, isValidIsraeliId, isValidMasof, isValidToken, parsePaymentPageResponse, parseQueryString, parseRedirectUrl, parseTokef, serializeParams, toQueryString };