@xpayeg/sdk 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @xpayeg/sdk
 
+## 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;
@@ -1347,6 +1351,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
@@ -3158,6 +3172,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. */
@@ -3594,7 +3610,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 +3624,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 +3645,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.

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;
@@ -1347,6 +1351,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
@@ -3158,6 +3172,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. */
@@ -3594,7 +3610,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 +3624,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 +3645,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.

package/package.json

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