> ## Documentation 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 SDK

> Overview of @ozura/elements — Ozura's browser SDK for secure payment data collection.

**@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 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 call `createToken()` 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 via `sessionUrl` 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.

<Note>
  **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.
</Note>

***

## 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 OzuraPay API `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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdks/elements/installation">
    npm, yarn, CDN. TypeScript setup.
  </Card>

  <Card title="Card Elements" icon="credit-card" href="/sdks/elements/card-elements">
    createElement(), createToken(), field types, events.
  </Card>

  <Card title="Bank Elements" icon="landmark" href="/sdks/elements/bank-elements">
    createBankElement(), createBankToken(), ACH tokenization.
  </Card>

  <Card title="React" icon="atom" href="/sdks/elements/react">
    OzElements provider, hooks, pre-built components.
  </Card>

  <Card title="Styling" icon="palette" href="/sdks/elements/styling">
    Style config, supported properties, global appearance.
  </Card>

  <Card title="Error Handling" icon="triangle-alert" href="/sdks/elements/error-handling">
    OzError, errorCode values, retry guidance.
  </Card>

  <Card title="Server SDK" icon="server" href="/sdks/elements/server">
    Process payments and query transactions on your backend.
  </Card>

  <Card title="API Reference" icon="book" href="/sdks/elements/api-reference">
    Complete reference for all classes, methods, and types.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.