@shoppexio/checkout-js

Official JavaScript SDK for embedding Shoppex hosted checkout as a modal on any website.

Install

npm install @shoppexio/checkout-js

Vanilla JS

import { open, on } from '@shoppexio/checkout-js';

on((event) => {
  if (event.type === 'success') console.log('Paid', event.payload?.invoiceId);
});

document.querySelector('#buy')?.addEventListener('click', () => {
  void open({
    shopId: 'your-shop',
    items: [{ productId: 'PROD_123', quantity: 1 }],
    theme: 'auto',
    locale: 'de',
    returnUrl: 'https://your-site.com/thanks',
  });
});

React

import { ShoppexCheckout } from '@shoppexio/checkout-js/react';

export default function BuyButton() {
  return (
    <ShoppexCheckout
      shopId="your-shop"
      items={[{ productId: 'PROD_123', quantity: 1 }]}
      locale="de"
      onSuccess={(invoiceId) => console.log('paid', invoiceId)}
      trigger={<button>Buy now</button>}
    />
  );
}

Headless (build your own checkout UI)

For full control of the checkout step on your own domain, use the headless primitives. You build every pixel; Shoppex runs the invoice, payment session, webhooks, and fulfillment. Add your site's origin under Dashboard → Checkout → Headless and use your publishable key (pk_live_…).

import {
  ShoppexCheckoutProvider,
  useCheckoutSession,
  useStripePaymentSession,
  ShoppexPoweredBy,
} from '@shoppexio/checkout-js/headless';

function Checkout() {
  const { session } = useCheckoutSession({ product_id: 'PROD_123', email });
  const stripe = useStripePaymentSession(session?.id, {
    returnUrl: 'https://your-site.com/thanks',
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); stripe.confirm(); }}>
      {/* your layout, your styles */}
      <div ref={stripe.mountRef} />
      <button disabled={!stripe.ready}>Pay</button>
      <ShoppexPoweredBy />
    </form>
  );
}

export default function App() {
  return (
    <ShoppexCheckoutProvider publishableKey="pk_live_…">
      <Checkout />
    </ShoppexCheckoutProvider>
  );
}

Render against the session kind (embed | redirect | address | balance | manual), not the provider name — that keeps redirect and crypto gateways provider-independent. Stripe is supported first; more embed gateways arrive in waves. Card fields are always provider iframes (Stripe.js / Elements) — Shoppex never touches the PAN.

<ShoppexPoweredBy /> is required. The SDK refuses to confirm a payment unless a visible "Powered by Shoppex" badge is on the page (the requirement is server-controlled; white-label is a separate entitlement). It is not a decorative opt-in — leave it in your checkout.

Framework-agnostic client (no React): import { HeadlessCheckoutClient } from '@shoppexio/checkout-js/headless'.

API

See docs.shoppex.io/guides/embeds for the modal API and docs.shoppex.io/checkout/headless for the headless session contract, CSP, and origin setup.