@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 atDocumentation Index
Fetch the complete documentation index at: https://docs.ozura.com/llms.txt
Use this file to discover all available pages before exploring further.
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 payment field (card number, CVV, account number, etc.) renders inside a cross-origin iframe hosted by Ozura. Your page controls the layout and styling, but cannot read the raw value inside. Sensitive data never touches your JavaScript or your server.Secure tokenization
When you callcreateToken() or createBankToken(), the SDK securely transmits the field values directly to the Ozura Vault API. Your code receives a vault token — never the raw card or bank data.
Session key
A short-lived credential created by your server for each checkout session. Point the SDK at your session endpoint viasessionUrl and the SDK handles the rest — your server exchanges the session ID for a key from the vault using your private vault key. The vault key never goes to the browser.
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.Bank tokens can be passed to any ACH-capable processor. Card tokens include a
cvcSession required by Ozura Pay for charging. If you are routing card payments to a different processor, use the token field directly — your processor’s documentation will tell you whether CVC vaulting is required. The cvcSession is enforced by the SDK on success, so if your processor does not need it, simply ignore it.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 |
| Server entrypoint | @ozura/elements/server |
| TypeScript | Full type definitions included |
What’s in the Box
| Export | Description |
|---|---|
OzVault | Main SDK class. Manages payment fields, tokenization, and session credentials. Use OzVault.create() (async static factory). |
OzElement | Returned by createElement() and createBankElement(). Exposes .mount(), .on(), .update(), .destroy(), etc. |
OzError | Error class thrown by createToken(), createBankToken(), OzVault.create(), and element methods such as mount(). Has .message, .errorCode, .raw, and .retryable. |
createSessionFetcher | Helper that creates a getSessionKey callback for a given backend URL. Used internally by sessionUrl — you typically won’t need this directly. |
normalizeVaultError | Maps raw vault /tokenize errors to user-friendly messages (card flows). |
normalizeBankVaultError | Maps raw vault /tokenize errors to user-friendly messages (bank/ACH flows). |
normalizeCardSaleError | Maps raw PayAPI cardSale errors to user-friendly messages. |
OzElements | React context provider (from @ozura/elements/react). |
useOzElements | React hook for createToken, createBankToken, ready state, initError, and tokenizeCount (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). |
OzBankAccountNumber, OzBankRoutingNumber | Pre-built React bank field components (from @ozura/elements/react). |
OzBankCard | Combined bank component rendering both bank fields (from @ozura/elements/react). |
Ozura | Server-side SDK class for card sales, transaction queries, and session creation (from @ozura/elements/server). |
OzuraError | Error class thrown by server SDK methods (from @ozura/elements/server). |
getClientIp | Extract client IP from Express, Fastify, Next.js, or Node.js requests (from @ozura/elements/server). |
SDK Pages
Installation
npm, yarn, CDN. TypeScript setup.
Card Elements
createElement(), createToken(), field types, events.
Bank Elements
createBankElement(), createBankToken(), ACH tokenization.
React
OzElements provider, hooks, pre-built components.
Styling
Style config, supported properties, global appearance.
Error Handling
OzError, errorCode values, retry guidance.
Server SDK
Process payments and query transactions on your backend.
API Reference
Complete reference for all classes, methods, and types.