@xpayeg/sdk 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+
+
+- [#224](https://github.com/xpayeg/xpay/pull/224) [`40beff5`](https://github.com/xpayeg/xpay/commit/40beff5ee4660914dff5c0f7c43480083bf331c4) Thanks [@mariamkamel](https://github.com/mariamkamel)! - `CheckoutCompleteResult` (drop-in `onComplete`) and the `session` in `confirmPayment()`'s success result now carry `paymentStatus`. Methods the customer pays afterwards, such as Fawry, complete checkout as `unpaid` and are paid later. Fulfil on `paymentStatus: "paid"`, never on completion alone.
+  
+  Drop-in `onError` now fires when an attempt fails (declined, canceled, processing error) and when the session is expired or already complete on load. The modal unlocks after a failed attempt so the customer can close it; previously it stayed locked until a successful payment.
+
+### Patch Changes
+
+
+
+- [#453](https://github.com/xpayeg/xpay/pull/453) [`5445718`](https://github.com/xpayeg/xpay/commit/5445718b5027cba56f1d645cba6f42904d2c2f2c) Thanks [@Elmosh](https://github.com/Elmosh)! - `@xpayeg/react` now declares its `@xpayeg/sdk` peer dependency as `^2.0.0` instead of an exact pinned version, so the two packages no longer have to be upgraded in lockstep within a major.
+
 ## 2.0.0
 ### Major Changes
 

package/dist/index.d.cts

@@ -907,6 +907,55 @@ interface ValuDetailsDto {
  */
 type PaymentMethodDetailsDtoValu = ValuDetailsDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface FawryDetailsDto {
+    /**
+     * Fawry-generated reference number the customer paid with
+     * @nullable
+     */
+    fawryRefNumber?: string | null;
+    /**
+     * Kiosk receipt/confirmation number (paymentRefrenceNumber in Fawry API)
+     * @nullable
+     */
+    paymentReferenceNumber?: string | null;
+    /**
+     * Payment channel used (e.g. PAYATFAWRY)
+     * @nullable
+     */
+    paymentMethod?: string | null;
+    /**
+     * Epoch millis when the customer paid at the kiosk
+     * @nullable
+     */
+    paymentTime?: number | null;
+    /**
+     * When the reference stops being payable.
+     * @nullable
+     */
+    expiresAt?: string | null;
+}
+
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Fawry details (if type is 'fawry')
+ * @nullable
+ */
+type PaymentMethodDetailsDtoFawry = FawryDetailsDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -925,6 +974,11 @@ interface PaymentMethodDetailsDto {
      * @nullable
      */
     valu?: PaymentMethodDetailsDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodDetailsDtoFawry;
 }
 
 /**
@@ -1242,6 +1296,10 @@ interface RefundResponseDto {
     reason?: RefundResponseDtoReason;
     /** Reason for refund failure */
     failureReason?: RefundResponseDtoFailureReason;
+    /** Error code describing why the refund failed. Same code vocabulary as payment failures. */
+    failureCode?: string;
+    /** Human-readable message for the refund failure */
+    failureMessage?: string;
     /** Reason for pending status */
     pendingReason?: RefundResponseDtoPendingReason;
     /** Description for non-card refunds */
@@ -1521,7 +1579,7 @@ declare const CheckoutSessionResponseDtoCustomerCreation: {
  * OpenAPI spec version: 1.0
  */
 /**
- * Session status
+ * Whether the customer is done with checkout. `open` while they are still on the page; `complete` once they have paid or, for methods paid later such as a Fawry reference, once they hold the reference; `expired` if the session timed out while still open. `complete` does not mean paid: read `paymentStatus` for that.
  */
 type CheckoutSessionResponseDtoStatus = typeof CheckoutSessionResponseDtoStatus[keyof typeof CheckoutSessionResponseDtoStatus];
 declare const CheckoutSessionResponseDtoStatus: {
@@ -1538,7 +1596,7 @@ declare const CheckoutSessionResponseDtoStatus: {
  * OpenAPI spec version: 1.0
  */
 /**
- * Payment status
+ * Whether the money has arrived. `paid` means fulfil; `unpaid` on a `complete` session means the customer still has to pay a reference. Never fulfil on `status` alone.
  */
 type CheckoutSessionResponseDtoPaymentStatus = typeof CheckoutSessionResponseDtoPaymentStatus[keyof typeof CheckoutSessionResponseDtoPaymentStatus];
 declare const CheckoutSessionResponseDtoPaymentStatus: {
@@ -1928,6 +1986,20 @@ type PaymentMethodObjectDtoCard = PaymentMethodCardDto | null;
  */
 type PaymentMethodObjectDtoValu = ValuDetailsDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Fawry details (if type is 'fawry')
+ * @nullable
+ */
+type PaymentMethodObjectDtoFawry = FawryDetailsDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -1974,6 +2046,11 @@ interface PaymentMethodObjectDto {
      * @nullable
      */
     valu?: PaymentMethodObjectDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodObjectDtoFawry;
     billingDetails: BillingDetailsDto;
     type: PaymentMethodObjectDtoType;
     /** Created timestamp (ISO 8601) */
@@ -2066,6 +2143,49 @@ interface NextActionRedirectDto {
  */
 type NextActionDetailDtoRedirectToUrl = NextActionRedirectDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface NextActionVoucherDto {
+    /** Payment method the reference is paid through, as its payment method type (e.g. `fawry`). */
+    provider: string;
+    /** Reference number the customer pays with at the kiosk or in the provider's app. */
+    reference: string;
+    /**
+     * When the reference stops being payable. `null` if the provider set no expiry.
+     * @nullable
+     */
+    expiresAt?: string | null;
+    /**
+     * Human-readable payment instructions for the customer. `null` if none.
+     * @nullable
+     */
+    instructions?: string | null;
+    /**
+     * URL of a hosted voucher page, when the provider offers one. `null` otherwise.
+     * @nullable
+     */
+    hostedVoucherUrl?: string | null;
+}
+
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Voucher details when `type` is `display_voucher_details`. `null` for any other action type.
+ * @nullable
+ */
+type NextActionDetailDtoDisplayVoucherDetails = NextActionVoucherDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -2075,13 +2195,18 @@ type NextActionDetailDtoRedirectToUrl = NextActionRedirectDto | null;
  */
 
 interface NextActionDetailDto {
-    /** Kind of action the customer must take next. Today the only value is `redirect_to_url`; future payment methods may add new types. */
+    /** Kind of action the customer must take next: `redirect_to_url` (3-D Secure, hosted payment pages) or `display_voucher_details` (a reference paid out-of-band, e.g. Fawry). */
     type: string;
     /**
      * Redirect details when `type` is `redirect_to_url`. `null` for any other action type.
      * @nullable
      */
     redirectToUrl?: NextActionDetailDtoRedirectToUrl;
+    /**
+     * Voucher details when `type` is `display_voucher_details`. `null` for any other action type.
+     * @nullable
+     */
+    displayVoucherDetails?: NextActionDetailDtoDisplayVoucherDetails;
 }
 
 /**
@@ -3148,9 +3273,9 @@ interface CheckoutSessionResponseDto {
     submitType: CheckoutSessionResponseDtoSubmitType;
     /** Customer creation mode */
     customerCreation: CheckoutSessionResponseDtoCustomerCreation;
-    /** Session status */
+    /** Whether the customer is done with checkout. `open` while they are still on the page; `complete` once they have paid or, for methods paid later such as a Fawry reference, once they hold the reference; `expired` if the session timed out while still open. `complete` does not mean paid: read `paymentStatus` for that. */
     status: CheckoutSessionResponseDtoStatus;
-    /** Payment status */
+    /** Whether the money has arrived. `paid` means fulfil; `unpaid` on a `complete` session means the customer still has to pay a reference. Never fulfil on `status` alone. */
     paymentStatus: CheckoutSessionResponseDtoPaymentStatus;
     /** Currency code (ISO 4217) */
     currency?: CheckoutSessionResponseDtoCurrency;
@@ -3289,6 +3414,13 @@ type Appearance = Pick<BrandingSettingsResponseDto, "colorMode" | "borderStyle"
  * }
  * ```
  */
+/**
+ * `complete` means the customer is done with checkout, not that the money has
+ * arrived. Cards and other instant methods complete as `paid`; a method the customer
+ * pays afterwards (a Fawry reference) completes as `unpaid`, and the session turns
+ * `paid` later — announced by `checkout.session.async_payment_succeeded`. Fulfil on
+ * `paymentStatus === "paid"`, never on `type === "complete"` alone.
+ */
 type SessionStatus = {
     type: "open";
 } | {
@@ -3322,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.) */
@@ -3452,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
@@ -3463,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.
  *
@@ -3518,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;
 }
@@ -3631,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 */
@@ -3702,6 +3909,12 @@ interface CheckoutInstance {
 /** Result of a successful payment via drop-in checkout */
 interface CheckoutCompleteResult {
     status: "succeeded";
+    /**
+     * Whether the money has arrived. `paid` for cards and other instant methods.
+     * `unpaid` when the customer holds a reference they pay afterwards (Fawry): the
+     * checkout is over, but fulfil only on `checkout.session.async_payment_succeeded`.
+     */
+    paymentStatus: "paid" | "unpaid" | "no_payment_required";
     /** The payment intent ID for server-side verification */
     paymentIntentId: string;
     /** The charge ID (if available) */
@@ -3857,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

@@ -907,6 +907,55 @@ interface ValuDetailsDto {
  */
 type PaymentMethodDetailsDtoValu = ValuDetailsDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface FawryDetailsDto {
+    /**
+     * Fawry-generated reference number the customer paid with
+     * @nullable
+     */
+    fawryRefNumber?: string | null;
+    /**
+     * Kiosk receipt/confirmation number (paymentRefrenceNumber in Fawry API)
+     * @nullable
+     */
+    paymentReferenceNumber?: string | null;
+    /**
+     * Payment channel used (e.g. PAYATFAWRY)
+     * @nullable
+     */
+    paymentMethod?: string | null;
+    /**
+     * Epoch millis when the customer paid at the kiosk
+     * @nullable
+     */
+    paymentTime?: number | null;
+    /**
+     * When the reference stops being payable.
+     * @nullable
+     */
+    expiresAt?: string | null;
+}
+
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Fawry details (if type is 'fawry')
+ * @nullable
+ */
+type PaymentMethodDetailsDtoFawry = FawryDetailsDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -925,6 +974,11 @@ interface PaymentMethodDetailsDto {
      * @nullable
      */
     valu?: PaymentMethodDetailsDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodDetailsDtoFawry;
 }
 
 /**
@@ -1242,6 +1296,10 @@ interface RefundResponseDto {
     reason?: RefundResponseDtoReason;
     /** Reason for refund failure */
     failureReason?: RefundResponseDtoFailureReason;
+    /** Error code describing why the refund failed. Same code vocabulary as payment failures. */
+    failureCode?: string;
+    /** Human-readable message for the refund failure */
+    failureMessage?: string;
     /** Reason for pending status */
     pendingReason?: RefundResponseDtoPendingReason;
     /** Description for non-card refunds */
@@ -1521,7 +1579,7 @@ declare const CheckoutSessionResponseDtoCustomerCreation: {
  * OpenAPI spec version: 1.0
  */
 /**
- * Session status
+ * Whether the customer is done with checkout. `open` while they are still on the page; `complete` once they have paid or, for methods paid later such as a Fawry reference, once they hold the reference; `expired` if the session timed out while still open. `complete` does not mean paid: read `paymentStatus` for that.
  */
 type CheckoutSessionResponseDtoStatus = typeof CheckoutSessionResponseDtoStatus[keyof typeof CheckoutSessionResponseDtoStatus];
 declare const CheckoutSessionResponseDtoStatus: {
@@ -1538,7 +1596,7 @@ declare const CheckoutSessionResponseDtoStatus: {
  * OpenAPI spec version: 1.0
  */
 /**
- * Payment status
+ * Whether the money has arrived. `paid` means fulfil; `unpaid` on a `complete` session means the customer still has to pay a reference. Never fulfil on `status` alone.
  */
 type CheckoutSessionResponseDtoPaymentStatus = typeof CheckoutSessionResponseDtoPaymentStatus[keyof typeof CheckoutSessionResponseDtoPaymentStatus];
 declare const CheckoutSessionResponseDtoPaymentStatus: {
@@ -1928,6 +1986,20 @@ type PaymentMethodObjectDtoCard = PaymentMethodCardDto | null;
  */
 type PaymentMethodObjectDtoValu = ValuDetailsDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Fawry details (if type is 'fawry')
+ * @nullable
+ */
+type PaymentMethodObjectDtoFawry = FawryDetailsDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -1974,6 +2046,11 @@ interface PaymentMethodObjectDto {
      * @nullable
      */
     valu?: PaymentMethodObjectDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodObjectDtoFawry;
     billingDetails: BillingDetailsDto;
     type: PaymentMethodObjectDtoType;
     /** Created timestamp (ISO 8601) */
@@ -2066,6 +2143,49 @@ interface NextActionRedirectDto {
  */
 type NextActionDetailDtoRedirectToUrl = NextActionRedirectDto | null;
 
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface NextActionVoucherDto {
+    /** Payment method the reference is paid through, as its payment method type (e.g. `fawry`). */
+    provider: string;
+    /** Reference number the customer pays with at the kiosk or in the provider's app. */
+    reference: string;
+    /**
+     * When the reference stops being payable. `null` if the provider set no expiry.
+     * @nullable
+     */
+    expiresAt?: string | null;
+    /**
+     * Human-readable payment instructions for the customer. `null` if none.
+     * @nullable
+     */
+    instructions?: string | null;
+    /**
+     * URL of a hosted voucher page, when the provider offers one. `null` otherwise.
+     * @nullable
+     */
+    hostedVoucherUrl?: string | null;
+}
+
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+
+/**
+ * Voucher details when `type` is `display_voucher_details`. `null` for any other action type.
+ * @nullable
+ */
+type NextActionDetailDtoDisplayVoucherDetails = NextActionVoucherDto | null;
+
 /**
  * Generated by orval v7.21.0 🍺
  * Do not edit manually.
@@ -2075,13 +2195,18 @@ type NextActionDetailDtoRedirectToUrl = NextActionRedirectDto | null;
  */
 
 interface NextActionDetailDto {
-    /** Kind of action the customer must take next. Today the only value is `redirect_to_url`; future payment methods may add new types. */
+    /** Kind of action the customer must take next: `redirect_to_url` (3-D Secure, hosted payment pages) or `display_voucher_details` (a reference paid out-of-band, e.g. Fawry). */
     type: string;
     /**
      * Redirect details when `type` is `redirect_to_url`. `null` for any other action type.
      * @nullable
      */
     redirectToUrl?: NextActionDetailDtoRedirectToUrl;
+    /**
+     * Voucher details when `type` is `display_voucher_details`. `null` for any other action type.
+     * @nullable
+     */
+    displayVoucherDetails?: NextActionDetailDtoDisplayVoucherDetails;
 }
 
 /**
@@ -3148,9 +3273,9 @@ interface CheckoutSessionResponseDto {
     submitType: CheckoutSessionResponseDtoSubmitType;
     /** Customer creation mode */
     customerCreation: CheckoutSessionResponseDtoCustomerCreation;
-    /** Session status */
+    /** Whether the customer is done with checkout. `open` while they are still on the page; `complete` once they have paid or, for methods paid later such as a Fawry reference, once they hold the reference; `expired` if the session timed out while still open. `complete` does not mean paid: read `paymentStatus` for that. */
     status: CheckoutSessionResponseDtoStatus;
-    /** Payment status */
+    /** Whether the money has arrived. `paid` means fulfil; `unpaid` on a `complete` session means the customer still has to pay a reference. Never fulfil on `status` alone. */
     paymentStatus: CheckoutSessionResponseDtoPaymentStatus;
     /** Currency code (ISO 4217) */
     currency?: CheckoutSessionResponseDtoCurrency;
@@ -3289,6 +3414,13 @@ type Appearance = Pick<BrandingSettingsResponseDto, "colorMode" | "borderStyle"
  * }
  * ```
  */
+/**
+ * `complete` means the customer is done with checkout, not that the money has
+ * arrived. Cards and other instant methods complete as `paid`; a method the customer
+ * pays afterwards (a Fawry reference) completes as `unpaid`, and the session turns
+ * `paid` later — announced by `checkout.session.async_payment_succeeded`. Fulfil on
+ * `paymentStatus === "paid"`, never on `type === "complete"` alone.
+ */
 type SessionStatus = {
     type: "open";
 } | {
@@ -3322,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.) */
@@ -3452,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
@@ -3463,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.
  *
@@ -3518,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;
 }
@@ -3631,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 */
@@ -3702,6 +3909,12 @@ interface CheckoutInstance {
 /** Result of a successful payment via drop-in checkout */
 interface CheckoutCompleteResult {
     status: "succeeded";
+    /**
+     * Whether the money has arrived. `paid` for cards and other instant methods.
+     * `unpaid` when the customer holds a reference they pay afterwards (Fawry): the
+     * checkout is over, but fulfil only on `checkout.session.async_payment_succeeded`.
+     */
+    paymentStatus: "paid" | "unpaid" | "no_payment_required";
     /** The payment intent ID for server-side verification */
     paymentIntentId: string;
     /** The charge ID (if available) */
@@ -3857,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.0.0",
+  "version": "2.2.0",
   "description": "XPay JavaScript SDK — loader and TypeScript types for embedding XPay payments",
   "license": "MIT",
   "type": "module",