@xpayeg/sdk 2.4.0 → 3.0.0

package/.types/index.d.cts

@@ -0,0 +1,1635 @@
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface AdjustableQuantityDto {
+  /** Whether adjustable quantity is enabled */
+  enabled: boolean;
+  /**
+   * Minimum quantity allowed
+   * @nullable
+   */
+  minimum?: number | null;
+  /**
+   * Maximum quantity allowed
+   * @nullable
+   */
+  maximum?: number | null;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Border style for inputs, buttons, cards
+ * @nullable
+ */
+type BrandingSettingsResponseDtoBorderStyle = (typeof BrandingSettingsResponseDtoBorderStyle)[keyof typeof BrandingSettingsResponseDtoBorderStyle] | null;
+declare const BrandingSettingsResponseDtoBorderStyle: {
+  readonly rounded: "rounded";
+  readonly sharp: "sharp";
+  readonly pill: "pill";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Dark mode preference
+ * @nullable
+ */
+type BrandingSettingsResponseDtoColorMode = (typeof BrandingSettingsResponseDtoColorMode)[keyof typeof BrandingSettingsResponseDtoColorMode] | null;
+declare const BrandingSettingsResponseDtoColorMode: {
+  readonly light: "light";
+  readonly dark: "dark";
+  readonly system: "system";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Form layout density
+ * @nullable
+ */
+type BrandingSettingsResponseDtoFormLayout = (typeof BrandingSettingsResponseDtoFormLayout)[keyof typeof BrandingSettingsResponseDtoFormLayout] | null;
+declare const BrandingSettingsResponseDtoFormLayout: {
+  readonly compact: "compact";
+  readonly spacious: "spacious";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Input field size
+ * @nullable
+ */
+type BrandingSettingsResponseDtoInputSize = (typeof BrandingSettingsResponseDtoInputSize)[keyof typeof BrandingSettingsResponseDtoInputSize] | null;
+declare const BrandingSettingsResponseDtoInputSize: {
+  readonly small: "small";
+  readonly medium: "medium";
+  readonly large: "large";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Input field style
+ * @nullable
+ */
+type BrandingSettingsResponseDtoInputStyle = (typeof BrandingSettingsResponseDtoInputStyle)[keyof typeof BrandingSettingsResponseDtoInputStyle] | null;
+declare const BrandingSettingsResponseDtoInputStyle: {
+  readonly flat: "flat";
+  readonly outlined: "outlined";
+  readonly filled: "filled";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Spacing density
+ * @nullable
+ */
+type BrandingSettingsResponseDtoSpacing = (typeof BrandingSettingsResponseDtoSpacing)[keyof typeof BrandingSettingsResponseDtoSpacing] | null;
+declare const BrandingSettingsResponseDtoSpacing: {
+  readonly condensed: "condensed";
+  readonly normal: "normal";
+  readonly spacious: "spacious";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface ColorCustomizationResponseDto {
+  /**
+   * Primary brand color (buttons, links, accents). Hex only.
+   * @nullable
+   */
+  primary?: string | null;
+  /**
+   * Primary foreground (text on primary background). Hex only.
+   * @nullable
+   */
+  primaryForeground?: string | null;
+  /**
+   * Page background color. Hex only.
+   * @nullable
+   */
+  background?: string | null;
+  /**
+   * Main text color. Hex only.
+   * @nullable
+   */
+  foreground?: string | null;
+  /**
+   * Border color. Hex only.
+   * @nullable
+   */
+  border?: string | null;
+  /**
+   * Input, button, and dropdown border color. Hex only.
+   * @nullable
+   */
+  input?: string | null;
+  /**
+   * Focus ring color. Hex only.
+   * @nullable
+   */
+  ring?: string | null;
+  /**
+   * Muted/secondary background. Hex only.
+   * @nullable
+   */
+  muted?: string | null;
+  /**
+   * Muted text color. Hex only.
+   * @nullable
+   */
+  mutedForeground?: string | null;
+  /**
+   * Accent background. Hex only.
+   * @nullable
+   */
+  accent?: string | null;
+  /**
+   * Accent text color. Hex only.
+   * @nullable
+   */
+  accentForeground?: string | null;
+  /**
+   * Destructive/error color. Hex only.
+   * @nullable
+   */
+  destructive?: string | null;
+}
+interface BrandingSettingsResponseDto {
+  /**
+   * Dark mode preference
+   * @nullable
+   */
+  colorMode?: BrandingSettingsResponseDtoColorMode;
+  /**
+   * Border style for inputs, buttons, cards
+   * @nullable
+   */
+  borderStyle?: BrandingSettingsResponseDtoBorderStyle;
+  /**
+   * Spacing density
+   * @nullable
+   */
+  spacing?: BrandingSettingsResponseDtoSpacing;
+  /**
+   * Input field size
+   * @nullable
+   */
+  inputSize?: BrandingSettingsResponseDtoInputSize;
+  /**
+   * Input field style
+   * @nullable
+   */
+  inputStyle?: BrandingSettingsResponseDtoInputStyle;
+  /**
+   * Form layout density
+   * @nullable
+   */
+  formLayout?: BrandingSettingsResponseDtoFormLayout;
+  /** Color customization options */
+  colors?: ColorCustomizationResponseDto | null;
+  /**
+   * Font family override
+   * @nullable
+   */
+  fontFamily?: string | null;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface CardInfoResponseDto {
+  brand: string;
+  isOnUs: boolean;
+  isInternational: boolean;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * @nullable
+ */
+type CatalogRecurringDtoInterval = (typeof CatalogRecurringDtoInterval)[keyof typeof CatalogRecurringDtoInterval] | null;
+declare const CatalogRecurringDtoInterval: {
+  readonly DAY: "DAY";
+  readonly WEEK: "WEEK";
+  readonly MONTH: "MONTH";
+  readonly YEAR: "YEAR";
+  readonly CUSTOM: "CUSTOM";
+};
+interface CatalogRecurringDto {
+  /** @nullable */
+  interval?: CatalogRecurringDtoInterval;
+  /** @nullable */
+  intervalCount?: number | null;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+type CouponResponseDtoCurrency = (typeof CouponResponseDtoCurrency)[keyof typeof CouponResponseDtoCurrency];
+declare const CouponResponseDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Discount type
+ */
+type CouponResponseDtoDiscountType = (typeof CouponResponseDtoDiscountType)[keyof typeof CouponResponseDtoDiscountType];
+declare const CouponResponseDtoDiscountType: {
+  readonly percentage: "percentage";
+  readonly fixed_amount: "fixed_amount";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Duration
+ */
+type CouponResponseDtoDuration = (typeof CouponResponseDtoDuration)[keyof typeof CouponResponseDtoDuration];
+declare const CouponResponseDtoDuration: {
+  readonly once: "once";
+  readonly repeating: "repeating";
+  readonly forever: "forever";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Custom metadata
+ */
+type CouponResponseDtoMetadata = {
+  [key: string]: unknown;
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Object type
+ */
+type CouponResponseDtoObject = (typeof CouponResponseDtoObject)[keyof typeof CouponResponseDtoObject];
+declare const CouponResponseDtoObject: {
+  readonly coupon: "coupon";
+};
+/**
+ * A Coupon defines a reusable discount you can apply to Checkout Sessions and PaymentIntents. Coupons can grant either a percentage off (`percentOff`) or a fixed amount off (`amountOff`), and can apply once, forever, or repeating for a number of billing cycles. You can also cap how many times a Coupon may be redeemed and when it expires.
+ *
+ * Coupons are the reusable template. Each concrete application of a Coupon to a customer's purchase is recorded as a Discount. To give customers a redeemable code (e.g. `SUMMER25`) instead of applying the Coupon directly, create one or more Promotion Codes that map to this Coupon — a single Coupon can have many Promotion Codes, each with its own per-code restrictions. You receive `coupon.*` and `promotion_code.*` webhook events for each as they are created or changed.
+ */
+interface CouponResponseDto {
+  /** Coupon ID */
+  id: string;
+  /** Object type */
+  object: CouponResponseDtoObject;
+  /** Created timestamp (ISO 8601) */
+  createdAt: string;
+  /** Discount type */
+  discountType: CouponResponseDtoDiscountType;
+  /** Percentage off (0.01-100) */
+  percentOff?: number;
+  /** Fixed amount off in smallest currency unit */
+  amountOff?: number;
+  currency?: CouponResponseDtoCurrency;
+  /** Duration */
+  duration: CouponResponseDtoDuration;
+  /** Number of months for repeating duration */
+  durationInMonths?: number;
+  /** Display name */
+  name?: string;
+  /** Maximum discount amount for percentage coupons (caps the discount) */
+  maxDiscountAmount?: number;
+  /** Minimum order subtotal required to use this coupon */
+  minValue?: number;
+  /** Maximum total redemptions */
+  maxRedemptions?: number;
+  /** Maximum times a single customer can redeem */
+  customerMaxRedemptions?: number;
+  /** Number of times redeemed */
+  timesRedeemed: number;
+  /** Redemption deadline (ISO 8601) */
+  redeemBy?: string;
+  /** Whether the coupon is currently valid (computed) */
+  valid: boolean;
+  /** Whether the coupon is active */
+  active: boolean;
+  /** Product IDs this coupon applies to */
+  appliesToProductIds?: string[];
+  /** Custom metadata */
+  metadata?: CouponResponseDtoMetadata;
+  /** Merchant ID */
+  merchantId: string;
+  /** Whether this is live mode */
+  livemode: boolean;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Object type
+ */
+type DiscountResponseDtoObject = (typeof DiscountResponseDtoObject)[keyof typeof DiscountResponseDtoObject];
+declare const DiscountResponseDtoObject: {
+  readonly discount: "discount";
+};
+/**
+ * A Discount records a single application of a Coupon to a specific Checkout Session, PaymentIntent, or Customer. Where a Coupon is the reusable template, a Discount captures the concrete redemption: which Coupon was applied, when it became active, when it expires, and (when applicable) which Promotion Code the customer entered to claim it.
+ */
+interface DiscountResponseDto {
+  /** Discount ID */
+  id: string;
+  /** Object type */
+  object: DiscountResponseDtoObject;
+  /** The coupon that was applied */
+  coupon: CouponResponseDto;
+  /** Promotion code ID used (null if direct coupon application) */
+  promotionCodeId?: string;
+  /** Customer-facing promotion code string (e.g. SUMMER25) */
+  promotionCodeCode?: string;
+  /** Checkout session this discount was applied to */
+  checkoutSessionId: string;
+  /** Customer who received the discount */
+  customerId?: string;
+  /** When the discount became active (ISO 8601) */
+  start: string;
+  /** When the discount ends (ISO 8601) */
+  end?: string;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+type PendingCouponResponseDtoObject = (typeof PendingCouponResponseDtoObject)[keyof typeof PendingCouponResponseDtoObject];
+declare const PendingCouponResponseDtoObject: {
+  readonly coupon: "coupon";
+};
+/**
+ * The Coupon selected for a Checkout Session before payment completes. It contains the discount terms used to calculate the session total; the Coupon has not yet been redeemed.
+ */
+interface PendingCouponResponseDto {
+  id: string;
+  object: PendingCouponResponseDtoObject;
+  /** @nullable */
+  name?: string | null;
+  discountType: string;
+  /** @nullable */
+  percentOff?: number | null;
+  /** @nullable */
+  amountOff?: string | null;
+  /** @nullable */
+  currency?: string | null;
+  valid: true;
+  livemode: boolean;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+type PendingDiscountResponseDtoId = (typeof PendingDiscountResponseDtoId)[keyof typeof PendingDiscountResponseDtoId];
+declare const PendingDiscountResponseDtoId: {
+  readonly pending: "pending";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Object type
+ */
+type PendingDiscountResponseDtoObject = (typeof PendingDiscountResponseDtoObject)[keyof typeof PendingDiscountResponseDtoObject];
+declare const PendingDiscountResponseDtoObject: {
+  readonly discount: "discount";
+};
+/**
+ * A Discount selected for a Checkout Session before payment completes. Its ID is pending until the discount is redeemed, and it includes the selected Coupon and any Promotion Code used.
+ */
+interface PendingDiscountResponseDto {
+  id: PendingDiscountResponseDtoId;
+  /** Object type */
+  object: PendingDiscountResponseDtoObject;
+  coupon: PendingCouponResponseDto;
+  /** @nullable */
+  promotionCodeId?: string | null;
+  /** @nullable */
+  promotionCodeCode?: string | null;
+  /** Checkout session this discount was applied to */
+  checkoutSessionId: string;
+  /** Customer who received the discount */
+  customerId?: string;
+  /** When the discount became active (ISO 8601) */
+  start: string;
+  /** When the discount ends (ISO 8601) */
+  end?: string;
+}
+type CheckoutDiscountResponseDto = DiscountResponseDto | PendingDiscountResponseDto;
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Currency code (ISO 4217)
+ * @nullable
+ */
+type CheckoutSessionResponseDtoCurrency = (typeof CheckoutSessionResponseDtoCurrency)[keyof typeof CheckoutSessionResponseDtoCurrency] | null;
+declare const CheckoutSessionResponseDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * 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: {
+  readonly paid: "paid";
+  readonly unpaid: "unpaid";
+  readonly no_payment_required: "no_payment_required";
+};
+interface FeesResponseDto {
+  paymentMethodType: string;
+  feeAmount: number;
+  feePercentage: number;
+  vatAmount?: number;
+  totalAmount: number;
+  cardInfo?: CardInfoResponseDto;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Currency of this line's amount fields
+ * @nullable
+ */
+type LineItemDtoCurrency = (typeof LineItemDtoCurrency)[keyof typeof LineItemDtoCurrency] | null;
+declare const LineItemDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Presentment currency matching the session
+ */
+type LineItemPresentmentDetailsDtoCurrency = (typeof LineItemPresentmentDetailsDtoCurrency)[keyof typeof LineItemPresentmentDetailsDtoCurrency];
+declare const LineItemPresentmentDetailsDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+interface LineItemPresentmentDetailsDto {
+  /** Unit amount in presentment smallest units */
+  unitAmount: number;
+  /** Line subtotal in presentment smallest units */
+  amountSubtotal: number;
+  /** Allocated line discount in presentment smallest units */
+  amountDiscount: number;
+  /** Line total after discount and tax, in presentment smallest units */
+  amountTotal: number;
+  /** Presentment currency matching the session */
+  currency: LineItemPresentmentDetailsDtoCurrency;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface CustomUnitAmountResponseDto {
+  /**
+   * Minimum amount the customer may enter (minor units).
+   * @nullable
+   */
+  minimum?: number | null;
+  /**
+   * Maximum amount the customer may enter (minor units).
+   * @nullable
+   */
+  maximum?: number | null;
+  /**
+   * Suggested amount pre-filled for the customer (minor units).
+   * @nullable
+   */
+  preset?: number | null;
+}
+type CustomUnitAmountDto = CustomUnitAmountResponseDto;
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Price currency
+ */
+type PriceDtoCurrency = (typeof PriceDtoCurrency)[keyof typeof PriceDtoCurrency];
+declare const PriceDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Price type
+ */
+type PriceDtoType = (typeof PriceDtoType)[keyof typeof PriceDtoType];
+declare const PriceDtoType: {
+  readonly ONE_TIME: "ONE_TIME";
+  readonly RECURRING: "RECURRING";
+  readonly CUSTOM: "CUSTOM";
+};
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface ProductDto {
+  /** Product ID */
+  id: string;
+  /** Product name */
+  name: string;
+  /**
+   * Product description
+   * @nullable
+   */
+  description?: string | null;
+  /**
+   * Product image identifier
+   * @nullable
+   */
+  image?: string | null;
+  /**
+   * Unit label, such as seat or license
+   * @nullable
+   */
+  unitLabel?: string | null;
+  /** Whether the product is available; inline products surface as active */
+  active: boolean;
+}
+type RecurringDto = CatalogRecurringDto;
+interface PriceDto {
+  /** Price ID */
+  id: string;
+  /** Unit amount in smallest currency units */
+  unitAmount?: number;
+  /** Price currency */
+  currency: PriceDtoCurrency;
+  /** Price type */
+  type: PriceDtoType;
+  recurring?: RecurringDto;
+  customUnitAmount?: CustomUnitAmountDto;
+  /**
+   * Creation timestamp
+   * @pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+   */
+  createdAt: string;
+  /** Whether the price is available; inline prices surface as active */
+  active: boolean;
+  /**
+   * Remaining stock; null means unlimited and negative means oversold
+   * @nullable
+   */
+  stock?: number | null;
+  /**
+   * Earliest checkout availability
+   * @nullable
+   * @pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+   */
+  startDate?: string | null;
+  /**
+   * Checkout availability ends at this time
+   * @nullable
+   * @pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
+   */
+  expirationDate?: string | null;
+  product: ProductDto;
+}
+interface LineItemDto {
+  /** Line item ID */
+  id: string;
+  /** Quantity; zero represents an optional item */
+  quantity: number;
+  price: PriceDto;
+  adjustableQuantity?: AdjustableQuantityDto;
+  /** Subtotal before discounts and taxes */
+  amountSubtotal?: number;
+  /** Total after discounts and taxes */
+  amountTotal?: number;
+  /** Allocated discount */
+  amountDiscount?: number;
+  /** Allocated tax */
+  amountTax?: number;
+  /**
+   * Currency of this line's amount fields
+   * @nullable
+   */
+  currency?: LineItemDtoCurrency;
+  /** Line item description */
+  description?: string;
+  presentmentDetails?: LineItemPresentmentDetailsDto;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface PaymentMethodTypeResponseDto {
+  /** Concrete payment method type */
+  type: string;
+  /** Display name */
+  displayName: string;
+  /** UI grouping category */
+  category?: string;
+  /**
+   * Minimum transaction amount in smallest currency units
+   * @nullable
+   */
+  minTransactionAmount?: string | null;
+  /**
+   * Maximum transaction amount in smallest currency units
+   * @nullable
+   */
+  maxTransactionAmount?: string | null;
+  /** @nullable */
+  requiredCustomerFields?: string[] | null;
+  supportsRefund?: boolean;
+  supportsPartialRefund?: boolean;
+  supportsPartialCapture?: boolean;
+  paymentConfirmation?: string;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+/**
+ * Customer's currency code (ISO 4217)
+ */
+type SessionPresentmentDetailsDtoCurrency = (typeof SessionPresentmentDetailsDtoCurrency)[keyof typeof SessionPresentmentDetailsDtoCurrency];
+declare const SessionPresentmentDetailsDtoCurrency: {
+  readonly EGP: "EGP";
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly SAR: "SAR";
+  readonly AED: "AED";
+  readonly QAR: "QAR";
+  readonly KWD: "KWD";
+  readonly JOD: "JOD";
+  readonly OMR: "OMR";
+  readonly BHD: "BHD";
+  readonly LYD: "LYD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CNY: "CNY";
+};
+interface SessionPresentmentDetailsDto {
+  /** Amount in the customer's currency, in the smallest unit */
+  amount: number;
+  /** Customer's currency code (ISO 4217) */
+  currency: SessionPresentmentDetailsDtoCurrency;
+  /** Locked rate: presentment major units × rate = processing major units */
+  exchangeRate: number;
+  /** Immutable exchange-rate record ID */
+  exchangeRateId: string;
+  /** Subtotal before discounts and fees, in presentment smallest units */
+  amountSubtotal: number;
+  /** Final total in presentment smallest units */
+  amountTotal: number;
+  /** Discount in presentment smallest units */
+  amountDiscount: number;
+  /** Collected VAT when collection is enabled */
+  amountCollectedVat?: number;
+  /** Platform fee when fees are passed through */
+  amountPlatformFee?: number;
+  /** Tax when charged */
+  amountTax?: number;
+}
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * XPay Checkout API
+ * API for the XPay checkout flow — client endpoints and SSR
+ * OpenAPI spec version: 1.0
+ */
+interface TotalDetailsResponseDto {
+  /** Discount amount */
+  amountDiscount: number;
+  /** Shipping amount */
+  amountShipping?: number;
+  /** Tax amount */
+  amountTax: number;
+  /** Platform fee passed through to the customer */
+  amountPlatformFee?: number;
+  /** Collected VAT amount */
+  amountCollectedVat?: number;
+}
+/**
+ * Information about an available payment method.
+ *
+ * @example
+ * ```ts
+ * checkout.paymentMethods.forEach(pm => {
+ *   console.log(pm.type);        // "card", "valu", "fawry"
+ *   console.log(pm.displayName); // "Card", "ValU", "Fawry"
+ *   console.log(pm.category);    // "card", "bnpl", "kiosk", "wallet"
+ * });
+ * ```
+ */
+type PaymentMethodInfo = Required<Pick<PaymentMethodTypeResponseDto, "type" | "displayName">> & {
+  /** Payment method category for grouping in UI */
+  category: "card" | "bnpl" | "kiosk" | "wallet";
+  /** Icon URL for the payment method */
+  icon?: string;
+  /** Description of the next step (e.g., "You will be redirected to complete payment") */
+  nextActionText?: string;
+};
+/**
+ * Appearance overrides for the checkout UI.
+ * Merged with the session's server-side `brandingSettings`.
+ *
+ * @example
+ * ```ts
+ * const elements = xpay.elements({
+ *   clientSecret,
+ *   appearance: {
+ *     colorMode: "dark",
+ *     borderStyle: "rounded",
+ *     inputStyle: "outlined",
+ *   },
+ * });
+ * ```
+ */
+type Appearance = Pick<BrandingSettingsResponseDto, "colorMode" | "borderStyle" | "spacing" | "inputSize" | "inputStyle" | "formLayout" | "colors" | "fontFamily">;
+/**
+ * Structured session status — tagged union for exhaustive checking.
+ *
+ * @example
+ * ```ts
+ * switch (checkout.status.type) {
+ *   case "open":     // ready for payment
+ *   case "expired":  // session timed out
+ *   case "complete": // payment completed — check paymentStatus
+ * }
+ * ```
+ */
+/**
+ * `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";
+} | {
+  type: "expired";
+} | {
+  type: "complete";
+  paymentStatus: CheckoutSessionResponseDtoPaymentStatus;
+};
+/**
+ * Checkout session data exposed to merchants.
+ *
+ * Contains everything needed to render a checkout UI: amounts, currency,
+ * available payment methods, line items, fees, and discounts.
+ *
+ * @example
+ * ```ts
+ * const state = useCheckout();
+ * if (state.type === "success") {
+ *   const { checkout } = state;
+ *   console.log(checkout.amountTotal);   // "10000" (in minor units)
+ *   console.log(checkout.currency);      // "EGP"
+ *   console.log(checkout.status.type);   // "open"
+ *   console.log(checkout.paymentMethods); // [{type: "card", ...}, ...]
+ * }
+ * ```
+ */
+type CheckoutSession = {
+  id?: string;
+  amountSubtotal?: number;
+  amountTotal?: number;
+  currency?: CheckoutSessionResponseDtoCurrency;
+  merchantName?: string | null;
+  livemode: boolean;
+  expiresAt?: string;
+  /** Structured session status */
+  status: SessionStatus;
+  /** Whether the session is ready for confirmation */
+  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?: SessionPresentmentDetailsDto | undefined;
+  /** Line items in the session */
+  lineItems?: LineItemDto[] | undefined;
+  /** Totals breakdown (subtotal, tax, shipping, etc.) */
+  totalDetails?: TotalDetailsResponseDto | undefined;
+  /** Fee breakdown (when feesPassThrough is enabled) */
+  fees?: FeesResponseDto | undefined;
+  /** Applied discounts / promotion codes */
+  discounts?: CheckoutDiscountResponseDto[] | undefined;
+};
+/** Line item in a checkout session */
+type CheckoutLineItem = LineItemDto;
+/** Totals breakdown (subtotal, tax, shipping, discount amounts) */
+type CheckoutTotalDetails = TotalDetailsResponseDto;
+/** Fee breakdown for pass-through fees */
+type CheckoutFees = FeesResponseDto;
+/** Applied discount / promotion code */
+type CheckoutDiscount = CheckoutDiscountResponseDto;
+/**
+ * Result of an action (confirm, promo, quantity update, etc.).
+ * Tagged union — check `result.type` to determine success or failure.
+ *
+ * @example
+ * ```ts
+ * const result = await checkout.applyPromotionCode("SAVE10");
+ * if (result.type === "success") {
+ *   console.log(result.session.amountTotal); // updated amount
+ * } else {
+ *   console.log(result.error.message); // "Invalid promotion code"
+ * }
+ * ```
+ */
+type ActionResult<E = XPayError> = {
+  type: "success";
+  session: CheckoutSession;
+} | {
+  type: "error";
+  error: E;
+};
+/**
+ * Unified error type for ALL SDK operations (Stripe-style).
+ *
+ * Same type for `confirm()`, `applyPromotionCode()`, `updateLineItemQuantity()`, etc.
+ * Payment-specific fields (`declineCode`, `adviceCode`, `chargeId`, `paymentMethod`) are
+ * `null` for non-payment errors.
+ *
+ * @example Payment decline:
+ * ```ts
+ * const result = await checkout.confirm({ customerDetails: { email } });
+ * if (result.type === "error") {
+ *   console.log(result.error.type);        // "card_error"
+ *   console.log(result.error.code);        // "card_declined"
+ *   console.log(result.error.declineCode); // "insufficient_funds"
+ *   console.log(result.error.adviceCode);  // "try_again_later"
+ *   console.log(result.error.message);     // "Your card has insufficient funds."
+ * }
+ * ```
+ *
+ * @example API error (promo code, quantity, session):
+ * ```ts
+ * const result = await checkout.applyPromotionCode("INVALID");
+ * if (result.type === "error") {
+ *   console.log(result.error.type);    // "invalid_request_error"
+ *   console.log(result.error.code);    // "promotion_code_not_found"
+ *   console.log(result.error.param);   // "promotionCode"
+ *   console.log(result.error.docUrl);  // "https://docs.xpay.app/api/errors#promotion_code_not_found"
+ *   console.log(result.error.message); // "No promotion code found for 'INVALID'"
+ * }
+ * ```
+ */
+interface XPayError {
+  /** Error category: "card_error" | "payment_method_error" | "invalid_request_error" | "api_error" | ... */
+  type: string;
+  /** Machine-readable error code: "card_declined" | "checkout_session_expired" | "promotion_code_not_found" | ... */
+  code: string | null;
+  /** Human-readable error message */
+  message: string;
+  /** Parameter that caused the error (e.g., "promotionCode", "quantity") — null for payment errors */
+  param?: string | null;
+  /** Documentation URL for this error code */
+  docUrl?: string | null;
+  /** Decline code — WHY it failed specifically ("insufficient_funds", "generic_decline") — null for non-payment errors */
+  declineCode?: string | null;
+  /** Retry advice ("try_again_later" | "do_not_try_again" | "confirm_card_data") — null for non-payment errors */
+  adviceCode?: string | null;
+  /** Failed charge ID — null for non-payment errors */
+  chargeId?: string | null;
+  /** Failed payment method ID — null for non-payment errors */
+  paymentMethodId?: string | null;
+  /** Payment method type ("card" | "valu" | "fawry") — null for non-payment errors */
+  paymentMethodType?: string | null;
+  /** Payment method snapshot at time of failure — null for non-payment errors */
+  paymentMethod?: Record<string, unknown> | null;
+}
+/**
+ * The XPay SDK instance returned by `loadXPay()`.
+ *
+ * @example
+ * ```ts
+ * import { loadXPay } from "@xpayeg/sdk";
+ *
+ * const xpay = await loadXPay("pk_test_xxx");
+ * const elements = xpay.elements({ clientSecret: "cs_test_abc_secret_xyz" });
+ * ```
+ */
+interface XPayInstance {
+  /**
+   * Create an Elements instance for custom checkout UI.
+   * Use with `PaymentElement` to render the payment form.
+   *
+   * @param options - Must include `clientSecret` from a checkout session
+   * @returns An Elements instance for creating and managing payment elements
+   */
+  elements(options: ElementsOptions): Elements;
+  /**
+   * Create a drop-in checkout modal or inline embed.
+   *
+   * @param options - Configuration including `clientSecret` and event handlers
+   * @returns A checkout instance with `open()`, `close()`, and `destroy()` methods
+   */
+  checkout(options: CheckoutOptions): CheckoutInstance;
+  /**
+   * Confirm a payment using the data collected by Elements.
+   *
+   * @param options - Must include `elements` and optionally `customerDetails`
+   * @returns Action result with the updated session on success, or an error
+   */
+  confirmPayment(options: ConfirmPaymentOptions): Promise<ActionResult>;
+  /**
+   * Initialize a checkout session — combines `elements()` with session data.
+   * Returns session data + action methods in a single call.
+   *
+   * @param options - Must include `clientSecret`
+   * @returns Session data merged with checkout action methods
+   */
+  initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
+}
+/**
+ * Options for creating an Elements instance from an existing checkout session.
+ *
+ * @example
+ * ```ts
+ * const elements = xpay.elements({
+ *   clientSecret: "cs_test_abc_secret_xyz",
+ *   appearance: { colorMode: "dark" },
+ *   locale: "ar",
+ * });
+ * ```
+ */
+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;
+  /** Only applicable in deferred mode. Session-first elements render the session's own payment method types, set when the session is created. */
+  paymentMethodTypes?: 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;
+  /**
+   * Restrict which payment method types the element renders (e.g. `["card"]`).
+   * Narrow-only: the list is intersected with the payment methods enabled for
+   * your account, so a type that is not enabled is never rendered. If nothing
+   * survives the intersection the element fails to load with a `loaderror`.
+   * Fixed for the element's lifetime. Omit to render every enabled method.
+   * The same values are passed as `paymentMethodTypes` when your server
+   * creates the session at pay time, so display and acceptance match.
+   */
+  paymentMethodTypes?: 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.
+ *
+ * A single Elements instance manages one embed iframe shared by all elements.
+ * Provides session management methods (promo codes, quantities, etc.) and
+ * element creation.
+ */
+interface Elements {
+  /** Create a PaymentElement (full payment method selector + card form) */
+  create(type: "payment", options?: PaymentElementOptions): PaymentElement;
+  /** Get an existing element by type, or null if not created */
+  getElement(type: "payment"): PaymentElement | null;
+  /** Fetch available payment methods for this session */
+  fetchPaymentMethods(): Promise<PaymentMethodInfo[]>;
+  /**
+   * Listen for the `ready` event — fires when the session is loaded and elements can render.
+   * If the session is already loaded, the handler fires immediately.
+   */
+  on(event: "ready", handler: (data: ElementsReadyEvent) => void): void;
+  /** Listen for session data changes (payment method selection, promo codes, fee updates, etc.) */
+  on(event: "change", handler: (session: CheckoutSession) => void): void;
+  /** Listen for session load failures (network errors, invalid client secret, API errors) */
+  on(event: "loaderror", handler: (data: ElementsLoadErrorEvent) => void): void;
+  /** Listen for unsolicited errors not triggered by a merchant action (e.g. session expired during fee recalculation, BIN detection failure) */
+  on(event: "error", handler: (error: XPayError) => void): void;
+  /** Listen for a custom event */
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  /** Remove an event handler */
+  off(event: string, handler: (...args: unknown[]) => void): void;
+  /** Apply a promotion code to the session */
+  applyPromotionCode(code: string): Promise<ActionResult>;
+  /** Remove the applied promotion code */
+  removePromotionCode(): Promise<ActionResult>;
+  /** Update a line item's quantity */
+  updateLineItemQuantity(args: {
+    lineItem: string;
+    quantity: number;
+  }): Promise<ActionResult>;
+  /** Validate all element fields before confirming — returns the selected payment method on success */
+  submit(): Promise<{
+    error?: XPayError;
+    selectedPaymentMethod?: string;
+  }>;
+  /** Re-fetch the session from the server to get the latest data */
+  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;
+}
+/** Fired when the session is loaded and elements are ready to render */
+interface ElementsReadyEvent {
+  /** The loaded checkout session data */
+  session: CheckoutSession;
+}
+/** Fired when the session fails to load */
+interface ElementsLoadErrorEvent {
+  /** Error category */
+  type: "invalid_request_error" | "api_error" | "network_error";
+  /** Human-readable error message */
+  message: string;
+  /** Machine-readable error code */
+  code?: string;
+  /** The parameter that caused the error */
+  param?: string;
+  /** Link to documentation about this error */
+  docUrl?: string;
+}
+/** Options for creating a PaymentElement */
+interface PaymentElementOptions {
+  /**
+   * How the element presents the payment method chooser.
+   *
+   * - `"accordion"` (default): a vertical list, one row per method, the
+   *   selected method's content expanding beneath its row. With exactly one
+   *   method the chooser disappears: a single non-card method shows a static
+   *   identity header (logo and name, no radio) above its content, while a
+   *   single card method renders the bare card form, since its fields
+   *   already identify it.
+   * - `"tabs"`: a grid of tiles that fills the row and wraps when the
+   *   methods no longer fit, with the selected method's content below it.
+   *   With exactly one method the tile grid disappears and
+   *   only the content renders, for pages whose own UI already shows the
+   *   method's logo and name (e.g. a per-gateway plugin row).
+   *
+   * Updatable after creation via `element.update({ layout })`.
+   */
+  layout?: "accordion" | "tabs";
+  /** Pre-select a specific payment method by type */
+  defaultPaymentMethod?: string;
+  /** Custom ordering of payment methods by type */
+  paymentMethodOrder?: string[];
+}
+/**
+ * Change event from a PaymentElement.
+ * Fires on payment method selection, card field changes, and session updates.
+ *
+ * @example
+ * ```tsx
+ * <PaymentElement
+ *   onChange={(event) => {
+ *     setPaymentReady(event.complete);
+ *     console.log("Selected method:", event.value.type);
+ *   }}
+ * />
+ * ```
+ */
+interface PaymentElementChangeEvent {
+  elementType: "payment";
+  /** Whether all card fields are empty (no user input yet) */
+  empty: boolean;
+  /** Whether the form is complete and ready for submission */
+  complete: boolean;
+  /** Whether the payment method selector is collapsed (no method selected) */
+  collapsed: boolean;
+  /** The currently selected payment method */
+  value: {
+    type: string;
+  };
+  /** Full session data including updated amounts, fees, and discounts */
+  session: CheckoutSession;
+}
+/** Base interface shared by all element types */
+interface BaseElement {
+  /** Mount the element into a DOM container (CSS selector or HTMLElement) */
+  mount(container: string | HTMLElement): void;
+  /** Unmount the element from the DOM (can be re-mounted later) */
+  unmount(): void;
+  /** Destroy the element and release all resources */
+  destroy(): void;
+  /** Programmatically focus the element's iframe */
+  focus(): void;
+  /** Programmatically blur the element's iframe */
+  blur(): void;
+  /** Fired when the element is mounted and the iframe content is ready */
+  on(event: "ready", handler: () => void): void;
+  /** Fired when the element's iframe starts loading */
+  on(event: "loaderstart", handler: () => void): void;
+  /** Fired when the element fails to load */
+  on(event: "loaderror", handler: (event: ElementsLoadErrorEvent) => void): void;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler: (...args: unknown[]) => void): void;
+}
+/**
+ * The subset of `PaymentElementOptions` that can be updated after creation
+ * (Stripe's `StripePaymentElementUpdateOptions` pattern). Only `layout` is
+ * updatable; `defaultPaymentMethod` and `paymentMethodOrder` are set at
+ * creation.
+ */
+type PaymentElementUpdateOptions = Pick<PaymentElementOptions, "layout">;
+/** PaymentElement — full payment method selector with card form */
+interface PaymentElement extends BaseElement {
+  /** Collapse the payment method selector (deselect all methods) */
+  collapse(): void;
+  /** Update element options at runtime — see {@link PaymentElementUpdateOptions} */
+  update(options: PaymentElementUpdateOptions): void;
+}
+/**
+ * Options for `confirmPayment()` or `checkout.confirm()`.
+ *
+ * The `redirect` option controls what happens after a successful payment:
+ * - `"if_required"` (default) — returns the result to your code
+ * - `"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
+ * // Default: get the result back in code
+ * const result = await checkout.confirm({
+ *   customerDetails: { email: "user@example.com" },
+ * });
+ *
+ * // Always redirect to the session's own destination after payment
+ * await checkout.confirm({ redirect: "always" });
+ * ```
+ */
+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 */
+  customFields?: Record<string, string | number | boolean>;
+  /** Device fingerprint for fraud detection */
+  deviceFingerprint?: {
+    visitorId: string;
+    confidence?: number;
+  };
+  /** Override the selected payment method type */
+  paymentMethod?: string;
+  /**
+   * 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 the session's `afterCompletion.redirect.url` after payment. The page navigates away and the function never returns on success.
+   */
+  redirect?: "if_required" | "always";
+}
+/**
+ * Options for creating a drop-in checkout instance.
+ *
+ * @example
+ * ```ts
+ * const checkout = xpay.checkout({
+ *   clientSecret: "cs_test_abc_secret_xyz",
+ *   mode: "modal",
+ *   onComplete: (result) => console.log("Paid!", result.paymentIntentId),
+ * });
+ * checkout.open();
+ * ```
+ */
+interface CheckoutOptions {
+  /** Client secret from a checkout session */
+  clientSecret: string;
+  /** Display mode — `"modal"` (overlay) or `"inline"` (embedded in page) */
+  mode?: "modal" | "inline";
+  /** Container for inline mode (CSS selector or HTMLElement) */
+  container?: string | HTMLElement;
+  /** Called when the payment completes successfully */
+  onComplete?: (result: CheckoutCompleteResult) => void;
+  /** Called when the checkout UI is closed */
+  onClose?: () => void;
+  /** Called when the session is loaded and the checkout is ready */
+  onReady?: (session: CheckoutSession) => void;
+  /** Called when the payment is confirmed (before final result) */
+  onConfirmed?: () => void;
+  /** Called when an error occurs */
+  onError?: (error: CheckoutError) => void;
+  /** Appearance overrides */
+  appearance?: Appearance;
+  /** Locale for the checkout UI */
+  locale?: "en" | "ar";
+}
+/** Drop-in checkout instance with lifecycle control */
+interface CheckoutInstance {
+  /** Open the checkout modal (only for `mode: "modal"`) */
+  open(): void;
+  /** Close the checkout UI */
+  close(): void;
+  /** Destroy the checkout instance and clean up resources */
+  destroy(): void;
+  on(event: "complete", handler: (result: CheckoutCompleteResult) => void): void;
+  on(event: "close", handler: () => void): void;
+  on(event: "ready", handler: (session: CheckoutSession) => void): void;
+  on(event: "confirmed", handler: () => void): void;
+  on(event: "error", handler: (error: CheckoutError) => void): void;
+  off(event: string, handler: (...args: unknown[]) => void): void;
+}
+/** 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) */
+  chargeId?: string;
+  /** Redirect URL from the session's afterCompletion settings */
+  redirectUrl?: string;
+}
+/** Error from the drop-in checkout */
+interface CheckoutError {
+  /** Human-readable error message */
+  message: string;
+  /** Machine-readable error code */
+  code?: string;
+}
+/**
+ * Options for `initCheckout()` — the modern single-call API.
+ *
+ * @example
+ * ```ts
+ * const checkout = await xpay.initCheckout({
+ *   clientSecret: "cs_test_abc_secret_xyz",
+ * });
+ * console.log(checkout.amountTotal);
+ * await checkout.confirm({ customerDetails: { email: "..." } });
+ * ```
+ */
+interface InitCheckoutOptions {
+  /** Client secret from a checkout session (string or Promise) */
+  clientSecret: string | Promise<string>;
+  /** Appearance overrides */
+  appearance?: Appearance;
+  /** Locale for the payment form */
+  locale?: "en" | "ar";
+}
+/** Result of `initCheckout()` — session data merged with action methods */
+type InitCheckoutResult = CheckoutSession & CheckoutActions;
+/**
+ * Action methods available on the checkout object.
+ * These are merged with `CheckoutSession` to form the `Checkout` type.
+ */
+interface CheckoutActions {
+  /**
+   * Confirm the payment.
+   *
+   * @param options - Customer details and redirect behavior
+   * @returns Action result with updated session on success, or an `XPayError`.
+   *   With `redirect: "always"`, the page navigates away on success (never returns).
+   *
+   * @example
+   * ```ts
+   * const result = await checkout.confirm({
+   *   customerDetails: { email: "user@example.com" },
+   * });
+   * if (result.type === "error") {
+   *   console.error(result.error.message);
+   * }
+   * ```
+   */
+  confirm(options?: Omit<ConfirmPaymentOptions, "elements">): Promise<ActionResult>;
+  /** Apply a promotion code to the session */
+  applyPromotionCode(code: string): Promise<ActionResult>;
+  /** Remove the applied promotion code */
+  removePromotionCode(): Promise<ActionResult>;
+  /** Update a line item's quantity */
+  updateLineItemQuantity(args: {
+    lineItem: string;
+    quantity: number;
+  }): Promise<ActionResult>;
+  /** Validate all fields before confirming — returns the selected payment method on success */
+  submit(): Promise<{
+    error?: XPayError;
+    selectedPaymentMethod?: string;
+  }>;
+  /** Re-fetch the session from the server */
+  fetchUpdates(): Promise<ActionResult>;
+  /** Update the appearance at runtime */
+  changeAppearance(appearance: Appearance): void;
+  /** Listen for session data changes */
+  on(event: "change", handler: (session: CheckoutSession) => void): void;
+  /** Listen for unsolicited errors (e.g. session expired during internal updates) */
+  on(event: "error", handler: (error: XPayError) => void): void;
+  /** Listen for a custom event */
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  /** Access the underlying Elements instance for element creation */
+  getElements(): Elements;
+}
+/** Customer details collected by the merchant's form */
+interface CustomerDetails {
+  /** Customer email address */
+  email?: string;
+  /** Customer full name */
+  name?: string;
+  /** Customer phone number */
+  phone?: string;
+  /** Billing details for the payment */
+  billingDetails?: {
+    name?: string;
+    email?: string;
+    phone?: string;
+    address?: Address;
+  };
+  /** Shipping details */
+  shipping?: {
+    name?: string;
+    phone?: string;
+    address?: Address;
+  };
+}
+/** Physical address */
+interface Address {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+  country?: string;
+}
+type XPayFactory = (publishableKey: string) => XPayInstance;
+declare global {
+  interface Window {
+    XPay?: XPayFactory;
+  }
+}
+/**
+ * Load the XPay SDK from CDN.
+ *
+ * Returns a promise that resolves to an XPayInstance with full TypeScript support.
+ * The SDK script is loaded once and cached — subsequent calls return the same instance.
+ *
+ * @param publishableKey - Your publishable API key (pk_test_... or pk_live_...)
+ *
+ * @example
+ * ```typescript
+ * import { loadXPay } from '@xpayeg/sdk';
+ *
+ * const xpay = await loadXPay('pk_test_xxx');
+ * const elements = xpay.elements({ clientSecret: 'cs_test_abc_secret_xyz' });
+ * ```
+ */
+export declare function loadXPay(publishableKey: string): Promise<XPayInstance | null>;
+export type { ActionResult, Address, Appearance, BaseElement, CheckoutActions, CheckoutCompleteResult, CheckoutDiscount, CheckoutError, CheckoutFees, CheckoutInstance, CheckoutLineItem, CheckoutOptions, CheckoutSession, CheckoutTotalDetails, ConfirmPaymentOptions, CustomerDetails, Elements, ElementsLoadErrorEvent, ElementsOptions, ElementsOptionsClientSecret, ElementsOptionsMode, ElementsReadyEvent, ElementsUpdateOptions, InitCheckoutOptions, InitCheckoutResult, PaymentElement, PaymentElementChangeEvent, PaymentElementOptions, PaymentMethodInfo, SessionStatus, XPayError, XPayInstance };