@xpayeg/sdk 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @xpayeg/sdk
 
+## 2.2.0
+### Minor Changes
+
+
+
+- [#462](https://github.com/xpayeg/xpay/pull/462) [`f083704`](https://github.com/xpayeg/xpay/commit/f08370434ff93c52450cfaee17f249c11b5cd46c) Thanks [@Elmosh](https://github.com/Elmosh)! - Deferred-mount Payment Element: `xpay.elements({ mode: "payment", amount, currency })` renders the payment form with no checkout session — your server creates the session with the final total when the customer clicks Pay, and its clientSecret is passed to `confirmPayment({ elements, clientSecret })` (a plain string). The session's total must equal the amount the element displays, or the confirmation fails with `amount_reconfirmation_required` and nothing is charged. Adds `elements.update({ amount, currency })` for deferred display updates. `XPayProvider` accepts the new options form; deferred amount/currency prop changes flow through `elements.update()` without recreating the instance. The existing `{ clientSecret }` path is unchanged.
+  
+  Also in this release: the overlay scroll lock (3DS/action overlay and drop-in modal, now one shared implementation) pins the page at its measured geometry and preserves the scrollbar gutter, so centered boxed themes no longer shift when an overlay opens; `elements.fetchUpdates()` now genuinely re-fetches the session from the server (it previously answered from the iframe's local state; failures now resolve the error arm instead of returning stale data), and `CheckoutSession` gains optional `presentmentDetails` — the customer-facing amounts, present only when the merchant prices in a currency other than the processing currency. Read amounts presentment-first.
+
 ## 2.1.0
 ### Minor Changes
 

package/dist/index.d.cts

@@ -3454,6 +3454,13 @@ type CheckoutSession = Pick<CheckoutSessionResponseDto, "id" | "amountSubtotal"
     canConfirm: boolean;
     /** Available payment methods */
     paymentMethods: PaymentMethodInfo[];
+    /**
+     * Customer-facing amounts, present only when the merchant prices in a
+     * currency other than the processing currency — read amounts
+     * presentment-first (`presentmentDetails.amountTotal` when present,
+     * top-level `amountTotal` otherwise).
+     */
+    presentmentDetails?: CheckoutSessionResponseDto["presentmentDetails"];
     /** Line items in the session */
     lineItems?: CheckoutSessionResponseDto["lineItems"];
     /** Totals breakdown (subtotal, tax, shipping, etc.) */
@@ -3584,7 +3591,7 @@ interface XPayInstance {
     initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
 }
 /**
- * Options for creating an Elements instance.
+ * Options for creating an Elements instance from an existing checkout session.
  *
  * @example
  * ```ts
@@ -3595,14 +3602,67 @@ interface XPayInstance {
  * });
  * ```
  */
-interface ElementsOptions {
+interface ElementsOptionsClientSecret {
     /** The client secret from a checkout session. Can be a string or a Promise. */
     clientSecret: string | Promise<string>;
+    /** Either use mode or clientSecret when creating an Elements group. */
+    mode?: never;
+    /** Amount is only applicable in deferred mode (`mode: "payment"`). */
+    amount?: never;
+    /** Currency is only applicable in deferred mode (`mode: "payment"`). */
+    currency?: never;
     /** Appearance overrides for the checkout UI */
     appearance?: Appearance;
     /** Locale for the payment form — `"en"` (default) or `"ar"` */
     locale?: "en" | "ar";
 }
+/**
+ * Options for creating a DEFERRED Elements instance — no checkout session
+ * exists yet. The Payment Element renders immediately from the amount and
+ * currency alone; your server creates the session with the final total when
+ * the customer clicks Pay, and its clientSecret is passed to
+ * `confirmPayment({ elements, clientSecret })`.
+ *
+ * The amount shown is the amount charged: if the session your server creates
+ * has a different total, the confirmation fails with
+ * `amount_reconfirmation_required` and nothing is charged.
+ *
+ * @example
+ * ```ts
+ * const elements = xpay.elements({
+ *   mode: "payment",
+ *   amount: 250000, // piasters
+ *   currency: "EGP",
+ * });
+ * ```
+ */
+interface ElementsOptionsMode {
+    /** Deferred mode. Only `"payment"` is supported. */
+    mode: "payment";
+    /** The amount to display and charge, in the currency's smallest unit (piasters). Integer, greater than zero. */
+    amount: number;
+    /** Three-letter currency code (e.g. `"EGP"`). */
+    currency: string;
+    /** Either use mode or clientSecret when creating an Elements group. */
+    clientSecret?: never;
+    /** Appearance overrides for the checkout UI */
+    appearance?: Appearance;
+    /** Locale for the payment form — `"en"` (default) or `"ar"` */
+    locale?: "en" | "ar";
+}
+/**
+ * Options for creating an Elements instance — with a session's
+ * `clientSecret`, or session-less with `{ mode, amount, currency }`
+ * (deferred). The two forms are mutually exclusive.
+ */
+type ElementsOptions = ElementsOptionsClientSecret | ElementsOptionsMode;
+/** Options for `elements.update()` — deferred mode only. */
+interface ElementsUpdateOptions {
+    /** New display amount in the currency's smallest unit. Integer, greater than zero. */
+    amount?: number;
+    /** New three-letter currency code. */
+    currency?: string;
+}
 /**
  * Manages the lifecycle of the PaymentElement.
  *
@@ -3650,6 +3710,12 @@ interface Elements {
     fetchUpdates(): Promise<ActionResult>;
     /** Update the appearance at runtime without recreating elements */
     changeAppearance(appearance: Appearance): void;
+    /**
+     * Update the displayed amount/currency of a DEFERRED Elements instance
+     * (created with `{ mode: "payment" }`). Throws when the instance was
+     * created with a `clientSecret` — session amounts are server-owned.
+     */
+    update(options: ElementsUpdateOptions): Promise<void>;
     /** Destroy the Elements instance and clean up all resources */
     destroy(): void;
 }
@@ -3763,6 +3829,15 @@ interface PaymentElement extends BaseElement {
 interface ConfirmPaymentOptions {
     /** The Elements instance managing the payment form */
     elements: Elements;
+    /**
+     * DEFERRED mode only, and required there: the clientSecret of the checkout
+     * session your server just created with the final total. A plain string —
+     * await your own fetch before calling. The session's total must equal the
+     * amount the element displays, or the confirmation fails with
+     * `amount_reconfirmation_required` and nothing is charged. Ignored when the
+     * elements were created with a clientSecret.
+     */
+    clientSecret?: string;
     /** Customer details collected by the merchant's form */
     customerDetails?: CustomerDetails;
     /** Custom field values for the session */
@@ -3995,4 +4070,4 @@ declare global {
 declare function loadXPay(publishableKey: string): Promise<XPayInstance | null>;
 
 export { loadXPay };
-export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };
+export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsOptionsClientSecret, ElementsOptionsMode, ElementsReadyEvent, ElementsUpdateOptions, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };

package/dist/index.d.mts

@@ -3454,6 +3454,13 @@ type CheckoutSession = Pick<CheckoutSessionResponseDto, "id" | "amountSubtotal"
     canConfirm: boolean;
     /** Available payment methods */
     paymentMethods: PaymentMethodInfo[];
+    /**
+     * Customer-facing amounts, present only when the merchant prices in a
+     * currency other than the processing currency — read amounts
+     * presentment-first (`presentmentDetails.amountTotal` when present,
+     * top-level `amountTotal` otherwise).
+     */
+    presentmentDetails?: CheckoutSessionResponseDto["presentmentDetails"];
     /** Line items in the session */
     lineItems?: CheckoutSessionResponseDto["lineItems"];
     /** Totals breakdown (subtotal, tax, shipping, etc.) */
@@ -3584,7 +3591,7 @@ interface XPayInstance {
     initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
 }
 /**
- * Options for creating an Elements instance.
+ * Options for creating an Elements instance from an existing checkout session.
  *
  * @example
  * ```ts
@@ -3595,14 +3602,67 @@ interface XPayInstance {
  * });
  * ```
  */
-interface ElementsOptions {
+interface ElementsOptionsClientSecret {
     /** The client secret from a checkout session. Can be a string or a Promise. */
     clientSecret: string | Promise<string>;
+    /** Either use mode or clientSecret when creating an Elements group. */
+    mode?: never;
+    /** Amount is only applicable in deferred mode (`mode: "payment"`). */
+    amount?: never;
+    /** Currency is only applicable in deferred mode (`mode: "payment"`). */
+    currency?: never;
     /** Appearance overrides for the checkout UI */
     appearance?: Appearance;
     /** Locale for the payment form — `"en"` (default) or `"ar"` */
     locale?: "en" | "ar";
 }
+/**
+ * Options for creating a DEFERRED Elements instance — no checkout session
+ * exists yet. The Payment Element renders immediately from the amount and
+ * currency alone; your server creates the session with the final total when
+ * the customer clicks Pay, and its clientSecret is passed to
+ * `confirmPayment({ elements, clientSecret })`.
+ *
+ * The amount shown is the amount charged: if the session your server creates
+ * has a different total, the confirmation fails with
+ * `amount_reconfirmation_required` and nothing is charged.
+ *
+ * @example
+ * ```ts
+ * const elements = xpay.elements({
+ *   mode: "payment",
+ *   amount: 250000, // piasters
+ *   currency: "EGP",
+ * });
+ * ```
+ */
+interface ElementsOptionsMode {
+    /** Deferred mode. Only `"payment"` is supported. */
+    mode: "payment";
+    /** The amount to display and charge, in the currency's smallest unit (piasters). Integer, greater than zero. */
+    amount: number;
+    /** Three-letter currency code (e.g. `"EGP"`). */
+    currency: string;
+    /** Either use mode or clientSecret when creating an Elements group. */
+    clientSecret?: never;
+    /** Appearance overrides for the checkout UI */
+    appearance?: Appearance;
+    /** Locale for the payment form — `"en"` (default) or `"ar"` */
+    locale?: "en" | "ar";
+}
+/**
+ * Options for creating an Elements instance — with a session's
+ * `clientSecret`, or session-less with `{ mode, amount, currency }`
+ * (deferred). The two forms are mutually exclusive.
+ */
+type ElementsOptions = ElementsOptionsClientSecret | ElementsOptionsMode;
+/** Options for `elements.update()` — deferred mode only. */
+interface ElementsUpdateOptions {
+    /** New display amount in the currency's smallest unit. Integer, greater than zero. */
+    amount?: number;
+    /** New three-letter currency code. */
+    currency?: string;
+}
 /**
  * Manages the lifecycle of the PaymentElement.
  *
@@ -3650,6 +3710,12 @@ interface Elements {
     fetchUpdates(): Promise<ActionResult>;
     /** Update the appearance at runtime without recreating elements */
     changeAppearance(appearance: Appearance): void;
+    /**
+     * Update the displayed amount/currency of a DEFERRED Elements instance
+     * (created with `{ mode: "payment" }`). Throws when the instance was
+     * created with a `clientSecret` — session amounts are server-owned.
+     */
+    update(options: ElementsUpdateOptions): Promise<void>;
     /** Destroy the Elements instance and clean up all resources */
     destroy(): void;
 }
@@ -3763,6 +3829,15 @@ interface PaymentElement extends BaseElement {
 interface ConfirmPaymentOptions {
     /** The Elements instance managing the payment form */
     elements: Elements;
+    /**
+     * DEFERRED mode only, and required there: the clientSecret of the checkout
+     * session your server just created with the final total. A plain string —
+     * await your own fetch before calling. The session's total must equal the
+     * amount the element displays, or the confirmation fails with
+     * `amount_reconfirmation_required` and nothing is charged. Ignored when the
+     * elements were created with a clientSecret.
+     */
+    clientSecret?: string;
     /** Customer details collected by the merchant's form */
     customerDetails?: CustomerDetails;
     /** Custom field values for the session */
@@ -3995,4 +4070,4 @@ declare global {
 declare function loadXPay(publishableKey: string): Promise<XPayInstance | null>;
 
 export { loadXPay };
-export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsReadyEvent, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };
+export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, DiscountResponseDto as CheckoutDiscount, CheckoutError, FeesResponseDto as CheckoutFees, CheckoutInstance, LineItemDto as CheckoutLineItem, CheckoutOptions, CheckoutSession, TotalDetailsResponseDto as CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsOptionsClientSecret, ElementsOptionsMode, ElementsReadyEvent, ElementsUpdateOptions, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpayeg/sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "XPay JavaScript SDK — loader and TypeScript types for embedding XPay payments",
   "license": "MIT",
   "type": "module",