@xpayeg/sdk 1.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @xpayeg/sdk
 
+## 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
+
+
+
+- [#331](https://github.com/xpayeg/xpay/pull/331) [`bdc6a48`](https://github.com/xpayeg/xpay/commit/bdc6a4865f8c0326a4c0eb3dd20808e1207d682a) Thanks [@Elmosh](https://github.com/Elmosh)! - **Breaking:** `returnUrl` is removed from `confirmPayment()` options. The return destination is always the checkout session's `afterCompletion.redirect.url`, set server-side at session creation.
+  
+  The URL is sent to the bank during authentication, before the browser leaves your page, so a value passed at confirm time could only ever conflict with what the bank already received. Delete `returnUrl` from `confirmPayment()` and set `afterCompletion.redirect.url` on `createSession`. `redirect: "always"` now follows that destination.
+  
+  **Breaking:** `afterCompletion` is now required for `uiMode: "embedded"` and `uiMode: "custom"`, and must be `type: "redirect"`. That URL is where the bank returns when authentication takes over the full page, which happens in in-app browsers where an embedded challenge cannot run. `hosted_confirmation` is rejected for these modes since those integrations run on your own site and there is no XPay page to return to.
+  
+  Also fixed: the 3DS challenge now renders at the size declared to the issuer (previously cropped or oversized), the overlay waits for the issuer's page to paint instead of showing an empty frame, and a challenge that cannot run in an iframe takes over the full tab instead of failing silently.
+
+### Patch Changes
+
+
+
+- [#333](https://github.com/xpayeg/xpay/pull/333) [`3dcea81`](https://github.com/xpayeg/xpay/commit/3dcea81b3e3f67267624105560c38f2615c35d96) Thanks [@Elmosh](https://github.com/Elmosh)! - Documentation: the `redirect: "always"` tables and examples now state that the destination is the checkout session's `afterCompletion.redirect.url`, set server-side at session creation.
+
 ## 1.0.1
 ### Patch Changes
 

package/README.md

@@ -231,18 +231,10 @@ await checkout.confirm({
 | `redirect` | Behavior |
 |---|---|
 | Not set (default) | `"if_required"` — returns result to your code |
-| `"always"` | Redirects to `returnUrl` (client override) → server's `afterCompletion.redirect.url` |
+| `"always"` | Redirects to the session's `afterCompletion.redirect.url` |
 | `"if_required"` | Returns result to your code — no redirect |
 
-You can override the server's redirect URL from the client:
-
-```javascript
-await checkout.confirm({
-  customerDetails: { email, name },
-  redirect: 'always',
-  returnUrl: 'https://mysite.com/custom-success', // Overrides server URL
-});
-```
+Your server sets that URL when it creates the session. XPay navigates there unchanged, appending nothing.
 
 ### Pre-validation with `submit()`
 
@@ -466,7 +458,7 @@ elements.changeAppearance({ colorMode: 'light' });
 
 ## API Reference
 
-### `loadXPay(publishableKey?)`
+### `loadXPay(publishableKey)`
 
 Loads the XPay SDK from CDN. Returns a Promise. Call at module level, not inside components.
 

package/dist/index.d.cts

@@ -749,7 +749,11 @@ interface ChargeCardDetailsDto {
     expYear: number;
     funding: string;
     last4: string;
-    network: string;
+    /**
+     * Payment rails the transaction rode (e.g. mastercard for a Meeza card). Null until the charge is processed by the gateway.
+     * @nullable
+     */
+    network: string | null;
     /** Card fingerprint for identifying the same card across customers */
     fingerprint: string;
     threeDSecure: ThreeDSecureDto;
@@ -903,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.
@@ -921,6 +974,11 @@ interface PaymentMethodDetailsDto {
      * @nullable
      */
     valu?: PaymentMethodDetailsDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodDetailsDtoFawry;
 }
 
 /**
@@ -1238,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 */
@@ -1347,6 +1409,16 @@ interface ChargeResponseDto {
     config: ChargeConfigDto;
     geocoding?: ChargeGeocodingDto;
     session?: ChargeSessionDto;
+    /**
+     * Origin of the page where this checkout ran — the merchant's site for embedded integrations (SDK Elements / drop-in), or our hosted checkout domain for hosted checkout and payment links. Null for merchant-initiated charges (recurring / MOTO).
+     * @nullable
+     */
+    merchantOrigin?: string | null;
+    /**
+     * Registrable domain (eTLD+1) derived from merchantOrigin.
+     * @nullable
+     */
+    merchantDomain?: string | null;
     processorCapabilities?: ProcessorCapabilitiesDto;
     /**
      * ID of the currently-active risk hold on this charge, if any
@@ -1507,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: {
@@ -1524,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: {
@@ -1914,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.
@@ -1960,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) */
@@ -2052,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.
@@ -2061,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;
 }
 
 /**
@@ -3134,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;
@@ -3158,6 +3297,8 @@ interface CheckoutSessionResponseDto {
     clientSecret?: string;
     /** Expiration timestamp (ISO 8601) */
     expiresAt?: string;
+    /** Whether this session can no longer be paid because it has expired (either swept/expired by status, or past `expiresAt`). Clients MUST render from this flag and MUST NOT re-derive expiry by comparing `expiresAt` against the local clock — a customer device running fast reads a live session as dead. */
+    isExpired: boolean;
     /** Customer ID (when existing customer linked) */
     customerId?: string;
     /** Customer object (when customerId is provided). Contains existing customer data for prefill. */
@@ -3273,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";
 } | {
@@ -3594,7 +3742,12 @@ interface PaymentElement extends BaseElement {
  *
  * The `redirect` option controls what happens after a successful payment:
  * - `"if_required"` (default) — returns the result to your code
- * - `"always"` — always redirects to `returnUrl` after payment
+ * - `"always"` — always redirects to the session's own destination after payment
+ *
+ * The destination is never set here. It is the `afterCompletion.redirect.url` you gave
+ * when creating the checkout session, because the same address is handed to the
+ * customer's bank during verification — before the browser leaves your page. A value
+ * supplied from the page could only ever disagree with what the bank was already told.
  *
  * @example
  * ```ts
@@ -3603,11 +3756,8 @@ interface PaymentElement extends BaseElement {
  *   customerDetails: { email: "user@example.com" },
  * });
  *
- * // Always redirect after payment
- * await checkout.confirm({
- *   redirect: "always",
- *   returnUrl: "https://merchant.com/success",
- * });
+ * // Always redirect to the session's own destination after payment
+ * await checkout.confirm({ redirect: "always" });
  * ```
  */
 interface ConfirmPaymentOptions {
@@ -3627,11 +3777,9 @@ interface ConfirmPaymentOptions {
     /**
      * Redirect behavior after payment.
      * - `"if_required"` (default) — returns the result to your code; only redirects if the payment method requires it
-     * - `"always"` — always redirects to `returnUrl` after payment. The page navigates away and the function never returns on success.
+     * - `"always"` — always redirects to the session's `afterCompletion.redirect.url` after payment. The page navigates away and the function never returns on success.
      */
     redirect?: "if_required" | "always";
-    /** URL to redirect to after payment. Overrides the session's `afterCompletion.redirect.url`. Only needed if you want a different URL than the one set server-side. */
-    returnUrl?: string;
 }
 /**
  * Options for creating a drop-in checkout instance.
@@ -3686,6 +3834,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) */

package/dist/index.d.mts

@@ -749,7 +749,11 @@ interface ChargeCardDetailsDto {
     expYear: number;
     funding: string;
     last4: string;
-    network: string;
+    /**
+     * Payment rails the transaction rode (e.g. mastercard for a Meeza card). Null until the charge is processed by the gateway.
+     * @nullable
+     */
+    network: string | null;
     /** Card fingerprint for identifying the same card across customers */
     fingerprint: string;
     threeDSecure: ThreeDSecureDto;
@@ -903,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.
@@ -921,6 +974,11 @@ interface PaymentMethodDetailsDto {
      * @nullable
      */
     valu?: PaymentMethodDetailsDtoValu;
+    /**
+     * Fawry details (if type is 'fawry')
+     * @nullable
+     */
+    fawry?: PaymentMethodDetailsDtoFawry;
 }
 
 /**
@@ -1238,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 */
@@ -1347,6 +1409,16 @@ interface ChargeResponseDto {
     config: ChargeConfigDto;
     geocoding?: ChargeGeocodingDto;
     session?: ChargeSessionDto;
+    /**
+     * Origin of the page where this checkout ran — the merchant's site for embedded integrations (SDK Elements / drop-in), or our hosted checkout domain for hosted checkout and payment links. Null for merchant-initiated charges (recurring / MOTO).
+     * @nullable
+     */
+    merchantOrigin?: string | null;
+    /**
+     * Registrable domain (eTLD+1) derived from merchantOrigin.
+     * @nullable
+     */
+    merchantDomain?: string | null;
     processorCapabilities?: ProcessorCapabilitiesDto;
     /**
      * ID of the currently-active risk hold on this charge, if any
@@ -1507,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: {
@@ -1524,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: {
@@ -1914,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.
@@ -1960,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) */
@@ -2052,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.
@@ -2061,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;
 }
 
 /**
@@ -3134,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;
@@ -3158,6 +3297,8 @@ interface CheckoutSessionResponseDto {
     clientSecret?: string;
     /** Expiration timestamp (ISO 8601) */
     expiresAt?: string;
+    /** Whether this session can no longer be paid because it has expired (either swept/expired by status, or past `expiresAt`). Clients MUST render from this flag and MUST NOT re-derive expiry by comparing `expiresAt` against the local clock — a customer device running fast reads a live session as dead. */
+    isExpired: boolean;
     /** Customer ID (when existing customer linked) */
     customerId?: string;
     /** Customer object (when customerId is provided). Contains existing customer data for prefill. */
@@ -3273,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";
 } | {
@@ -3594,7 +3742,12 @@ interface PaymentElement extends BaseElement {
  *
  * The `redirect` option controls what happens after a successful payment:
  * - `"if_required"` (default) — returns the result to your code
- * - `"always"` — always redirects to `returnUrl` after payment
+ * - `"always"` — always redirects to the session's own destination after payment
+ *
+ * The destination is never set here. It is the `afterCompletion.redirect.url` you gave
+ * when creating the checkout session, because the same address is handed to the
+ * customer's bank during verification — before the browser leaves your page. A value
+ * supplied from the page could only ever disagree with what the bank was already told.
  *
  * @example
  * ```ts
@@ -3603,11 +3756,8 @@ interface PaymentElement extends BaseElement {
  *   customerDetails: { email: "user@example.com" },
  * });
  *
- * // Always redirect after payment
- * await checkout.confirm({
- *   redirect: "always",
- *   returnUrl: "https://merchant.com/success",
- * });
+ * // Always redirect to the session's own destination after payment
+ * await checkout.confirm({ redirect: "always" });
  * ```
  */
 interface ConfirmPaymentOptions {
@@ -3627,11 +3777,9 @@ interface ConfirmPaymentOptions {
     /**
      * Redirect behavior after payment.
      * - `"if_required"` (default) — returns the result to your code; only redirects if the payment method requires it
-     * - `"always"` — always redirects to `returnUrl` after payment. The page navigates away and the function never returns on success.
+     * - `"always"` — always redirects to the session's `afterCompletion.redirect.url` after payment. The page navigates away and the function never returns on success.
      */
     redirect?: "if_required" | "always";
-    /** URL to redirect to after payment. Overrides the session's `afterCompletion.redirect.url`. Only needed if you want a different URL than the one set server-side. */
-    returnUrl?: string;
 }
 /**
  * Options for creating a drop-in checkout instance.
@@ -3686,6 +3834,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) */

package/package.json

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