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

# Sandbox

> Test your Ozura integration without processing real transactions.

# Sandbox Environment

The Ozura sandbox is a complete test environment for end-to-end integration. No real money moves, and you can validate every part of your flow before going live.

<Note>
  Ozura's sandbox model is asymmetric: the Vault has a single environment where "sandbox" means a **Test project** with a **test key**, while OzuraPay has fully separate **sandbox** and **production** environments.
</Note>

## End-to-end integration flow

Testing a full integration follows this sequence:

1. **Create a vault project** — go to [ozuravault.com](https://www.ozuravault.com), sign up, and create a **Test project** (the default for new projects).
2. **Get a test vault key** — open the project, create an application, and copy the test key. Omit `pubKey` from `OzVault.create()` when using a test key — no pub key is needed for test projects.
3. **Set up the session endpoint** — implement `/api/oz-session` on your backend using `createSessionHandler` (or `createSessionMiddleware`). Use your test vault key as `vaultKey`. See the [Server SDK guide](/sdks/elements/server).
4. **Add the Elements SDK** — install `@ozura/elements` and mount your card fields. See [Installation](/sdks/elements/installation) and the quick-start guides.
5. **Run the tokenize flow** — fill the fields with a [test card number](/guides/test-credentials) and call `createToken()`. You receive a vault token and a CVC session.
6. **Hit your processor's sandbox** — pass the token and CVC session to your backend charge endpoint and forward them to your payment processor's sandbox environment. If you are routing through OzuraPay, point your backend at `https://sandbox.payapi.v2.ozurapay.com` with sandbox merchant credentials (see below).

***

## Base URLs

| Service      | Sandbox URL                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| OzuraPay API | `https://sandbox.payapi.v2.ozurapay.com`                                                                                                   |
| Checkout     | `https://sandbox-checkout.ozura.com`                                                                                                       |
| Vault        | `https://api.ozuravault.com` — single environment; use a test key from a Test project.                                                     |
| Dashboard    | `https://app.ozura.com` — flip the **Sandbox/Production** toggle in the header to switch envs (there is no separate sandbox dashboard URL) |

## What You Need to Use Checkout Sandbox

To run Checkout against the sandbox, you need three things:

1. A **test vault key** (from a Test project at [ozuravault.com](https://www.ozuravault.com))
2. **Sandbox OzuraPay credentials** (merchant ID + PayAPI key) from the merchant dashboard's Sandbox/Production toggle — see the [OzuraPay overview](/guides/payments/payapi/overview) for where to find them
3. All checkout API requests directed at `https://sandbox-checkout.ozura.com`

## Getting a Test Vault Key

The Ozura Vault product UI lives at [ozuravault.com](https://www.ozuravault.com) (also reachable at `vault.ozura.com` — same app, both URLs work) and is separate from the Ozura merchant dashboard at `app.ozura.com`.

1. Go to [https://www.ozuravault.com](https://www.ozuravault.com) and create an account.
2. Open **Projects → Create new project**. Your first project is a **Test project** by default; for any later project, confirm the **Test** marker is on. Name the project.
3. Open the new project, then **create an application** inside it and give it a name.
4. The next page displays the **test key** for that application. Store it securely — this is your test vault key.

Production vault keys are gated behind an application/approval step — apply via the Ozura Vault product UI or through your Ozura representative.

## Getting Sandbox OzuraPay Credentials

Sandbox PayAPI credentials (merchant ID + PayAPI key) come from the merchant dashboard. Flip the **Sandbox/Production** toggle in the dashboard header to Sandbox, then retrieve them from the Developers section. Full details are in the [OzuraPay overview](/guides/payments/payapi/overview).

## Using Elements with a Test Vault Key

The Elements SDK supports two sandbox flows. Pick the one that matches what you need:

1. **Tokenize-only** — vault-only merchants using their own processor, or just storing tokens. You only need a **test vault key**; no `merchantId` / `apiKey` required. On the frontend, omit `pubKey` from `OzVault.create()` (or the `<OzElements>` provider).
2. **Tokenize + charge via OzuraPay** — you need a test vault key **and** sandbox OzuraPay credentials (merchant ID + PayAPI key). On the frontend, still omit `pubKey` when using a test vault key.

The Elements SDK emits a one-time `console.warn` when `pubKey` is omitted to make the test-key-only mode explicit — that warning is expected in sandbox:

```
[OzVault] pubKey not provided — this only works with a test vault key from a Test
project on the vault. For production, set pubKey to your pk_live_... or pk_prod_... value.
```

<CardGroup cols={2}>
  <Card title="Elements — Installation" icon="download" href="/sdks/elements/installation">
    Add `@ozura/elements` and initialise `OzVault.create()` — credentials, options, and Next.js setup.
  </Card>

  <Card title="Elements — Server SDK" icon="server" href="/sdks/elements/server">
    Tokenize-only `new Ozura({ vaultKey })` constructor for vault-only merchants.
  </Card>
</CardGroup>

## Key Differences from Production

* No real money is processed
* Test card numbers are accepted (see [Test Credentials](/guides/test-credentials))
* Rate limits are relaxed
* Webhook payloads include a `sandbox: true` flag

## Next Steps

* [Test Credentials](/guides/test-credentials) for test card numbers and the amount-based outcome model
* [Checkout Testing Guide](/guides/payments/checkout/testing-guide) for the checkout-specific testing flow