@x-money/checkout

The browser half of the X Money SDK: the Pay with X button, and the popup checkout flow behind it.

Zero runtime dependencies, no framework required.

npm install @x-money/checkout

Quick start

Sessions are created with your secret key, so that part stays on your server. The button calls your endpoint and takes it from there.

import { Checkout } from "@x-money/checkout";

const checkout = Checkout();

checkout
  .button({
    intent: "checkout",
    size: "lg",
    session: () =>
      fetch("/api/checkout", { method: "POST" })
        .then((r) => r.json())
        .then((s) => s.url),
    onSuccess: ({ sessionId }) => showPendingState(sessionId),
    onCancel: () => {},
    onError: (error) => handleError(error),
  })
  .mount(document.querySelector("#pay"));

Use @x-money/core on the server to create the session.

onSuccess means the customer finished checkout, not that you have been paid. Fulfill on the checkout_session_completed webhook and treat onSuccess as a cue to show a pending state.

The button

button() returns a handle with mount(target), update(props), and unmount(). Options are documented in full under Props; briefly, intent picks the copy from a closed set of sixteen, locale picks its language (the buyer's browser languages by default), and shape, size, theme, border, and width are independent appearance axes.

The button renders into a shadow root, so page CSS cannot restyle it. It sets state to "loading" while a checkout is in flight, which also blocks clicks so a second one cannot open a second popup.

unmount() stops the SDK listening but deliberately does not close a popup the customer is still paying in.

The flow on its own

If you want the payment without the button, checkout.start() is the same flow with no UI.

import { Checkout } from "@x-money/checkout";

const checkout = Checkout();

const handle = checkout.start({
  session: () => createSessionOnMyServer(),
  onSuccess: ({ sessionId }) => showPendingState(sessionId),
  onCancel: () => resetMyButton(),
  onError: (error) => handleError(error),
});

handle.cancel(); // stop observing, without closing the popup

Call it directly inside your click handler. It opens the popup synchronously before awaiting anything, which is what keeps popup blockers from killing it.

Errors

onError receives an XMoneyCheckoutError. Its code is one of no_browser (called during a server render), session_failed (your session callback rejected; the rejection is on cause), or invalid_session_url (the callback resolved to something the popup cannot navigate to). None of them mean a payment failed: a declined payment stays in the popup for the customer to retry, and an abandoned one arrives as onCancel.

The package ships a source map with the TypeScript sources embedded, so browser devtools show stack traces against the original source. If your bundler emits its own source maps, have it read the ones in your dependencies too (webpack needs source-map-loader for that).

Account exchanges

session also accepts an account exchange url, for when the customer authorizes future charges instead of paying now. onSuccess then receives { exchangeId } rather than { sessionId }, and a customer who declines closes the popup, which arrives as onCancel. Read the minted customer_id and account_ids from the account_exchange_setup_succeeded webhook.

Popup mode requirements

The popup can only report back to your page when your page is served over https and its origin (scheme, host, and port) exactly matches the origin of the session's success_url or failure_url. Otherwise the payment still completes, but the popup redirects to success_url, onSuccess never fires, and closing the popup calls onCancel. A Cross-Origin-Opener-Policy: same-origin header on your page has the same effect.

Pass debug: true while you integrate to get console warnings, prefixed [XMoney], for the cases the SDK can detect. It is off by default so the SDK never writes to your console unasked.

What it handles

• Popup blockers. Browsers block popups opened after an await, which is exactly what creating a session on click requires. The window is opened blank and synchronously, then navigated when the URL arrives.
• Mobile. Redirects rather than opening a popup, so the /i/money/checkout universal link can open the X app.
• Blocked popups. Falls back to a full-page redirect.
• Cancellation. A customer who closes the popup sends no signal, so the closed window is watched for and reported as a cancel.
• Result validation. A result is accepted only from the checkout origin, only from the window that was opened, and only when it carries the expected marker. onSuccess fires exactly once.

Theming

theme="auto" renders dark on light surfaces and light on dark ones, following prefers-color-scheme by default. Chromium-based browsers will follow a .dark ancestor class instead where one is present; Safari and Firefox do not implement the selector that makes that work, so they stay on the OS preference.

That difference is visible rather than merely unsupported: a site in light mode by class, viewed on a machine set to dark, gets the dark button in those browsers. Pass theme="light" or theme="dark" when the tone has to be guaranteed.

Documentation

The full guide, every intent and variant, and a live playground are under Checkout in the X Money docs.

To have an AI coding agent collect a payment with this package:

npx skills add https://xmoney.mintlify.site/docs

Support

Report bugs and ask questions through the X Help Center. Security issues go through the same form; please do not post them publicly.

License

MIT. The full text ships in the package as LICENSE.