@tapsilat/tapsilat-js 2026.10.20 → 2026.10.26

package/dist/index.cjs

@@ -20,6 +20,8 @@ class TapsilatError extends Error {
     apiStatus;
     /** Per-field validation messages from the API response body */
     errors;
+    /** Whether the API error says the request can be retried, as Elements errors do */
+    retryable;
     /** Raw API response body */
     rawBody;
     /**
@@ -55,6 +57,7 @@ class TapsilatError extends Error {
         error.apiCode = apiError.apiCode;
         error.apiStatus = apiError.apiStatus;
         error.errors = apiError.errors;
+        error.retryable = apiError.retryable;
         error.rawBody = apiError.rawBody;
         return error;
     }
@@ -521,6 +524,8 @@ class HttpClient {
         const errors = body.errors && typeof body.errors === "object" && !Array.isArray(body.errors)
             ? body.errors
             : undefined;
+        const nested = this.nestedError(body);
+        const apiCode = body.code !== undefined && body.code !== null ? body.code : nested?.code;
         return {
             success: false,
             status: response.status,
@@ -529,13 +534,14 @@ class HttpClient {
                 code: error.code,
                 details: error.details,
                 statusCode: response.status,
-                apiCode: body.code !== undefined && body.code !== null
-                    ? String(body.code)
+                apiCode: apiCode !== undefined && apiCode !== null
+                    ? String(apiCode)
                     : undefined,
                 apiStatus: body.status !== undefined && body.status !== null
                     ? String(body.status)
                     : undefined,
                 errors,
+                retryable: typeof nested?.retryable === "boolean" ? nested.retryable : undefined,
                 rawBody,
             },
         };
@@ -593,10 +599,28 @@ class HttpClient {
         }
         if (data && typeof data === "object") {
             const obj = data;
-            return (obj.message || obj.error || obj.detail);
+            const nested = this.nestedError(obj);
+            return (obj.message || (nested ? nested.message : obj.error) || obj.detail);
         }
         return undefined;
     }
+    /**
+     * @category HTTP Client Internals
+     * @summary Returns the error object of a nested error body
+     * @description Elements routes answer with {"error": {"code", "message", "retryable"}} instead of top-level fields
+     *
+     * @param data - The parsed response data
+     * @returns The nested error object, or undefined when `error` is not an object
+     */
+    nestedError(data) {
+        if (!data || typeof data !== "object") {
+            return undefined;
+        }
+        const error = data.error;
+        return error && typeof error === "object" && !Array.isArray(error)
+            ? error
+            : undefined;
+    }
     /**
      * @category HTTP Client Internals
      * @summary Extracts validation details from error response
@@ -1883,30 +1907,129 @@ class CurrencyResolver {
     }
 }
 
+/** What a redacted secret prints as */
+const REDACTED = "[redacted]";
+/** The hook Node.js calls when console.log or util.inspect prints an object */
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+/**
+ * Makes console.log and util.inspect print an object's `client_secret` as "[redacted]"
+ *
+ * @summary Keep a client secret out of logs
+ * @description
+ * Adds a non-enumerable inspect hook to the object itself, so JSON.stringify, property access and
+ * Object.keys still see the real secret. A copy made with spread or structuredClone does not keep
+ * the hook.
+ *
+ * @param value - A response object that carries `client_secret`
+ * @returns The same object
+ */
+const redactClientSecret = (value) => {
+    if (value && typeof value === "object" && "client_secret" in value) {
+        Object.defineProperty(value, INSPECT, {
+            value: function () {
+                return { ...this, client_secret: REDACTED };
+            },
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return value;
+};
+
+/** The header that carries the signature of every callback Tapsilat sends */
+const WEBHOOK_SIGNATURE_HEADER = "Tapsilat-Signature";
+/** How many seconds a callback's signature timestamp may differ from the current time */
+const WEBHOOK_TOLERANCE = 300;
+const LEGACY_PREFIX = "sha256=";
+const hmacHex = (secret, ...parts) => {
+    const hmac = crypto.createHmac("sha256", secret);
+    for (const part of parts) {
+        hmac.update(part);
+    }
+    return hmac.digest("hex");
+};
+// Compare in constant time so the signature cannot be guessed byte by byte
+const safeEqual = (expected, candidate) => {
+    const a = Buffer.from(expected);
+    const b = Buffer.from(candidate);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+const checkSeconds = (value, name) => {
+    if (value !== undefined && (typeof value !== "number" || Number.isNaN(value))) {
+        throw new TapsilatValidationError(`Webhook ${name} must be a number of seconds`);
+    }
+    return value;
+};
 // WEBHOOK SIGNATURE VERIFICATION
-// Summary: Security verification of webhook payloads using HMAC-SHA256
-// Description: Computes expected signature from payload and secret, compares with provided signature
+// Summary: Verify the Tapsilat-Signature header of a callback
+// Description: Checks the timestamped HMAC-SHA256 that Tapsilat signs every callback with
 /**
- * Verifies HMAC-SHA256 signature for webhook security
+ * Verifies the Tapsilat-Signature header of a callback against the organization's webhook secret
  *
- * @summary Security verification of webhook payloads using HMAC-SHA256
- * @description Computes expected signature from payload and secret, compares with provided signature
+ * @summary Verify the Tapsilat-Signature header of a callback
+ * @description
+ * Tapsilat sends "t=<unix timestamp>,v1=<hex HMAC-SHA256 of '<timestamp>.<raw body>'>". The timestamp
+ * must be within `tolerance` seconds of `now` so that a captured callback cannot be replayed. The
+ * comparison takes constant time.
+ *
+ * A bare hex HMAC-SHA256 of the payload, with or without a "sha256=" prefix, is still accepted for
+ * signatures made the way earlier versions of this SDK documented.
  *
- * @param payload - Raw webhook payload string
- * @param signature - Webhook signature from headers (should include "sha256=" prefix)
- * @param secret - Your webhook secret key
- * @returns true if signature is valid, false otherwise
+ * @param payload - The raw request body, before any JSON decoding
+ * @param signature - The Tapsilat-Signature header
+ * @param secret - The webhook secret from the panel's callback settings
+ * @param options - Timestamp tolerance and the current time
+ * @returns true when the signature is valid; false when it is missing, malformed, stale or wrong
+ * @throws {TapsilatValidationError} When payload is not a string or bytes, or an option is not a number
  */
-const verifyHmacSignature = (payload, signature, secret) => {
-    const expectedSignature = crypto
-        .createHmac("sha256", secret)
-        .update(payload)
-        .digest("hex");
-    const expected = Buffer.from(`sha256=${expectedSignature}`);
-    const provided = Buffer.from(signature ?? "");
-    // Compare in constant time so the signature cannot be guessed byte by byte
-    return (expected.length === provided.length &&
-        crypto.timingSafeEqual(expected, provided));
+const verifyWebhookSignature = (payload, signature, secret, options = {}) => {
+    if (typeof payload !== "string" && !(payload instanceof Uint8Array)) {
+        throw new TapsilatValidationError("Webhook payload must be the raw request body as a string or Buffer");
+    }
+    const tolerance = checkSeconds(options.tolerance, "tolerance") ?? WEBHOOK_TOLERANCE;
+    const now = checkSeconds(options.now, "now") ?? Math.floor(Date.now() / 1000);
+    const header = typeof signature === "string" ? signature.trim() : "";
+    if (header === "" || typeof secret !== "string" || secret === "") {
+        return false;
+    }
+    if (header.startsWith(LEGACY_PREFIX) || !header.includes("=")) {
+        const legacy = header.startsWith(LEGACY_PREFIX) ? header.slice(LEGACY_PREFIX.length) : header;
+        return safeEqual(hmacHex(secret, payload), legacy.toLowerCase());
+    }
+    let timestamp;
+    const candidates = [];
+    for (const part of header.split(",")) {
+        const pair = part.trim();
+        const separator = pair.indexOf("=");
+        if (separator === -1) {
+            continue;
+        }
+        const key = pair.slice(0, separator);
+        const value = pair.slice(separator + 1);
+        if (key === "t") {
+            timestamp = value;
+        }
+        else if (key === "v1") {
+            candidates.push(value.toLowerCase());
+        }
+    }
+    if (timestamp === undefined || !/^[0-9]+$/.test(timestamp) || candidates.length === 0) {
+        return false;
+    }
+    const signedAt = Number(timestamp);
+    if (!Number.isSafeInteger(signedAt)) {
+        return false;
+    }
+    if (tolerance > 0 && Math.abs(now - signedAt) > tolerance) {
+        return false;
+    }
+    const expected = hmacHex(secret, `${timestamp}.`, payload);
+    let valid = false;
+    for (const candidate of candidates) {
+        valid = safeEqual(expected, candidate) || valid;
+    }
+    return valid;
 };
 
 /**
@@ -2103,7 +2226,7 @@ class TapsilatSDK {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     get webhooks() {
         return {
-            verify: (payload, signature, secret) => this.verifyWebhook(payload, signature, secret),
+            verify: (payload, signature, secret, options) => this.verifyWebhook(payload, signature, secret, options),
         };
     }
     // ORDER CREATION
@@ -2846,28 +2969,31 @@ class TapsilatSDK {
         throw new TapsilatError("Checkout URL not found in order response", "CHECKOUT_URL_NOT_FOUND");
     }
     // WEBHOOK SIGNATURE VERIFICATION
-    // Summary: Validate webhook signature for security verification
-    // Description: Verifies the authenticity of webhook payloads using HMAC signature validation
+    // Summary: Verify the Tapsilat-Signature header of a callback
+    // Description: Checks the timestamped HMAC-SHA256 that Tapsilat signs every callback with
     /**
-     * Verifies webhook signature for security
+     * Verifies the Tapsilat-Signature header of a callback against the organization's webhook secret
      *
-     * @summary Validate webhook signature for security verification
-     * @description Verifies the authenticity of webhook payloads using HMAC signature validation.
+     * @summary Verify the Tapsilat-Signature header of a callback
+     * @description
+     * Tapsilat sends "t=<unix timestamp>,v1=<hex HMAC-SHA256 of '<timestamp>.<raw body>'>". The timestamp
+     * must be within `options.tolerance` seconds (300 by default; 0 disables the check) of `options.now`
+     * (the current time by default) so that a captured callback cannot be replayed. The comparison takes
+     * constant time.
+     *
+     * A bare hex HMAC-SHA256 of the payload, with or without a "sha256=" prefix, is still accepted for
+     * signatures made the way earlier versions of this SDK documented.
      *
-     * @param payload - Raw webhook payload string
-     * @param signature - Webhook signature from headers
-     * @param secret - Your webhook secret key
-     * @returns Promise resolving to true if signature is valid
-     * @throws {TapsilatValidationError} When input validation fails for payload, signature or secret
+     * @param payload - The raw request body as a string or Buffer, before any JSON decoding
+     * @param signature - The Tapsilat-Signature header
+     * @param secret - The webhook secret from the panel's callback settings
+     * @param options - Timestamp tolerance in seconds and the current Unix time
+     * @returns Promise resolving to true when the signature is valid, and to false when the header or
+     * secret is empty, or the signature is malformed, stale or wrong
+     * @throws {TapsilatValidationError} When payload is not a string or bytes, or an option is not a number
      */
-    async verifyWebhook(payload, signature, secret) {
-        if (!isNonEmptyString(payload))
-            throw new TapsilatValidationError("Webhook payload is required and must be a non-empty string");
-        if (!isNonEmptyString(signature))
-            throw new TapsilatValidationError("Webhook signature is required and must be a non-empty string");
-        if (!isNonEmptyString(secret))
-            throw new TapsilatValidationError("Webhook secret is required and must be a non-empty string");
-        return verifyHmacSignature(payload, signature, secret);
+    async verifyWebhook(payload, signature, secret, options = {}) {
+        return verifyWebhookSignature(payload, signature, secret, options);
     }
     // API HEALTH STATUS CHECK
     // Summary: Check API service health and availability
@@ -3627,6 +3753,81 @@ class TapsilatSDK {
             return handleError(error, "get installment table");
         }
     }
+    // ELEMENTS SESSIONS
+    // Summary: Create, read and cancel sessions for the Tapsilat Elements card sheet
+    // Description: Your backend creates a session and hands only its client_secret to the app that opens the sheet
+    /**
+     * Creates a Tapsilat Elements session for the native card sheet
+     *
+     * @summary Create an Elements session
+     * @description
+     * Sends POST /elements/sessions. Hand the returned `client_secret` to your app, which opens the card
+     * sheet with it, and do not log or store it. A `pay` session needs `order_reference_id`; a `tokenize`
+     * session saves a card for `user_id` with the given `mode`.
+     *
+     * @param request - The session's purpose and its order or card owner
+     * @returns The new session with its `client_secret` and `elements_base_url`
+     * @throws {TapsilatValidationError} When `purpose` is missing
+     * @throws {TapsilatError} When the API rejects the request; `apiCode` and `retryable` say why
+     */
+    async createElementsSession(request) {
+        if (!isNonEmptyString(request?.purpose)) {
+            throw new TapsilatValidationError("Elements session purpose is required and must be a non-empty string", { provided: request?.purpose });
+        }
+        const body = Object.fromEntries(Object.entries(request).filter(([, value]) => value !== undefined && value !== null));
+        try {
+            const response = await this.httpClient.post("/elements/sessions", body);
+            return redactClientSecret(handleResponse(response, "Create Elements session"));
+        }
+        catch (error) {
+            return handleError(error, "create Elements session");
+        }
+    }
+    /**
+     * Returns the authoritative state and outcome of an Elements session
+     *
+     * @summary Get an Elements session
+     * @description
+     * Sends GET /elements/sessions/{id}. Read the outcome here on your backend before fulfilling an
+     * order, rather than trusting what the app reports.
+     *
+     * @param id - Session ID, such as "es_test_8Kq2nV0rX4"
+     * @throws {TapsilatError} With `apiCode` "session_not_found" and `statusCode` 404 for an unknown session
+     */
+    async getElementsSession(id) {
+        if (!isNonEmptyString(id)) {
+            throw new TapsilatValidationError("Elements session ID is required and must be a non-empty string", { provided: id });
+        }
+        try {
+            const response = await this.httpClient.get(`/elements/sessions/${encodeURIComponent(id)}`);
+            return handleResponse(response, "Get Elements session");
+        }
+        catch (error) {
+            return handleError(error, "get Elements session");
+        }
+    }
+    /**
+     * Cancels an Elements session that is still waiting for a card
+     *
+     * @summary Cancel an Elements session
+     * @description
+     * Sends POST /elements/sessions/{id}/cancel with no body. A session that is confirming or has
+     * completed comes back unchanged, so check `status` in the result.
+     *
+     * @param id - Session ID, such as "es_test_8Kq2nV0rX4"
+     */
+    async cancelElementsSession(id) {
+        if (!isNonEmptyString(id)) {
+            throw new TapsilatValidationError("Elements session ID is required and must be a non-empty string", { provided: id });
+        }
+        try {
+            const response = await this.httpClient.post(`/elements/sessions/${encodeURIComponent(id)}/cancel`);
+            return handleResponse(response, "Cancel Elements session");
+        }
+        catch (error) {
+            return handleError(error, "cancel Elements session");
+        }
+    }
     // ORGANIZATION CURRENCIES, USERS AND SUBORGANIZATIONS
     async listOrganizationCurrencyPresets() {
         try {
@@ -4075,9 +4276,328 @@ exports.BusinessType = void 0;
     BusinessType[BusinessType["UNKNOWN"] = 4] = "UNKNOWN";
 })(exports.BusinessType || (exports.BusinessType = {}));
 
+/**
+ * Request and response types for Tapsilat Elements sessions.
+ *
+ * Tapsilat Elements is the native Android and iOS card sheet. Your backend creates a session with
+ * its secret API key and hands only the session's `client_secret` to the app, which opens the sheet
+ * with it. Card data goes from the sheet to Tapsilat encrypted and never reaches your backend.
+ *
+ * Field names match the JSON wire format. Response fields are optional because the server omits
+ * empty values. `purpose`, `status` and `brand` are plain strings so that values added later still
+ * decode; compare them with the constants below.
+ */
+/**
+ * @category Elements
+ * @summary Purposes of an Elements session
+ */
+const ElementsSessionPurpose = Object.freeze({
+    /** Save a card for a user without charging it */
+    TOKENIZE: "tokenize",
+    /** Pay an existing order */
+    PAY: "pay",
+});
+/**
+ * @category Elements
+ * @summary Statuses of an Elements session
+ */
+const ElementsSessionStatus = Object.freeze({
+    REQUIRES_PAYMENT_METHOD: "requires_payment_method",
+    PROCESSING: "processing",
+    REQUIRES_ACTION: "requires_action",
+    SUCCEEDED: "succeeded",
+    FAILED: "failed",
+    EXPIRED: "expired",
+    CANCELED: "canceled",
+});
+/**
+ * @category Elements
+ * @summary Tokenize modes of an Elements session
+ */
+const ElementsTokenizeMode = Object.freeze({
+    /** 3D Secure */
+    SECURE: 1,
+    HALF_SECURE: 2,
+    NON_SECURE: 3,
+});
+/**
+ * @category Elements
+ * @summary Card brands an Elements session reports
+ */
+const ElementsCardBrand = Object.freeze({
+    VISA: "visa",
+    MASTERCARD: "mastercard",
+    AMEX: "amex",
+    TROY: "troy",
+    DISCOVER: "discover",
+    UNIONPAY: "unionpay",
+    UNKNOWN: "unknown",
+});
+
+const CODES = {
+    RECEIVED: 1,
+    UNPAID: 2,
+    PAID: 3,
+    PROCESSING: 4,
+    SHIPPED: 5,
+    ON_HOLD: 6,
+    WAITING_FOR_PAYMENT: 7,
+    CANCELLED: 8,
+    COMPLETED: 9,
+    REFUNDED: 10,
+    FRAUD: 11,
+    REJECTED: 12,
+    FAILURE: 13,
+    RETRYING: 14,
+    PARTIALLY_REFUNDED: 15,
+    SUB_MERCHANT_PAYMENT_APPROVED: 16,
+    SUB_MERCHANT_PAYMENT_DISAPPROVED: 17,
+    SUB_MERCHANT_PAYMENT_ERRORED: 18,
+    STILL_HAS_UNPAID_INSTALLMENTS: 19,
+    STILL_HAS_UNPAID_TERMS: 20,
+    EXPIRED: 21,
+    STILL_HAS_UNPAID_SUB_MERCHANT_PAYMENTS: 22,
+    PARTIALLY_PAID: 23,
+    TERMINATED: 24,
+    CARD_TOKENIZATION: 25,
+    PRE_AUTHORIZED: 26,
+    DISPUTED: 27,
+    PARTIALLY_DISPUTED: 28,
+    SUSPECT: 29,
+};
+/** The status names that GET /order/{reference_id}/status returns */
+const NAMES = Object.freeze({
+    [CODES.RECEIVED]: "Received",
+    [CODES.UNPAID]: "Unpaid",
+    [CODES.PAID]: "Paid",
+    [CODES.PROCESSING]: "Processing",
+    [CODES.SHIPPED]: "Shipped",
+    [CODES.ON_HOLD]: "On hold",
+    [CODES.WAITING_FOR_PAYMENT]: "Waiting for payment",
+    [CODES.CANCELLED]: "Cancelled",
+    [CODES.COMPLETED]: "Completed",
+    [CODES.REFUNDED]: "Refunded",
+    [CODES.FRAUD]: "Fraud",
+    [CODES.REJECTED]: "Rejected",
+    [CODES.FAILURE]: "Failure",
+    [CODES.RETRYING]: "Retrying",
+    [CODES.PARTIALLY_REFUNDED]: "Partially refunded",
+    [CODES.SUB_MERCHANT_PAYMENT_APPROVED]: "Sub merchant payment approved",
+    [CODES.SUB_MERCHANT_PAYMENT_DISAPPROVED]: "Sub merchant payment disapproved",
+    [CODES.SUB_MERCHANT_PAYMENT_ERRORED]: "Sub merchant payment errored",
+    [CODES.STILL_HAS_UNPAID_INSTALLMENTS]: "Still has unpaid installments",
+    [CODES.STILL_HAS_UNPAID_TERMS]: "Still has unpaid terms",
+    [CODES.EXPIRED]: "Expired",
+    [CODES.STILL_HAS_UNPAID_SUB_MERCHANT_PAYMENTS]: "Still has unpaid sub merchant payments",
+    [CODES.PARTIALLY_PAID]: "Partially Paid",
+    [CODES.TERMINATED]: "Terminated",
+    [CODES.CARD_TOKENIZATION]: "Card Tokenization",
+    [CODES.PRE_AUTHORIZED]: "Pre Authorized",
+    [CODES.DISPUTED]: "Disputed",
+    [CODES.PARTIALLY_DISPUTED]: "Partially disputed",
+    [CODES.SUSPECT]: "Suspect",
+});
+/** Statuses of an order whose payment was captured */
+const PAID_STATUSES = Object.freeze([
+    CODES.PAID,
+    CODES.COMPLETED,
+    CODES.SUB_MERCHANT_PAYMENT_APPROVED,
+]);
+/** Statuses of an order that will not be paid */
+const FAILED_STATUSES = Object.freeze([
+    CODES.CANCELLED,
+    CODES.FRAUD,
+    CODES.REJECTED,
+    CODES.FAILURE,
+    CODES.EXPIRED,
+    CODES.TERMINATED,
+]);
+/** Statuses of an order whose payment was refunded in full or in part */
+const REFUNDED_STATUSES = Object.freeze([CODES.REFUNDED, CODES.PARTIALLY_REFUNDED]);
+const isCode = (value) => Object.prototype.hasOwnProperty.call(NAMES, value);
+/**
+ * Returns the status code for a code, a numeric string such as order_lite callbacks send, or a status
+ * name such as "Paid" (case-insensitive), or null when the value is not a status
+ */
+const code = (status) => {
+    if (typeof status === "number") {
+        return Number.isInteger(status) && isCode(status) ? status : null;
+    }
+    if (typeof status !== "string") {
+        return null;
+    }
+    const trimmed = status.trim();
+    if (/^[0-9]+$/.test(trimmed)) {
+        return code(Number(trimmed));
+    }
+    const lower = trimmed.toLowerCase();
+    for (const [value, label] of Object.entries(NAMES)) {
+        if (label.toLowerCase() === lower) {
+            return Number(value);
+        }
+    }
+    return null;
+};
+/** Returns the status name, such as "Paid", or null when the value is not a status */
+const name = (status) => {
+    const statusCode = code(status);
+    return statusCode === null ? null : NAMES[statusCode];
+};
+const inGroup = (group, status) => {
+    const statusCode = code(status);
+    return statusCode !== null && group.includes(statusCode);
+};
+/**
+ * @category Order Management
+ * @summary Order status codes, their names and the paid, failed and refunded groups
+ * @description
+ * The numeric codes that callbacks and order details carry, and the names that
+ * GET /order/{reference_id}/status returns for them. Every helper accepts a code, a numeric string or
+ * a name.
+ *
+ * @example
+ * ```typescript
+ * const { status } = await tapsilat.getOrderStatus(referenceId); // e.g. "Waiting for payment"
+ * OrderStatus.isPaid(status); // Paid, Completed, Sub merchant payment approved
+ * OrderStatus.code(status); // 7; also accepts "7" or 7
+ * ```
+ */
+const OrderStatus = Object.freeze({
+    ...CODES,
+    NAMES,
+    PAID_STATUSES,
+    FAILED_STATUSES,
+    REFUNDED_STATUSES,
+    /** The code for a code, a numeric string or a name (case-insensitive), or null */
+    code,
+    /** The status name, such as "Paid", or null */
+    name,
+    /** Paid, Completed or Sub merchant payment approved */
+    isPaid: (status) => inGroup(PAID_STATUSES, status),
+    /** Cancelled, Fraud, Rejected, Failure, Expired or Terminated */
+    isFailed: (status) => inGroup(FAILED_STATUSES, status),
+    /** Refunded or Partially refunded */
+    isRefunded: (status) => inGroup(REFUNDED_STATUSES, status),
+});
+
+const ZERO_UUID = "00000000-0000-0000-0000-000000000000";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const firstString = (values) => {
+    for (const value of values) {
+        if (typeof value === "string" && value !== "" && value !== ZERO_UUID) {
+            return value;
+        }
+        if (typeof value === "number" && Number.isSafeInteger(value)) {
+            return String(value);
+        }
+    }
+    return null;
+};
+/**
+ * @category Webhooks
+ * @summary A callback Tapsilat posts to an organization's callback URLs
+ * @description
+ * Tapsilat posts {"type": "...", "data": {...}, "token": "<delivery id>"} to the organization's callback
+ * URLs and to an order's payment_success_url and payment_failure_url. The shape of "data" depends on the
+ * type, which each organization chooses in the panel: "order_lite" (the default), "order",
+ * "order_payment_detail", "extended_order" or "payment_facilitator". The getters read the order's
+ * reference ID, conversation ID and status from whichever shape arrived.
+ *
+ * Verify the Tapsilat-Signature header with `verifyWebhook()` before trusting a callback.
+ *
+ * @example
+ * ```typescript
+ * const event = WebhookEvent.fromPayload(rawBody);
+ * if (event.isPaid()) {
+ *   await fulfil(event.referenceId);
+ * }
+ * ```
+ */
+class WebhookEvent {
+    static TYPE_ORDER = "order";
+    static TYPE_ORDER_LITE = "order_lite";
+    static TYPE_ORDER_PAYMENT_DETAIL = "order_payment_detail";
+    static TYPE_EXTENDED_ORDER = "extended_order";
+    static TYPE_PAYMENT_FACILITATOR = "payment_facilitator";
+    /** The callback type, such as "order_lite" */
+    type;
+    /** Unique per delivery */
+    token;
+    /** The callback's "data" object, or the whole payload when it has none */
+    data;
+    /** The decoded payload */
+    payload;
+    constructor(payload) {
+        this.payload = payload;
+        this.type = typeof payload.type === "string" ? payload.type : null;
+        this.token = typeof payload.token === "string" ? payload.token : null;
+        this.data = isObject(payload.data) ? payload.data : payload;
+    }
+    /**
+     * Decodes a raw callback body
+     *
+     * @param payload - The raw request body
+     * @throws {TapsilatValidationError} When the body is not a JSON object
+     */
+    static fromPayload(payload) {
+        const body = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+        let decoded;
+        try {
+            decoded = JSON.parse(body);
+        }
+        catch {
+            decoded = undefined;
+        }
+        if (!isObject(decoded)) {
+            throw new TapsilatValidationError("The webhook payload is not a JSON object");
+        }
+        return new WebhookEvent(decoded);
+    }
+    /** The order's reference ID */
+    get referenceId() {
+        const order = isObject(this.data.order) ? this.data.order : {};
+        return firstString([
+            this.data.orderReferenceId,
+            this.data.order_reference_id,
+            this.data.reference_id,
+            order.reference_id,
+        ]);
+    }
+    /** The conversation ID the order was created with */
+    get conversationId() {
+        return firstString([this.data.conversationId, this.data.conversation_id]);
+    }
+    /** The order status code (see OrderStatus), or null when this callback type carries none */
+    get statusCode() {
+        const code = OrderStatus.code(this.data.status);
+        if (code === null && isObject(this.data.order)) {
+            return OrderStatus.code(this.data.order.status);
+        }
+        return code;
+    }
+    /** The order status name, such as "Paid" */
+    get status() {
+        return OrderStatus.name(this.statusCode);
+    }
+    isPaid() {
+        return OrderStatus.isPaid(this.statusCode);
+    }
+    isFailed() {
+        return OrderStatus.isFailed(this.statusCode);
+    }
+    isRefunded() {
+        return OrderStatus.isRefunded(this.statusCode);
+    }
+}
+
 exports.ConfigManager = ConfigManager;
 exports.CurrencyResolver = CurrencyResolver;
+exports.ElementsCardBrand = ElementsCardBrand;
+exports.ElementsSessionPurpose = ElementsSessionPurpose;
+exports.ElementsSessionStatus = ElementsSessionStatus;
+exports.ElementsTokenizeMode = ElementsTokenizeMode;
 exports.MarketplaceService = MarketplaceService;
+exports.OrderStatus = OrderStatus;
 exports.SubmerchantService = SubmerchantService;
 exports.TapsilatAuthenticationError = TapsilatAuthenticationError;
 exports.TapsilatError = TapsilatError;
@@ -4087,6 +4607,9 @@ exports.TapsilatSDK = TapsilatSDK;
 exports.TapsilatValidationError = TapsilatValidationError;
 exports.TokenizationService = TokenizationService;
 exports.VposService = VposService;
+exports.WEBHOOK_SIGNATURE_HEADER = WEBHOOK_SIGNATURE_HEADER;
+exports.WEBHOOK_TOLERANCE = WEBHOOK_TOLERANCE;
+exports.WebhookEvent = WebhookEvent;
 exports.cleanGsmNumber = cleanGsmNumber;
 exports.isValidCurrency = isValidCurrency;
 exports.isValidPaymentMethod = isValidPaymentMethod;