Skip to main content
Keep your integration secure and protect your customers.

​
API Key Management

You have two API keys. Treat them like passwords.
KeyHeaderPurpose
Vault API KeyX-API-KEYAuthenticates with Ozura’s secure card storage system
Merchant API KeyX-OZURA-API-KEYIdentifies your merchant account
Why two keys? The Vault API Key connects to the secure card tokenization system. The Merchant API Key ties transactions to your specific merchant account. Both are required for security.Where to find them: Your Vault API Key was provided at signup (contact support if you lost it). Your Merchant API Key is in Dashboard → Settings → API Keys.
What about the Vault Pub Key (X-Pub-Key)? If you’ve used OzElements, you may be familiar with the Vault Pub Key required for direct tokenization. With Checkout, you do not need to provide or manage this key — Checkout handles tokenization and pub key authentication internally. Your integration only requires the two keys listed above.

​
Do’s and Don’ts

DoDon’t
Store keys in environment variablesHardcode keys in your code
Rotate keys if compromisedCommit keys to version control
Restrict key access to needed team membersShare keys via email or chat

​
Server-Side Only

Never expose your API keys to the browser.
Create sessions from your server, not from client-side JavaScript: 
// ✅ CORRECT: Server-side (Node.js, Next.js API route, etc.)
app.post('/create-checkout', async (req, res) => {
  const response = await fetch('https://checkout.ozura.io/api/sessions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.VAULT_API_KEY,        // Server env var
      'X-OZURA-API-KEY': process.env.MERCHANT_API_KEY // Server env var
    },
    body: JSON.stringify({
      merchantId: process.env.MERCHANT_ID,
      amount: req.body.amount,
      // ...
    })
  });
  
  const data = await response.json();
  res.json({ checkoutUrl: data.data.checkoutUrl });
});

// ❌ WRONG: Client-side (browser JavaScript)
// API keys would be visible to anyone viewing page source!
fetch('https://checkout.ozura.io/api/sessions/create', {
  headers: {
    'X-API-KEY': 'exposed_key_123',  // NEVER DO THIS
  }
});

​
Verify Payments

Always verify payments server-side before fulfilling orders. A malicious user could attempt to visit your success URL directly. Always check the session status: 
// On your success page handler
app.get('/success', async (req, res) => {
  const { sessionId } = req.query;
  
  // Check session status
  // No headers required - session ID acts as access token
  const response = await fetch(
    `https://checkout.ozura.io/api/sessions/${sessionId}`
  );
  
  const data = await response.json();
  
  if (data.data.session.status === 'completed') {
    // ✅ Payment verified by Ozura
    // ⚠️ YOUR RESPONSIBILITY: Implement your fulfillment logic
    await updateOrderStatus(sessionId, 'paid'); // YOUR implementation
  } else {
    // Not completed - don't fulfill
    res.redirect('/payment-issue');
  }
});

​
Session Security

​
Time Limits

Sessions expire after 30 minutes. This provides a secure window for payment while giving customers adequate time to complete checkout.

​
One-Time Use

Each session can only be completed once. After payment:
  • The session status becomes completed
  • Back button won’t work (session is expired)
  • The checkout page shows “already paid”

​
Use HTTPS in Production

All API requests to Ozura are made over HTTPS automatically. Your redirect URLs (successUrl, cancelUrl, errorUrl) should use HTTPS in production: 
{
  "successUrl": "https://mysite.com/success",
  "cancelUrl": "https://mysite.com/cancel",
  "errorUrl": "https://mysite.com/error"
}
Local development: You can use http://localhost:3000 for testing. HTTPS is only required for production URLs.

​
PCI Compliance

Ozura Checkout is designed for PCI compliance:
  • Card data never touches your servers – Customers enter card details directly on our secure checkout page
  • Tokenization – Card data is tokenized before processing
  • Encryption – All data is encrypted in transit and at rest
By using Ozura Checkout (hosted page), you significantly reduce your PCI compliance scope.

​
Refunds

Refunds are handled through the Ozura Pay API, not through the Checkout widget.