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