Quickstart

Before You Begin

You need 3 things from your Ozura Dashboard:

What	Where to Find	Example Format
Vault API Key	Developers → Vault Key	(your unique key)
Merchant API Key	Developers → API Keys	(your unique key)
Merchant ID	Developers → Identity	(your merchant ID)

To open checkout in a popup instead of redirecting, no registration or approval is needed. Pass embedMode: "popup" and parentOrigin (the exact origin of your page) in your session create request. Checkout sends the result back to that origin.

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

Iframe embedding is coming soon. See Integration Modes for the full popup and new tab 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:

Enters their card details
Clicks “Pay Now”
Gets redirected back to your site

Step 4: Handle the Result

After payment, the customer lands on one of your URLs:

Outcome	Where They Go	What to Do (Your Responsibility)
Payment succeeded	Your `successUrl`	Show confirmation, fulfill order (your business logic)
Payment failed	Your `errorUrl`	Show error, offer retry
Customer cancelled	Your `cancelUrl`	Return 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 cart	Create Session → Cart Items
Keep customer on my site (popup/new tab)	Integration Modes
Match checkout to my brand colors	Customize Appearance
Test without real charges	Testing Guide
See all API options	API Reference
Fix an error	Troubleshooting

Getting Started

Vault

Payments

Before You Begin

Step 1: Create a Checkout Session

Step 2: Redirect Your Customer

Step 3: Customer Pays

Step 4: Handle the Result

That’s It!

​Before You Begin

​Keeping Customers on Your Site (Popup)

​Step 1: Create a Checkout Session

​Step 2: Redirect Your Customer

​Step 3: Customer Pays

​Step 4: Handle the Result

​That’s It!

Before You Begin

Keeping Customers on Your Site (Popup)

Step 1: Create a Checkout Session

Step 2: Redirect Your Customer

Step 3: Customer Pays

Step 4: Handle the Result

That’s It!