Troubleshooting

​

Common API Errors

​

”Invalid Vault API Key”

1. Your Vault API Key was provided when you first signed up
2. If you didn’t save it, contact Ozura support to retrieve it
3. Copy the key exactly (no extra spaces)
4. Make sure it’s in the X-API-KEY header (not X-OZURA-API-KEY)

​

“Invalid Merchant API Key”

1. Go to Dashboard → Settings → API Keys
2. Copy your Merchant API Key exactly
3. Paste it in the X-OZURA-API-KEY header (not X-API-KEY)

​

“merchantId is required”

{
  "merchantId": "your_merchant_id"
}

​

“successUrl is required”

{
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "errorUrl": "https://yoursite.com/error"
}

​

“Session not found”

• Sessions expire after 30 minutes – create a new one
• Check you’re using the correct sessionId
• Make sure you’re hitting the right environment (test vs production)

​

“Session has expired”

​

”Session already completed”

​

CORS Errors

​

”Access-Control-Allow-Origin” error in browser

{
  "embedMode": "popup",
  "parentOrigin": "https://yoursite.com"
}

• Include https:// (not just yoursite.com)
• No trailing slash
• Exact match required

​

Popup/Iframe Issues

​

Popup blocked

1. Popup must open from a user click (not automatically)
2. Ask user to allow popups for your site
3. Consider using redirect mode as fallback:

const popup = window.open(checkoutUrl, 'checkout', 'width=500,height=700');
if (!popup || popup.closed) {
  // Fallback to redirect
  window.location.href = checkoutUrl;
}

​

Iframe not loading

1. Check browser console for CSP errors
2. Add Ozura to your CSP config:
   Copy

   frame-src 'self' https://checkout.ozura.io;
   
3. Consider using popup or redirect mode instead

​

Not receiving postMessage events

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://checkout.ozura.io') return;
  // Handle event
});

​

Cart/Itemization Issues

​

”Cannot use both amount and items”

// ✅ Correct: Items only (no amount)
{
  "items": [
    { "productId": "sku_001", "name": "T-Shirt", "price": 25.00, "quantity": 2 }
  ]
}

// ✅ Correct: Amount only (no items)
{
  "amount": "50.00"
}

​

“Mixed taxExempt values in items”

// ✅ Correct: All tax-exempt
{
  "items": [
    { "productId": "A", "name": "Item A", "price": 10, "quantity": 1, "taxExempt": true },
    { "productId": "B", "name": "Item B", "price": 20, "quantity": 1, "taxExempt": true }
  ]
}

​

“price has X decimal places but Y only allows Z”

​

Related Pages

• Error Handling — HTTP status codes, error response format, and retry patterns
• Handle the Payment Result — Verifying session status and processing outcomes

​

Still Stuck?

• Your Merchant ID
• Session ID (if applicable)
• The exact error message
• Steps to reproduce