Elements SDK

@ozura/elements is Ozura’s browser SDK for embedding secure payment input fields in your own UI. Each field runs in an isolated iframe hosted at elements.ozura.com — raw card and bank data never exist in your JavaScript bundle, your DOM, or your server logs.

Key Concepts

Isolated iframes

Every element (card number, CVV, account number, etc.) is rendered inside a cross-origin iframe. Your page can style and position the iframe, but it cannot read the value inside it. Only the Ozura tokenizer — also running in a same-origin iframe — can access the raw data.

Tokenizer frame

A hidden <iframe> is mounted alongside your input elements. When you call createToken() or createBankToken(), the input frames pass their values to the tokenizer frame via postMessage, and the tokenizer frame POSTs directly to the Vault API. You receive a token — never the raw data.

PCI scope reduction

Because sensitive data never reaches your JavaScript or your server, your PCI DSS surface area is significantly reduced. You only handle vault tokens.

Package Details


Package name	`@ozura/elements`
npm	`npm install @ozura/elements`
CDN (ESM)	`https://elements.ozura.com/oz-elements.esm.js`
CDN (UMD)	`https://elements.ozura.com/oz-elements.umd.js`
React entrypoint	`@ozura/elements/react`
TypeScript	Full type definitions included

What’s in the Box

Export	Description
`OzVault`	Main SDK class. Manages elements, the tokenizer frame, and credentials.
`OzElement`	Returned by `createElement()` and `createBankElement()`. Exposes `.mount()`, `.on()`, `.destroy()`, etc.
`OzError`	Error class thrown by `createToken()` and `createBankToken()`. Has `.message` and `.errorCode`.
`normalizeCardSaleError`	Utility to map vault error strings to user-friendly messages.
`OzElements`	React context provider (from `@ozura/elements/react`).
`useOzElements`	React hook for `createToken`, `ready` state, and element access (from `@ozura/elements/react`).
`OzCardNumber`, `OzExpiry`, `OzCvv`	Pre-built React card field components (from `@ozura/elements/react`).
`OzCard`	Combined card component rendering all three card fields (from `@ozura/elements/react`).