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"
}

​

“Payment processing is not available for this merchant.”

1. Verify your merchantId exactly matches what’s in your Ozura Dashboard
2. Verify the X-OZURA-API-KEY you are using is authorized for that merchantId
3. Create a new checkout session with the corrected credentials

​

”Authentication failed. Please start a new checkout session.”

1. Session is older than 30 minutes. The credential expires 30 minutes from when the session was created. If the customer (or developer) took longer than that to fill in the form and submit, the credential will be expired. Create a new session and redirect the customer to the new checkout URL.
2. Merchant API key lacks sale permission for the merchantId. The X-OZURA-API-KEY used to create the session does not have sale permission for the merchantId in the request. This surfaces as a “Payment processing is not available for this merchant” error on the checkout page (not a card issue — the error occurs before the card is charged). Verify that the Merchant API Key you are using is authorized for the merchantId you are passing in the session body.
3. Vault key environment mismatch. The X-API-KEY used to create the session is a staging vault key, but the Checkout deployment is configured for the production vault (or vice versa). Keys and the checkout environment must match.
4. Vault key lacks tokenize permission. The vault API key does not have tokenization rights. Verify your key has the correct permissions in the Ozura Dashboard.

​

”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:
   frame-src 'self' https://checkout.ozura.com;
   
3. Consider using popup or redirect mode instead

​

Not receiving postMessage events

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://checkout.ozura.com') 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