Create a Checkout Session

Before a customer can pay, you create a “session” that holds all the payment details.

Quick Start (30 seconds)

Create a session and redirect your customer:

curl -X POST https://checkout.ozura.io/api/sessions/create \
  -H "X-API-KEY: your_vault_key" \
  -H "X-OZURA-API-KEY: your_merchant_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "your_merchant_id",
    "merchantName": "My Store",
    "amount": "25.00",
    "currency": "USD",
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "errorUrl": "https://yoursite.com/error"
  }'

Then redirect your customer to the returned checkoutUrl. Done!

The Basics

What	Value
API URL	`POST https://checkout.ozura.io/api/sessions/create`
Content-Type	`application/json`
Called From	Your server (never from browser JavaScript)

What’s “your server”? Backend code like Node.js, PHP, Python, Ruby, etc. If you’re using a website builder (Shopify, Wix), check if they offer serverless functions. If you only have static HTML, use Payment Links instead.

Required Headers

Every request needs these two headers:

X-API-KEY: your_vault_api_key
X-OZURA-API-KEY: your_merchant_api_key

What’s a header? Headers are extra information sent with your request (like an ID badge). They’re set separately from the request body — see the code examples below.Vault API Key: Provided when you signed up. If you didn’t save it, contact Ozura support.Merchant API Key: Dashboard → Settings → API Keys.

Required Fields

Your request body must include these fields:

{
  "merchantId": "your_merchant_id",
  "merchantName": "Your Store Name",
  "amount": "25.00",
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "errorUrl": "https://yoursite.com/error"
}

Field	What to Put	Example
`merchantId`	Your Merchant ID from Dashboard	`"merchant_abc123"`
`merchantName`	Your business name (customer sees this)	`"Bob's Coffee Shop"`
`amount`	How much to charge (string or number)*	`"25.00"` or `25.00`
`successUrl`	Confirmation page after payment	`"https://yoursite.com/thank-you"`
`cancelUrl`	Return destination (cart page)	`"https://yoursite.com/cart"`
`errorUrl`	System error handler	`"https://yoursite.com/cart?checkoutError=true"`

Why full URLs? Use absolute URLs like https://yoursite.com/success, not just /success. The redirect happens from Ozura’s servers, so we need the full URL to find your website.

*amount is required for standard payments. Accepts string (e.g., "25.00") or number (e.g., 25.00). Not needed when using items or checkoutMode: "donation".

Understanding the Three URLs

These three URLs control where customers end up after checkout.

Quick Summary

URL	Purpose	When Used	What You Receive
`successUrl`	Show receipt/confirmation	Payment successful	Transaction details, card info, customer data
`cancelUrl`	Return to shopping	User cancels OR session expires	Nothing (just a return path)
`errorUrl`	Handle system errors	Server/connectivity failures	Error code, message, return URL

successUrl – Your Confirmation Page

Purpose: Where customers land after successful payment to see their receipt/confirmation. When it’s used: After payment is processed and confirmed. What you receive: Full transaction details as URL parameters:

https://yoursite.com/success?success=true&sessionId=session_xxx&transactionId=txn_123&amount=25.00&currency=USD&cardLastFour=4242&cardBrand=visa&firstName=John&lastName=Doe&email=john@example.com

cancelUrl – Your “Go Back” Destination

Purpose: Where customers return when they don’t complete checkout. When it’s used: Customer clicks “Cancel”, session expires (30 min), or customer visits old/bookmarked checkout URL. What you receive: Nothing – it’s just a return path. Best Practice: Point to your cart page or wherever the customer was before checkout.

errorUrl – Your System Error Handler

Purpose: Handle unrecoverable errors (NOT card declines). When it’s used: Server failures, connectivity issues, authentication errors. NOT for card declines – those show inline messages and let customers retry. What you receive: Error details as URL parameters:

https://yoursite.com/error?success=false&errorCode=SYSTEM_ERROR&error=Payment+service+unavailable&cancelUrl=https://yoursite.com/cart

Optional Fields

Common Options

Field	Default	What It Does
`currency`	`"USD"`	Currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`, `"CAD"`)
`metadata`	`{}`	Your custom data (JSON object, returned in success URL)
`appearance`	`{}`	Custom styling (see Appearance)

Cart Items (Alternative to Amount)

Instead of a flat amount, you can send an array of cart items for a rich, itemized checkout display.

{
  "items": [
    {
      "productId": "sku_001",
      "name": "Blue T-Shirt",
      "price": 29.99,
      "quantity": 2,
      "imageUrl": "https://cdn.example.com/tshirt.jpg"
    }
  ]
}

Limits: Maximum 100 items per cart, maximum cart total: $999,999,999.99. See the full Cart Item Fields section below for all options.

Checkout Modes (Mutually Exclusive)

Mode	How to Use	Best For
Simple Amount	Pass `amount` only	Quick payments, invoices
Itemized Cart	Pass `items` array only	E-commerce with multiple products
Donation	Pass `checkoutMode: "donation"`	Charities, non-profits, tips

These modes are mutually exclusive:

Cannot use amount + items together
Cannot use items + checkoutMode: "donation" together
Can use amount + checkoutMode: "donation" (sets default donation amount)

Cart Item Fields

Each item in the items array supports:

Required Fields

Field	Type	Description
`productId`	string	Your product SKU or ID (max 100 chars)
`name`	string	Product name shown to customer (max 200 chars)
`price`	number	Unit price (e.g., `29.99`). Must be ≥ 0
`quantity`	integer	Quantity (1-10,000)

Visual Display Fields (Optional)

Field	Type	Description
`imageUrl`	string	Product image URL (HTTPS recommended)
`description`	string	Short product description (max 500 chars)
`variant`	string	Variant details, e.g., `"Size: L, Color: Blue"`
`brand`	string	Brand name displayed above product name
`category`	string	Product category

Pricing & Discount Fields (Optional)

Field	Type	Description
`originalPrice`	number	Original price before discount (shows strikethrough)
`discountLabel`	string	Discount badge text, e.g., `"SALE"`, `"20% OFF"`
`taxExempt`	boolean	If `true`, item displays “Tax Free” badge

Response

{
  "success": true,
  "data": {
    "sessionId": "session_xxxxxxxxxxxxxx",
    "checkoutUrl": "https://checkout.ozura.io/checkout/session_xxxxxxxxxxxxxx",
    "expiresAt": "2025-01-07T12:15:00.000Z",
    "embedCode": "<script>...</script>",
    "pricing": {
      "subtotal": 25.00,
      "tax": 0,
      "shipping": 0,
      "total": 25.00,
      "currency": "USD"
    }
  }
}

Field	What It Is
`checkoutUrl`	Send your customer here! This is the payment page URL.
`sessionId`	Save this – you’ll need it to verify the payment later.
`expiresAt`	When the session expires (customer must pay before this).
`embedCode`	Ready-to-use HTML/JS for popup/iframe modes.
`pricing`	Calculated totals (subtotal, tax, shipping, total).

What’s Next?

You have a checkoutUrl. Now redirect your customer to checkout.

Getting Started

Vault

Payments

Create a Checkout Session

Quick Start (30 seconds)

The Basics

Required Headers

Required Fields

Understanding the Three URLs

Quick Summary

successUrl – Your Confirmation Page

cancelUrl – Your “Go Back” Destination

errorUrl – Your System Error Handler

Optional Fields

Common Options

Cart Items (Alternative to Amount)

Checkout Modes (Mutually Exclusive)

Cart Item Fields

Required Fields

Visual Display Fields (Optional)

Pricing & Discount Fields (Optional)

Response

What’s Next?

Getting Started

Vault

Payments

​Quick Start (30 seconds)

​The Basics

​Required Headers

​Required Fields

​Understanding the Three URLs

​Quick Summary

​successUrl – Your Confirmation Page

​cancelUrl – Your “Go Back” Destination

​errorUrl – Your System Error Handler

​Optional Fields

​Common Options

​Cart Items (Alternative to Amount)

​Checkout Modes (Mutually Exclusive)

​Cart Item Fields

​Required Fields

​Visual Display Fields (Optional)

​Pricing & Discount Fields (Optional)

​Response

​What’s Next?

Quick Start (30 seconds)

The Basics

Required Headers

Required Fields

Understanding the Three URLs

Quick Summary

successUrl – Your Confirmation Page

cancelUrl – Your “Go Back” Destination

errorUrl – Your System Error Handler

Optional Fields

Common Options

Cart Items (Alternative to Amount)

Checkout Modes (Mutually Exclusive)

Cart Item Fields

Required Fields

Visual Display Fields (Optional)

Pricing & Discount Fields (Optional)

Response

What’s Next?