Skip to main content

Embedding the component

How to mount the PCI Component from the CDN on your checkout page. The examples below match Hybrid (new card). Session modes, saved cards, and vault APIs are documented in Saved cards and modes — the mount contract is the same: your page only supplies a session_id.

Everything else the component needs — enabled payment methods, accepted card brands and every text the buyer reads — it gets from Geopagos, not from your page. That boundary is deliberate: a script on your checkout must not be able to influence how card data is protected.

Environments​

EnvironmentCDN ({cdn_host})API ({api_host})
Stagingpci-card-form.stg.geopagos.ioapi.stg.geopagos.io
ProductionProvided by GeopagosProvided by Geopagos

The entry point​

https://{cdn_host}/v1/main.js

That URL is the whole contract: hardcode it and nothing else. It always resolves the current version of the component, so a new release reaches your checkout without you touching the page.

Do not put an integrity attribute on it — that file changes on every release, so a fixed hash would break your integration on the next deploy.

Load and mount​

<div id="card-form-container"></div>

<script type="module">
const { Checkout, CheckoutError } = await import(
'https://{cdn_host}/v1/main.js'
);

// sessionId from YOUR BACKEND: POST /api/v1.0/sessions
const form = new Checkout(sessionId, {
onReady: () => {},
onSubmit: async () => {
// Intent succeeded (204). Your backend charges: POST /payment + X-Session-Id + Bearer JWT + email.
await fetch('/checkout/charge', { method: 'POST' });
},
onError: (error) => console.error(error.toJSON?.() ?? error),
});

await form.render('card-form-container');
</script>

Constructor: new Checkout(sessionId, options) — the first argument is the string id, not an options object. Options and methods are documented under Configuration; the callbacks under Lifecycle Hooks.

The <script> must be type="module": the component is distributed as ESM and loaded with a dynamic import().

render() and unmount()​

await form.render('card-form-container');  // by id
await form.render(containerElement); // by element
form.unmount();

Store the instance before await render() so a failed mount does not lose the reference:

const form = new Checkout(sessionId, options);
saveInstance(form); // keep it wherever your page keeps it
await form.render(container);

render() can be called again after unmount(). Mounting over an instance that is still mounted is an error (RENDER_FAILED): unmount first.

There is a stronger guarantee for when that is not respected: a container cannot end up with two forms. Mounting into a container that already holds one from another instance unmounts that one and warns on the console. The warning means an unmount() is missing somewhere.

After a successful submit the component unmounts itself and hands you back an empty container, so you do not need unmount() to draw your success screen — see onSubmit. Mounting again requires a new session.

Payment method list​

When the merchant has more than one payment method enabled, the component lists them first and mounts the one the buyer picks. With a single method enabled it mounts that one directly. Controlled by selector.

Which methods are available is decided by the merchant's configuration, not by your snippet — so enabling a new one does not require touching your integration.

TypeScript​

There is no npm package, so TypeScript cannot resolve the types on its own. A declarations file is published next to each version of the component: download it once and declare the module.

curl -O https://{cdn_host}/v1/<version>/pci-card-form.d.ts
// types/checkout.d.ts
declare module 'https://*/v1/main.js' {
export * from './pci-card-form';
}

Browser support​

BrowserMinimum
Chrome / Edge89
Firefox89
Safari (macOS / iOS)15

HTTPS is required. Card data is encrypted in the browser, and the encryption API only exists in a secure context. On plain http:// — testing against a local network IP, for instance — the payment cannot complete. localhost counts as a secure context, so local development works.

On Safari below 15.4 the payment method list has minor cosmetic differences. None of them prevents paying.

Next steps​

  1. Backend Integration — create session and charge
  2. Lifecycle Hooks — onSubmit / onError
  3. Security — what stays on your server vs the browser