Skip to main content

​
Before You Begin

You need 3 things from your Ozura Dashboard:
WhatWhere to FindExample Format
Vault API KeyDevelopers → Vault Key(your unique key)
Merchant API KeyDevelopers → API Keys(your unique key)
Merchant IDDevelopers → Identity(your merchant ID)

​
Embedding on Your Site (Iframe or Popup)

If you plan to embed the checkout on your website, no registration or approval is needed. Simply pass parentOrigin in your session create request and Ozura automatically configures the Content Security Policy so the browser only allows the checkout to be framed on your domain. 
{
  "embedMode": "iframe",
  "parentOrigin": "https://yoursite.com"
}
That’s it — there is no separate domain registration step. See Integration Modes for the full embed implementation.
Don’t have your Vault API Key? Find it under Developers → Vault Key.Environment Variables 101: Never hardcode API keys in your code. Instead:
  • Create a .env file: VAULT_API_KEY=your_actual_key
  • Access it: process.env.VAULT_API_KEY (Node.js) or os.environ['VAULT_API_KEY'] (Python)
  • Never commit .env to git! Add it to .gitignore

​
Step 1: Create a Checkout Session

From your server (not browser), make this API call:
What’s “your server”? This is backend code — a Node.js app, PHP script, Python app, etc. If you only have static HTML, you cannot call this API directly (API keys would be exposed). Consider using Payment Links instead.
curl -X POST https://checkout.ozura.com/api/sessions/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_VAULT_API_KEY" \
  -H "X-OZURA-API-KEY: YOUR_MERCHANT_API_KEY" \
  -d '{
    "merchantId": "YOUR_MERCHANT_ID",
    "merchantName": "My Store",
    "amount": "25.00",
    "currency": "USD",
    "successUrl": "https://yoursite.com/thank-you",
    "cancelUrl": "https://yoursite.com/cart",
    "errorUrl": "https://yoursite.com/payment-failed"
  }'
Replace:
  • YOUR_VAULT_API_KEY → Your Vault API Key (Developers → Vault Key)
  • YOUR_MERCHANT_API_KEY → Your Merchant API Key (Developers → API Keys)
  • YOUR_MERCHANT_ID → Your Merchant ID (Developers → Identity)
  • URLs → Your actual website URLs
You’ll get back: 
{
  "success": true,
  "data": {
    "sessionId": "session_xxxxxxxxxxxxxx",
    "checkoutUrl": "https://checkout.ozura.com/checkout/session_xxxxxxxxxxxxxx"
  }
}

​
Step 2: Redirect Your Customer

Send the customer’s browser to the checkoutUrl: 
// === BROWSER CODE (your checkout button click handler) ===
// This runs in the customer's browser, NOT on your server
window.location.href = "https://checkout.ozura.com/checkout/session_xxxxxxxxxxxxxx";
The customer will see a secure payment form with your store name and the amount.
For local development, your URLs can use http://localhost. In production, always use HTTPS.

​
Step 3: Customer Pays

The customer:
  1. Enters their card details
  2. Clicks “Pay Now”
  3. Gets redirected back to your site

​
Step 4: Handle the Result

After payment, the customer lands on one of your URLs:
OutcomeWhere They GoWhat to Do (Your Responsibility)
Payment succeededYour successUrlShow confirmation, fulfill order (your business logic)
Payment failedYour errorUrlShow error, offer retry
Customer cancelledYour cancelUrlReturn to cart
Success URL includes payment details: 
https://yoursite.com/thank-you?success=true&sessionId=session_xxx&transactionId=2603130000113B86C&amount=25.00&currency=USD&cardLastFour=4242&cardBrand=VISA
Important: Ozura automatically marks the session as “completed” before redirecting. However, you should still verify the session server-side (call GET /api/sessions/{sessionId}) before fulfilling orders to prevent URL spoofing. See Security for details.

​
That’s It!

You’re now accepting payments. What’s next?
I want to…Read this
Add product images and discounts to cartCreate Session → Cart Items
Keep customer on my site (popup/iframe)Integration Modes
Match checkout to my brand colorsCustomize Appearance
Test without real chargesTesting Guide
See all API optionsAPI Reference
Fix an errorTroubleshooting