Checkout

`. Just make sure the wrapper has visible width and is not hidden with `overflow: hidden` or `height: 0`, or the field will be invisible. You can also pass element options at creation time: ```ts theme={null} const cardNumber = vault.createElement('cardNumber', { style: { base: { fontSize: '16px', color: '#1a1a2e' } }, placeholder: '1234 1234 1234 1234', }); ``` *** ## createElement Options ```ts theme={null} vault.createElement(type: ElementType, options?: ElementOptions): OzElement ``` | Option | Type | Description | | - | - | - | | `style` | `ElementStyleConfig` | Per-element style overrides. See [Styling](/sdks/elements/styling). | | `placeholder` | `string` | Placeholder text shown inside the field | | `disabled` | `boolean` | Mount the field in a disabled state | | `loadTimeoutMs` | `number` | Timeout (ms) before `loaderror` fires for this element. Default: `10000`. | *** ## Tokenizing Call `createToken()` after the user has filled all fields. The SDK transmits the field values directly to the Ozura Vault API — raw data never passes through your code. ```ts theme={null} document.getElementById('pay-btn').addEventListener('click', async (e) => { e.preventDefault(); try { const { token, cvcSession, card, billing } = await vault.createToken({ billing: { firstName: 'Jane', lastName: 'Smith', address: { line1: '123 Main St', city: 'San Francisco', state: 'CA', zip: '94102', country: 'US', }, }, }); // token — vault token, pass to your backend // cvcSession — CVC session ID; returned on success and required for cardSale // card.last4 — last 4 digits (safe to display) // card.brand — 'visa' | 'mastercard' | 'amex' | … // billing — validated, normalized billing ready for cardSale await fetch('/api/charge', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token, cvcSession, billing }), }); } catch (err) { if (err instanceof OzError) { console.error(err.message, err.errorCode); } } }); ``` ### createToken options ```ts theme={null} vault.createToken(options?: TokenizeOptions): Promise ``` | Option | Type | Description | | - | - | - | | `billing` | `BillingDetails` | Billing details to validate, normalize, and include in the token record | | `firstName` | `string` | *(deprecated)* Use `billing.firstName` instead | | `lastName` | `string` | *(deprecated)* Use `billing.lastName` instead | ### TokenResponse ```ts theme={null} { token: string; // vault token cvcSession: string; // CVC session ID — always present on success; pass to cardSale card?: { last4: string; // last 4 digits of card number brand: string; // 'visa' | 'mastercard' | 'amex' | 'discover' | … expMonth: string; // '01'–'12' expYear: string; // '2026', '2027', … }; billing?: BillingDetails; // echoed back (validated + normalized) if you passed billing } ``` **`cvcSession` is always present on a successful tokenization.** The SDK validates this field before resolving `createToken()` — if it is absent the promise rejects with an `OzError` (`errorCode: 'server'`), which would indicate a vault misconfiguration. Always forward both `token` and `cvcSession` to your charge endpoint: ```ts theme={null} const { token, cvcSession, billing } = await vault.createToken({ billing }); // cvcSession is guaranteed non-empty here await fetch('/api/charge', { method: 'POST', body: JSON.stringify({ token, cvcSession, billing }), }); ``` **`cvcSession` lifecycle.** The `cvcSession` is a short-lived vault credential that allows your server to retrieve the CVC value during a `cardSale` call. It shares the parent session TTL (default 30 minutes). It is safe to briefly persist it server-side — e.g. in a Redis key with a short TTL, or in a signed server-session — between the tokenization call and the charge call (seconds to minutes is fine). Do **not** store it long-term or log it. The vault invalidates the CVC credential after it is consumed by `cardSale`, so it is single-use. ### BillingDetails ```ts theme={null} { firstName: string; // required, 1–50 chars lastName: string; // required, 1–50 chars email?: string; // valid email, max 50 chars phone?: string; // E.164 format, e.g. '+15551234567' address?: { line1: string; // required line2?: string; // optional city: string; // required state: string; // required; US/CA normalized to 2-letter code zip: string; // required country: string; // ISO 3166-1 alpha-2, e.g. 'US' }; } ``` The SDK normalizes `state` to its standard 2-letter abbreviation for US and Canadian addresses. Full names (e.g. `"California"`, `"British Columbia"`) and 2-letter codes are both accepted. For `country: 'US'`, the state must be a valid US state, territory (PR, GU, VI, AS, MP), or military address code (AE, AP, AA) — other values are rejected. For `country: 'CA'`, the state must be a valid Canadian province code. **`cardSale` requires more billing fields than tokenize-only.** The OzuraPay API enforces `minLength: 1` on billing fields — passing an empty string `""` causes a validation error even if the field is technically optional. The SDK strips absent optional fields automatically (omits the key rather than sending `""`). However, in practice `cardSale` typically requires `email`, `phone`, and a full `address` to process the charge. If any of these are missing, the OzuraPay API will return a validation error. **Recommendation:** For charge flows, collect `email`, `phone`, and full address from the customer and pass them in `BillingDetails`. For tokenize-only flows (no charging), `billing` can be omitted entirely — or if you want billing details echoed back in `TokenResponse.billing`, pass at minimum `{ firstName, lastName }`. *** ## Events Each element emits events you can listen to with `.on()`: ```ts theme={null} cardNumber.on('change', (event) => { // event.empty — boolean: true when the field has no input // event.complete — boolean: field has reached the required length/format (may still be invalid — check `valid`) // event.valid — boolean: value passes full validation (e.g. Luhn check, expiry in future) // event.error — string | undefined: human-readable error message // event.cardBrand — string: 'visa' | 'mastercard' | 'amex' | … (cardNumber only) }); expiry.on('change', (event) => { // event.month — string: parsed month '01'–'12' (expirationDate only) // event.year — string: parsed 2-digit year e.g. '27' (expirationDate only) }); ``` **The expiry `onChange` event includes `month` and `year` values.** These are parsed from the masked expiry input and delivered to your handler for display purposes (e.g. showing the detected expiry date). If your PCI scope requires zero cardholder data on the merchant page, do not read or log these fields. ```ts theme={null} cardNumber.on('focus', () => { /* field received focus */ }); cardNumber.on('blur', (data) => { /* field lost focus; data = { empty, complete, valid, error } */ }); cardNumber.on('ready', () => { /* iframe loaded and is interactive */ }); cardNumber.on('loaderror', ({ elementType, error }) => { /* iframe failed to load */ }); ``` ### Gating the submit button The vault and each field iframe load independently. Gate your submit button on both: * **Vault readiness** — the `onReady` callback (fires when the vault is ready to tokenize) * **Field readiness** — each field's `'ready'` event (fires when the iframe loaded and is interactive) plus `change` events for completion ```ts theme={null} let vaultReady = false; const fieldReady = { cardNumber: false, expiry: false, cvv: false }; const fieldFilled = { cardNumber: false, expiry: false, cvv: false }; function updatePayButton() { const allReady = vaultReady && fieldReady.cardNumber && fieldReady.expiry && fieldReady.cvv && fieldFilled.cardNumber && fieldFilled.expiry && fieldFilled.cvv; document.getElementById('pay-btn').disabled = !allReady; } const vault = await OzVault.create({ pubKey: 'YOUR_PUB_KEY', // omit for test vault keys sessionUrl: '/api/oz-session', onReady: () => { vaultReady = true; updatePayButton(); }, }); cardNumber.on('ready', () => { fieldReady.cardNumber = true; updatePayButton(); }); expiry.on('ready', () => { fieldReady.expiry = true; updatePayButton(); }); cvv.on('ready', () => { fieldReady.cvv = true; updatePayButton(); }); cardNumber.on('change', ({ complete, valid }) => { fieldFilled.cardNumber = complete && valid; updatePayButton(); }); expiry.on('change', ({ complete, valid }) => { fieldFilled.expiry = complete && valid; updatePayButton(); }); cvv.on('change', ({ complete, valid }) => { fieldFilled.cvv = complete && valid; updatePayButton(); }); ``` *** ## Teardown When the checkout component unmounts, call `vault.destroy()` to remove all iframes and listeners. In vanilla JS use a cancel flag to handle the async nature of `OzVault.create()`: ```ts theme={null} let cancelled = false; let vault: OzVault | null = null; OzVault.create({ pubKey: 'YOUR_PUB_KEY', sessionUrl: '/api/oz-session', }).then(v => { if (cancelled) { v.destroy(); return; } vault = v; // mount elements... }); // On unmount: function cleanup() { cancelled = true; vault?.destroy(); } ``` *** ## Auto-Advance Focus Elements automatically advance focus from one field to the next on completion: * When **card number** is complete and valid → focus moves to **expiry** * When **expiry** is complete and valid → focus moves to **CVV** This is built-in and requires no configuration. *** ## Card Brand Detection The `cardNumber` element detects the card brand as the user types and emits it via `change`: ```ts theme={null} cardNumber.on('change', ({ cardBrand }) => { // Update your card brand icon document.getElementById('brand-icon').src = `/icons/${cardBrand}.svg`; }); ``` | Brand value | Description | | - | - | | `'visa'` | Visa | | `'mastercard'` | Mastercard | | `'amex'` | American Express (CVV becomes 4 digits) | | `'discover'` | Discover | | `'dinersclub'` | Diners Club | | `'jcb'` | JCB | | `'unknown'` | Not yet detected or unrecognized | *** ## Imperatively Managing Elements ```ts theme={null} // Focus a field programmatically cardNumber.focus(); // Clear a field cardNumber.clear(); // Check if the iframe is ready if (cardNumber.isReady) { /* safe to proceed */ } // Get the element type cardNumber.type; // 'cardNumber' // Tear down the iframe and remove listeners cardNumber.destroy(); ``` *** ## Full End-to-End Example (Vanilla JS + Express) **`onReady` can fire while `OzVault.create()` is still pending.** Vault initialization runs multiple steps in parallel. The `onReady` callback can fire while `await OzVault.create(...)` is still in progress — meaning `vault` is `undefined` inside the callback. Never reference `vault` inside `onReady`. Declare your readiness flags before calling `create()` so they exist when the callback runs. See the example below for the correct pattern. A complete working example: HTML page with card fields, Express backend with `/api/oz-session` and `/api/charge` routes, and the full tokenize → charge flow. ### Frontend (HTML + JS) ```html theme={null} Checkout ``` ### Backend (Express) ```js theme={null} // server.js import express from 'express'; import { Ozura, OzuraError, getClientIp, createSessionMiddleware } from '@ozura/elements/server'; const app = express(); app.use(express.json()); // Serve the SDK from the same origin for localhost CDN-free loading app.get('/oz-elements.esm.js', (_, res) => res.sendFile('node_modules/@ozura/elements/dist/oz-elements.esm.js', { root: '.' }) ); const ozura = new Ozura({ merchantId: process.env.MERCHANT_ID, apiKey: process.env.MERCHANT_API_KEY, vaultKey: process.env.VAULT_API_KEY, }); // Session route — called automatically by the frontend SDK app.post('/api/oz-session', createSessionMiddleware(ozura)); // Charge route — called after tokenization app.post('/api/charge', async (req, res) => { try { const { token, cvcSession, billing } = req.body; // Always fetch the authoritative amount from your own database const amount = '49.00'; const result = await ozura.cardSale({ token, cvcSession, amount, currency: 'USD', billing, clientIpAddress: getClientIp(req), }); // Store result.transactionId — required for refunds res.json({ success: true, transactionId: result.transactionId }); } catch (err) { const status = err instanceof OzuraError ? (err.statusCode || 500) : 500; const message = err instanceof OzuraError ? err.message : 'Internal server error'; res.status(status).json({ error: message }); } }); app.listen(3000, () => console.log('Listening on http://localhost:3000')); ``` This example serves the SDK locally to avoid CDN CORS issues on localhost. In production, use the CDN URL or your bundler — remove the `/oz-elements.esm.js` static route. See [Installation → CDN](/sdks/elements/installation#cdn-script-tag) for details. *** ## Test Cards These cards are for testing the **vault tokenization flow** — they are Luhn-valid and accepted by the vault in test mode. Use them to confirm your fields mount, tokenize, and return a token correctly. | Brand | Number | CVC | Expiry | | - | - | - | - | | Visa | `4111 1111 1111 1111` | Any 3 digits | Any future date | | Mastercard | `5555 5555 5555 4444` | Any 3 digits | Any future date | | Amex | `3782 822463 10005` | Any 4 digits | Any future date | **Testing a full charge with OzuraPay?** Use the cards on the [Test Credentials](/guides/test-credentials) page instead — those are calibrated for OzuraPay's sandbox, where the outcome (approve / decline) is determined by the charge amount, not the card number. **Testing your integration?** Use the test pub key on localhost — see [Installation → Local Development](/sdks/elements/installation#local-development) for setup details and test card numbers above. *** ## Next Steps Customize colors, fonts, and states. OzElements provider and pre-built components. Handle tokenization errors gracefully. Process the token with cardSale() on your backend. # Error Handling Source: https://docs.ozura.com/sdks/elements/error-handling Handle OzError instances from createToken() and createBankToken(), understand error codes, and surface errors to users. `createToken()` and `createBankToken()` both throw an `OzError` when tokenization fails. Wrap calls in a `try/catch` and inspect `.errorCode` to decide how to respond. *** ## OzError ```ts theme={null} import { OzError } from '@ozura/elements'; try { const { token } = await vault.createToken(); } catch (err) { if (err instanceof OzError) { console.error(err.message); // user-facing message console.error(err.errorCode); // machine-readable code console.error(err.raw); // raw message from vault (for logging) console.error(err.retryable); // boolean: safe to retry? } } ``` ### OzError properties | Property | Type | Description | | - | - | - | | `message` | `string` | Normalized, user-friendly error message | | `errorCode` | `OzErrorCode` | Machine-readable code (see table below) | | `raw` | `string` | Raw message returned by the Vault API (use for logging, not display) | | `retryable` | `boolean` | `true` for transient errors (`network`, `timeout`, `server`). `false` for permanent failures where retrying with the same input won't help. | *** ## Error Codes | `errorCode` | `retryable` | Meaning | What to do | | - | - | - | - | | `'network'` | ✅ | Request failed due to a network error (offline, DNS failure, etc.) | Show a "check your connection" message. Retry is safe. | | `'timeout'` | ✅ | Tokenization took longer than 30 seconds | Show a timeout message. Retry is safe. | | `'server'` | ✅ | Vault returned a 5xx error | Retry after a short delay. Log for investigation. | | `'auth'` | ❌ | Session key invalid/expired (after automatic refresh retry), or pub key misconfigured | If you see this in production after a successful initial load, the auto-refresh failed — check that your session endpoint (`/api/oz-session`) is reachable. Otherwise verify credentials. | | `'validation'` | ❌ | Request was malformed or the vault rejected input | Check request parameters. Usually a developer error. | | `'config'` | ❌ | Unexpected SDK or environment issue | Log the error and contact Ozura support. | | `'unknown'` | ❌ | Unclassified error | Log and surface a generic message. | **Session key expiry is handled automatically.** When a session key expires or is consumed between initialization and the user clicking Pay, the SDK silently fetches a fresh key and retries once. You will only receive an `auth` error if the refresh itself fails (e.g. your session endpoint is down or returns an error). The proactive refresh — triggered once `sessionLimit` successful submissions are reached — also prevents expiry from surfacing under normal usage. *** ## Recommended Pattern ```ts theme={null} import { OzVault, OzError } from '@ozura/elements'; async function handlePay() { try { const { token, cvcSession } = await vault.createToken({ billing: { firstName: 'Jane', lastName: 'Smith' }, }); await submitPayment(token, cvcSession); } catch (err) { if (!(err instanceof OzError)) throw err; // rethrow unexpected errors if (err.retryable) { showError('Connection issue — please try again.'); } else { switch (err.errorCode) { case 'auth': showError('Configuration error. Please contact support.'); console.error('[OzElements] Auth error:', err.raw); break; case 'validation': showError('Payment details could not be verified. Please check your card.'); break; case 'config': showError('Configuration error. Please contact support.'); console.error('[OzElements] Config error:', err.raw); break; default: showError('Something went wrong. Please try again.'); console.error('[OzElements] Unexpected error:', err); } } } } ``` *** ## SDK-Level Errors These `OzError` instances are thrown before any network request is made. They represent setup or usage mistakes caught during integration — fix them in code, don't surface them to the user. ### Initialization errors These come from `OzVault.create()`. If you're using the React provider, they appear in `initError`. | Condition | How to fix | | - | - | | `pubKey` missing | If using a **production** vault API key, pass a valid `pubKey` to `OzVault.create()` / ``. If using a test/sandbox vault API key, `pubKey` is not required and can be omitted. | | No session option provided | Pass `sessionUrl`, `getSessionKey`, or (deprecated) `fetchWaxKey` to `OzVault.create()` / ``. | | `sessionUrl` or `getSessionKey` returned an empty string | Check your `/api/oz-session` endpoint — it must return a non-empty `sessionKey`. | | Session fetch threw an error | Your session endpoint failed. Check server logs. | ### Tokenization errors These come from `createToken()` / `createBankToken()`. | Condition | How to fix | | - | - | | Vault not ready | Wait for the `onReady` callback (vanilla) or the `ready` flag (React) before submitting. | | No elements mounted | Call `mount()` on at least one element before tokenizing. | | `accountNumber` / `routingNumber` not ready (bank) | Mount both bank elements before calling `createBankToken()`. | | Tokenization already in progress | Disable your submit button while tokenization is pending. | | Missing `firstName` / `lastName` (bank) | Pass `firstName` and `lastName` in your `createBankToken()` options. | | Name exceeds 50 characters | Truncate or validate `firstName` / `lastName` before submitting. | | Invalid billing details | Validate `billing` fields before calling `createToken()`. Check the error message for the specific field. | | Tokenization timed out | `errorCode: 'timeout'` — retryable; show a timeout message. | ### Element errors | Condition | How to fix | | - | - | | `mount()` CSS selector not found | Verify the selector string targets an element that exists in the DOM at mount time. | | `mount()` passed `null` / `undefined` | Check your DOM reference before calling `mount()`. | These are developer errors — TypeScript types and the error messages above are the full diagnostic. *** ## Load Errors If the vault fails to load (network issue, blocked by CSP, etc.), use `onLoadError` in `OzVault.create()`: ```ts theme={null} const vault = await OzVault.create({ pubKey: 'YOUR_PUB_KEY', sessionUrl: '/api/oz-session', onLoadError: () => { showError('Payment fields could not load. Please refresh and try again.'); }, loadTimeoutMs: 8000, // default: 10000 }); ``` Individual element load failures emit a `loaderror` event with the element type and error message: ```ts theme={null} cardNumber.on('loaderror', ({ elementType, error }) => { console.error(`[OzElements] ${elementType} failed to load:`, error); showError('Card number field failed to load. Please refresh.'); }); ``` *** ## React: initError In React, `OzVault.create()` is called inside the `` provider. If it fails (e.g. your session endpoint is unreachable or returns an error), `useOzElements().initError` will be non-null: ```tsx theme={null} function CheckoutForm() { const { createToken, ready, initError } = useOzElements(); if (initError) { return

Payment unavailable — please refresh the page.

; } return (

); } ``` *** ## Error Normalization Helpers The SDK exports three standalone functions that map raw API error strings to user-friendly messages. `OzError.message` from `createToken()` and `createBankToken()` is **already normalized** — the SDK calls these functions internally. You only need to call them yourself when you receive raw error strings from a different source (e.g. your backend forwarding a vault or OzuraPay API response). ### normalizeVaultError Maps raw vault `/tokenize` error strings to user-facing messages for **card** flows. ```ts theme={null} import { normalizeVaultError } from '@ozura/elements'; const message = normalizeVaultError(rawVaultErrorString); // e.g. "Invalid card number" → "The card number is invalid. Please check and try again." ``` ### normalizeBankVaultError Maps raw vault `/tokenize` error strings to user-facing messages for **bank/ACH** flows. ```ts theme={null} import { normalizeBankVaultError } from '@ozura/elements'; const message = normalizeBankVaultError(rawVaultErrorString); // e.g. "Invalid routing number" → "The routing number is invalid. Please check and try again." ``` ### normalizeCardSaleError Maps raw OzuraPay API `cardSale` error strings to user-facing messages. Use this when your backend processes a charge via the OzuraPay API and needs to display the error to the user. ```ts theme={null} import { normalizeCardSaleError } from '@ozura/elements'; const message = normalizeCardSaleError(rawPayApiErrorString); // e.g. "Insufficient Funds" → "Your card has insufficient funds. Please use a different payment method." ``` All three functions fall back gracefully when no pattern matches: * **`normalizeVaultError`** and **`normalizeBankVaultError`** — return the original `raw` string unchanged when no pattern matches. * **`normalizeCardSaleError`** — short unrecognized strings (under 100 characters) are returned as-is; long opaque server strings (100+ characters) are replaced with `"Payment processing failed. Please try again or contact support."` An empty input returns `"Payment processing failed. Please try again."` *** ## Next Steps Full OzError type definition and all SDK types. createToken() full reference. # Installation Source: https://docs.ozura.com/sdks/elements/installation Add @ozura/elements to your project via npm, yarn, or a CDN script tag. ## npm / yarn ```bash npm theme={null} npm install @ozura/elements ``` ```bash yarn theme={null} yarn add @ozura/elements ``` **Pre-release builds (`@next`):** The `next` dist-tag contains unreleased changes before they reach `latest`. It is intended for Ozura-coordinated testing only — production credentials will not work with it. If you have been given access to pre-release testing, contact **[ammar@ozura.com](mailto:ammar@ozura.com)** for the matching staging credentials and setup instructions. ```bash theme={null} npm install @ozura/elements@next ``` `npm install @ozura/elements` (no tag) always resolves `latest` — `@next` has no impact on production installs. Then import in your JavaScript or TypeScript: ```ts theme={null} import { OzVault, OzError } from '@ozura/elements'; ``` For React components: ```ts theme={null} import { OzElements, useOzElements, OzCard, OzCardNumber, OzExpiry, OzCvv, OzBankCard, OzBankAccountNumber, OzBankRoutingNumber, } from '@ozura/elements/react'; ``` `@ozura/elements/react` requires **React 17 or later** as a peer dependency. If React is not already in your project, install it first: ```bash theme={null} npm install react react-dom ``` For server-side usage (Node.js, Deno, Bun): ```ts theme={null} import { Ozura, OzuraError, getClientIp, createCardSaleHandler, createSessionHandler } from '@ozura/elements/server'; ``` *** ## CDN (Script Tag) **The Ozura CDN blocks `localhost` origins.** If you load the CDN script on `http://localhost`, the browser will reject it with a CORS error (`No 'Access-Control-Allow-Origin' header`). The CDN is for deployed origins only. See [Local Development](#local-development) below. If you're not using a bundler, load the UMD build directly from the Ozura CDN: ```html theme={null} ``` Or use the ESM build with a native module script: ```html theme={null} ``` *** ## Local Development The CDN blocks `localhost`. For local development you have two options depending on how you load the SDK: ### npm install (recommended) If your project uses a bundler (webpack, Vite, Next.js, etc.), `@ozura/elements` is imported directly from `node_modules` — no CDN involved, no workaround needed. The iframes load from `elements.ozura.com` at runtime, but that uses `