@xpayeg/sdk

The XPay JavaScript SDK is a tiny CDN-loaded library that gives you a typed XPayInstance from your publishable key. From there you can mount payment UI as Elements, open a drop-in checkout, or run a single-call initCheckout and confirm a payment.

pnpm add @xpayeg/sdk
# or: npm install @xpayeg/sdk / yarn add @xpayeg/sdk

The package ships ESM and CJS builds, plus full TypeScript types. The runtime itself is loaded on demand from https://checkout.xpay.app/v1/sdk.js.

There are two ways to load the SDK, and they expose the factory under different names. This is the single most common integration mistake, so get it right up front:

// Import loadXPay and await it. This is the path the rest of this page documents.
import { loadXPay } from "@xpayeg/sdk";

const xpay = await loadXPay("pk_test_...");

<!-- Drop the CDN script tag, then call the global XPay() factory the runtime
     puts on window. No import, no await, no build step. -->
<script src="https://checkout.xpay.app/v1/sdk.js"></script>
<script>
  const xpay = XPay("pk_test_...");
</script>

loadXPay exists only in the npm package; the CDN runtime exposes only the global XPay. They are not interchangeable: calling loadXPay(...) after a script tag throws ReferenceError: loadXPay is not defined, and the global XPay isn't importable. Pick the row that matches your setup; everything after you obtain the xpay instance is identical. This page documents the npm entry point (loadXPay). On the plain-HTML path, swap await loadXPay(k) for XPay(k) in any example below.

This page is the reference for every public export. For walkthroughs, see Drop-in and Elements under Integrate.

Use this package when

@xpayeg/sdk is the vanilla SDK and is the right pick whenever you're not on React. That covers:

• Plain HTML and static sites (CDN script tag + the global XPay() factory; see the two load paths above).
• Vue, Svelte, Solid, Angular, Lit, Qwik, Astro, and any other framework. Call the SDK from inside that framework's component lifecycle (mount, onMount, useEffect equivalent, etc.).
• React Native via WebView until a native package ships.
• Server-side scripts that need to type their clientSecret payloads (the package's TypeScript types are framework-agnostic).

For React, @xpayeg/react is a thin convenience wrapper on top of this package. It builds on loadXPay, xpay.initCheckout, and xpay.elements, so anything you read here applies under the hood there too.

Quick start

The recommended path is loadXPay at module level, then xpay.initCheckout() once you have a clientSecret from your server.

import { loadXPay } from "@xpayeg/sdk";

// Module-level: call once, share across the app.
const xpayPromise = loadXPay("pk_test_...");

async function startCheckout() {
  const xpay = await xpayPromise;
  if (!xpay) return; // SSR returns null on the server

  // initCheckout accepts a Promise<string> too, so you can pass the fetch directly.
  const checkout = await xpay.initCheckout({
    clientSecret: fetch("/api/create-checkout", { method: "POST" })
      .then((r) => r.json())
      .then((d) => d.clientSecret as string),
  });

  // Mount the payment element.
  const elements = checkout.getElements();
  const paymentElement = elements.create("payment");
  paymentElement.mount("#payment-element");

  // Listen for state changes (promo codes, quantity updates, fee recalcs).
  checkout.on("change", (session) => {
    document.getElementById("total")!.textContent =
      `${session.currency} ${(session.amountTotal / 100).toFixed(2)}`;
  });

  // Confirm when the customer submits.
  document.getElementById("pay")!.addEventListener("click", async () => {
    const result = await checkout.confirm({
      customerDetails: { email: "customer@example.com", name: "Aya Hassan" },
    });
    if (result.type === "error") {
      console.error(result.error.message);
      return;
    }
    window.location.href = "/thank-you";
  });
}

Exports at a glance

loadXPay(publishableKey)

Loads the SDK runtime from CDN and returns an XPayInstance. Call this once at module level, not inside a component.

import { loadXPay } from "@xpayeg/sdk";

const xpayPromise = loadXPay("pk_test_...");
// later, when you have a clientSecret:
const xpay = await xpayPromise;
const elements = xpay.elements({ clientSecret: "cs_test_..." });

Returns Promise<XPayInstance | null>. null is returned during server-side rendering (no window). The XPayProvider from @xpayeg/react handles null gracefully by retrying on the client.

The runtime is fetched once; subsequent loadXPay calls reuse the same script tag. If a script with sdk.js is already on the page, it isn't re-injected.

XPayInstance

The factory you get back from loadXPay. Four methods.

interface XPayInstance {
  elements(options: ElementsOptions): Elements;
  checkout(options: CheckoutOptions): CheckoutInstance;
  confirmPayment(options: ConfirmPaymentOptions): Promise<ActionResult>;
  initCheckout(options: InitCheckoutOptions): Promise<InitCheckoutResult>;
}

elements(options)

Creates an Elements instance for custom checkout UI. Pass it the clientSecret from a Checkout Session.

const elements = xpay.elements({
  clientSecret: "cs_test_...",
  appearance: { colorMode: "dark", borderStyle: "rounded" },
  locale: "en",
});

ElementsOptions accepts one of two forms. Session-first, with a clientSecret:

Or deferred, with no session yet:

const elements = xpay.elements({
  mode: "payment",
  amount: 149900, // minor units
  currency: "EGP",
});

The two forms are mutually exclusive. In deferred mode your server creates the session when the customer pays, and you pass its clientSecret to confirmPayment({ elements, clientSecret }). The session total must equal the displayed amount, or the payment is refused with amount_reconfirmation_required and nothing is charged. See Elements: deferred mode.

checkout(options)

Creates a drop-in checkout instance. See CheckoutOptions below.

confirmPayment(options)

Submits a payment using the data collected by Elements. See ConfirmPaymentOptions below.

initCheckout(options)

Modern single-call API: returns the session data and action methods together. See InitCheckoutOptions below.

Elements

Returned by xpay.elements(). Manages one shared payment iframe and exposes session-mutation methods.

interface Elements {
  create(type: "payment", options?: PaymentElementOptions): PaymentElement;
  getElement(type: "payment"): PaymentElement | null;
  fetchPaymentMethods(): Promise<PaymentMethodInfo[]>;

  on(event: "ready" | "change" | "loaderror" | "error", handler): void;
  off(event: string, handler): void;

  applyPromotionCode(code: string): Promise<ActionResult>;
  removePromotionCode(): Promise<ActionResult>;
  updateLineItemQuantity(args: { lineItem: string; quantity: number }): Promise<ActionResult>;
  submit(): Promise<{ error?: XPayError; selectedPaymentMethod?: string }>;
  fetchUpdates(): Promise<ActionResult>;
  changeAppearance(appearance: Appearance): void;
  update(options: ElementsUpdateOptions): Promise<void>;
  destroy(): void;
}

Events

Methods

• create("payment", options?): returns a PaymentElement you can mount. options.layout picks the chooser presentation, see Layout.
• getElement("payment"): returns the existing element or null if none was created.
• fetchPaymentMethods(): returns the list of PaymentMethodInfo the session supports.
• applyPromotionCode(code): applies a promotion code, returns ActionResult.
• removePromotionCode(): removes the applied code, returns ActionResult.
• updateLineItemQuantity({ lineItem, quantity }): updates a line item, returns ActionResult.
• submit(): validates element fields. Returns either an error or the selectedPaymentMethod type string.
• fetchUpdates(): re-fetches the session from the server and resolves with the fresh session data. Use it after a server-side session change.
• changeAppearance(appearance): updates branding at runtime without recreating elements.
• update({ amount, currency }): deferred mode only. Updates the displayed amount when your cart total changes. Throws on instances created with a clientSecret; session amounts are server-owned.
• destroy(): tears down the instance and frees resources.

PaymentElement

The full payment-method selector with the card form, BNPL, kiosk, and wallet methods. Get one from elements.create("payment").

interface PaymentElement {
  mount(container: string | HTMLElement): void;
  unmount(): void;
  destroy(): void;
  focus(): void;
  blur(): void;
  collapse(): void;
  update(options: { layout?: "accordion" | "tabs" }): void;

  on(event: "ready" | "loaderstart" | "loaderror", handler): void;
  off(event: string, handler): void;
}

Layout

elements.create("payment", { layout }) controls how the element presents the payment method chooser:

• "accordion" (default): a vertical list, one row per method, with the selected method's form expanding under its row. With exactly one method the chooser disappears and the element shows a static header (logo and name, no radio) above the content. Card is the exception: its form fields already identify the method, so a single card method renders the bare form.
• "tabs": a grid of tiles with the selected method's form below it. Tiles share each row equally and wrap to a new row when they no longer fit, so every method stays visible. With exactly one method the tile grid disappears and only the content renders. Use this when your own page already shows the method's logo and name, for example a per-gateway row in a plugin checkout.

const paymentElement = elements.create("payment", { layout: "tabs" });

Layout is updatable after creation with paymentElement.update({ layout: "accordion" }). Both layouts keep every method's form mounted, so a typed card number survives switching methods and back.

PaymentElementChangeEvent is the payload for the parent Elements "change" event when triggered by a payment-method change:

ConfirmPaymentOptions

Shape passed to xpay.confirmPayment() and checkout.confirm().

redirect semantics:

• "if_required" returns the result to your code; only redirects when the payment method requires it (e.g. 3-D Secure, BNPL).
• "always" always redirects to the session's afterCompletion.redirect.url after payment. The page navigates away and the function never returns on success.

The destination is the session's afterCompletion.redirect.url, set when your server creates the session. XPay navigates to it unchanged.

In deferred mode, the session total must equal the amount the element displays. A different total fails the confirmation with amount_reconfirmation_required and nothing is charged: update the element's amount and confirm again.

On retries, pass the same clientSecret: one session per checkout keeps the whole transaction lifecycle on one Payment Intent. If the total changed, your server updates the existing session first. Create a fresh session only when the previous one died, which the confirm reports as checkout_session_expired. See Elements: retries.

CheckoutOptions

Configuration for the drop-in xpay.checkout().

CheckoutInstance

Returned by xpay.checkout(). Imperative handle.

interface CheckoutInstance {
  open(): void; // modal mode
  close(): void;
  destroy(): void;
  on(event: "complete" | "close" | "ready" | "confirmed" | "error", handler): void;
  off(event: string, handler): void;
}

CheckoutCompleteResult (the payload for onComplete):

InitCheckoutOptions

Modern single-call API. Combines elements() with session loading and exposes session data plus action methods on a single object.

const checkout = await xpay.initCheckout({ clientSecret: "cs_test_..." });
console.log(checkout.amountTotal); // session field
const result = await checkout.confirm({ customerDetails: { email } });

InitCheckoutResult is CheckoutSession & CheckoutActions. The action methods on CheckoutActions:

CheckoutSession (data type)

Session data exposed to the merchant. Derived from the server's response, trimmed to the merchant-facing fields.

presentmentDetails

Present only when the store prices in a currency other than the processing currency. It carries the customer-facing amounts: amountTotal, amountSubtotal, amountDiscount, currency, and the locked exchange rate. Read amounts presentment-first: use presentmentDetails.amountTotal and presentmentDetails.currency when the field is present, the top-level amountTotal and currency otherwise.

SessionStatus:

type SessionStatus =
  | { type: "open" }
  | { type: "expired" }
  | { type: "complete"; paymentStatus: "paid" | "unpaid" | "no_payment_required" };

PaymentMethodInfo:

ActionResult and XPayError

Every action that mutates the session returns an ActionResult. It's a tagged union, so narrow by result.type before reading the payload.

type ActionResult<E = XPayError> =
  | { type: "success"; session: CheckoutSession }
  | { type: "error"; error: E };

XPayError is the unified error shape. Payment-specific fields are null for non-payment errors.

For a guide on handling API errors and the three error code spaces, see Errors, API error codes, Payment error codes, and Decline codes.

Appearance

Branding overrides for the embedded UI. Mirrors a subset of the merchant-default fields you set in Branding settings.

Pass an Appearance to xpay.elements(), xpay.checkout(), or xpay.initCheckout(). Or call elements.changeAppearance() / checkout.changeAppearance() to update at runtime.

CustomerDetails and Address

Shapes for customer fields you collect on your form and pass at confirm time.

interface CustomerDetails {
  email?: string;
  name?: string;
  phone?: string;
  billingDetails?: { name?: string; email?: string; phone?: string; address?: Address };
  shipping?: { name?: string; phone?: string; address?: Address };
}

interface Address {
  line1?: string;
  line2?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

For the developer-side cross-reference on what each Checkout Session field controls (collection toggles, custom fields, prefill priority), see Customer lifecycle.

Where to next