@selcom/selcom-js

Browser drop-in for the Selcom Payments embedded checkout, with the same ergonomics as Stripe.js. One <script> tag, one Selcom(pk).mount(...) call, and you have a fully PCI-scoped checkout iframe in your page.

Install

From the CDN (recommended)

<script src="https://js.selcom.com.na/v1/selcom.js" async></script>
<script>
  document.addEventListener('DOMContentLoaded', async () => {
    const session = await fetch('/api/create-selcom-session', { method: 'POST' })
      .then((r) => r.json());

    const selcom = window.Selcom('pk_test_…');
    selcom.mount('#selcom-checkout', {
      sessionId: session.sessionId,
      appearance: { theme: 'light', primaryColor: '#FF6B00' },
      onSuccess(event) {
        window.location.href = `/orders/${event.reference}/thanks`;
      },
      onError(event) {
        console.warn('Selcom error', event);
      },
    });
  });
</script>
<div id="selcom-checkout"></div>

The CDN URL is versioned:

| URL | What it pins | |------------------------------------------------|---------------------------------------| | https://js.selcom.com.na/v1/selcom.js | Latest 1.x (auto-patches) | | https://js.selcom.com.na/v1.0.0/selcom.js | Exact 1.0.0 | | https://js.selcom.com.na/canary/selcom.js | Pre-release (do not use in prod) |

From npm

npm install @selcom/selcom-js
# or
pnpm add @selcom/selcom-js

import Selcom from '@selcom/selcom-js';

const selcom = Selcom(import.meta.env.VITE_SELCOM_PK!);
selcom.mount('#checkout', {
  sessionId,
  onSuccess: (e) => router.push(`/orders/${e.reference}`),
});

Why a CDN drop-in?

• PCI scope contained to Selcom. The card form lives in our iframe, not your DOM, so you stay out of PCI-DSS SAQ-D scope and into SAQ-A.
• Fast first paint. ~6 kB gzipped, deterministic, cached at edge.
• Always patchable by us. Browser quirks, 3DS protocol changes, and fraud heuristics can ship without a redeploy on your side.

API reference

Selcom(publishableKey, options?) → SelcomInstance

Creates a configured client. The publishable key (pk_test_* / pk_live_*) is safe to ship in client code.

options.iframeOrigin lets you override the hosted checkout origin (useful for self-hosted previews).

instance.mount(container, options)

Renders the checkout iframe into a container element (CSS selector or HTMLElement) and returns a handle:

interface SelcomMountedInstance {
  unmount(): void;                       // tear down the iframe
  element(): HTMLIFrameElement | null;   // get the underlying iframe
}

Mount options:

interface MountOptions {
  sessionId: string;
  appearance?: {
    theme?: 'light' | 'dark' | 'auto';
    primaryColor?: string;
    borderRadius?: 'none' | 'small' | 'medium' | 'large';
    locale?: string;
  };
  returnUrl?: string;
  onReady?: () => void;
  onSuccess?: (event: SelcomSuccessEvent) => void;
  onError?: (event: SelcomErrorEvent) => void;
  onClose?: () => void;
  onEvent?: (event: SelcomEvent) => void;
}

Build & release

pnpm install
pnpm --filter @selcom/selcom-js build
ls packages/selcom-js/dist
# selcom.js        — IIFE (browser global)
# selcom.esm.js    — ESM
# selcom.cjs.js    — CommonJS
# *.d.ts           — TypeScript declarations

CDN deployment is described in scripts/deploy-cdn.md.

Versioning

Follows semver. Major versions get their own CDN path so existing integrations never break on a routine deploy. The v1 alias always points at the latest 1.x patch.