@xpayeg/sdk 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @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
 

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";
 } | {
@@ -3702,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

@@ -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";
 } | {
@@ -3702,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": "2.0.0",
+  "version": "2.1.0",
   "description": "XPay JavaScript SDK — loader and TypeScript types for embedding XPay payments",
   "license": "MIT",
   "type": "module",