@glomopay/secure-elements-sdk

Cross-origin iframe fields for collecting card data. The SDK mounts hardened, sandboxed iframes served from a Glomopay-controlled origin; card data never touches the host page's DOM or JavaScript.

The package is published publicly to the npm registry under the @glomopay scope.

Install

pnpm add @glomopay/secure-elements-sdk
# or: npm install / yarn add

No registry configuration or authentication is required.

Usage

import { SecureElementsClient, ELEMENT_TYPE } from '@glomopay/secure-elements-sdk';

const client = new SecureElementsClient({ environment: 'production' });

const container = client.getElementsContainer();
const cardNumber = container.createElement({
  type: ELEMENT_TYPE.cardNumber,
  onChange: (state) => console.log(state.isValid),
});
cardNumber.mount('#card-number');

// later
client.destroy();

Environments

The iframe host is compiled in and selected by environment; callers pick from a fixed set and can never supply an arbitrary origin (this is what keeps the postMessage trust anchor intact).

| environment | Host | | ------------- | -------------------------------- | | production | production secure-elements host | | staging | staging secure-elements host | | development | development secure-elements host |

Every host is compiled in from a build-time env var (VITE_SECURE_ELEMENTS_HOST_STAGING, VITE_SECURE_ELEMENTS_HOST_PRODUCTION, VITE_SECURE_ELEMENTS_HOST_DEVELOPMENT); selecting an environment whose host is unset throws. development conventionally points at the portless alias secure-elements (https://secure-elements.localhost).

API

• new SecureElementsClient({ environment }) — injects a hidden controller iframe and starts the inbound message gate. Must run in a browser.
• client.getElementsContainer() — the client's single ElementsContainer.
• container.createElement({ type, onChange?, onFocus?, onBlur?, onExternalErrorChange? }) — returns an IframeElement.
• element.mount(selector) / element.unmount().
• element.setError(message) / element.clearError().
• client.destroy() — tears down every iframe and stops the listener.