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
| Environment | CDN ({cdn_host}) | API ({api_host}) |
|---|---|---|
| Staging | pci-card-form.stg.geopagos.io | api.stg.geopagos.io |
| Production | Provided by Geopagos | Provided 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
| Browser | Minimum |
|---|---|
| Chrome / Edge | 89 |
| Firefox | 89 |
| 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
- Backend Integration — create session and charge
- Lifecycle Hooks —
onSubmit/onError - Security — what stays on your server vs the browser