Skip to main content

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

​
End-to-end integration flow

Testing a full integration follows this sequence:
  1. Create a vault project — go to 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.
  4. Add the Elements SDK — install @ozura/elements and mount your card fields. See Installation and the quick-start guides.
  5. Run the tokenize flow — fill the fields with a test card number 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

ServiceSandbox URL
OzuraPay APIhttps://sandbox.payapi.v2.ozurapay.com
Checkouthttps://sandbox-checkout.ozura.com
Vaulthttps://api.ozuravault.com — single environment; use a test key from a Test project.
Dashboardhttps://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)
  2. Sandbox OzuraPay credentials (merchant ID + PayAPI key) from the merchant dashboard’s Sandbox/Production toggle — see the OzuraPay 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 (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 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.

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

Elements — Installation

Add @ozura/elements and initialise OzVault.create() — credentials, options, and Next.js setup.

Elements — Server SDK

Tokenize-only new Ozura({ vaultKey }) constructor for vault-only merchants.

​
Key Differences from Production

  • No real money is processed
  • Test card numbers are accepted (see Test Credentials)
  • Rate limits are relaxed
  • Webhook payloads include a sandbox: true flag

​
Next Steps