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.com/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.com/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: Developers → Vault Key.Merchant API Key: Developers → 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
`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: Transaction details and card info as URL parameters:

https://yoursite.com/success?success=true&sessionId=session_xxx&checkoutMode=payment&transactionId=2603130000113B86C&transactionType=sale&amount=25.00&currency=USD&ozuraMerchantId=ozu_abc&cardLastFour=4242&cardBrand=VISA

See Handle the Payment Result for the full parameter reference.

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)
`checkoutMode`	`"payment"`	`"payment"`, `"donation"`, or `"recurring"`
`embedMode`	`"redirect"`	`"redirect"`, `"popup"`, `"iframe"`, or `"new_tab"`. See Integration Modes
`parentOrigin`	—	Required when `embedMode` is `"popup"` or `"iframe"`. Must be a valid URL
`allowPopup`	`true`	When `false`, disables the popup upgrade path if iframe is blocked
`hideHeader`	`false`	Hides the merchant name and logo strip at the top of checkout
`surchargePercent`	—	Credit card surcharge passed to the processor. String or number, max `"3.00"` (Florida cap). E.g. `"2.50"` adds a 2.5% surcharge line to the order summary.
`transactionChannel`	`"ecommerce"`	`"ecommerce"` (customer self-serve) or `"moto"` (merchant-entered on customer’s behalf). Forwarded directly to the payment processor — the checkout UI is identical for both.
`taxExempt`	`false`	Skip sales tax calculation for this session
`idempotencyKey`	—	Unique string for network retry protection — replaying a request with the same key returns the original response without creating a duplicate session
`recurringConfig`	—	Required when `checkoutMode: "recurring"`. See Recurring Mode for the full field reference.
`donationConfig`	—	Donation preset amounts and configuration. See Donation Mode.

Tax-exempt checkout experience

When taxExempt is false (the default), the customer enters their billing details on the checkout page first — Ozura uses these to calculate sales tax — then continues to the secure payment step. When taxExempt is true, there’s no tax to calculate, so checkout skips the billing-details step and takes the customer straight to the secure payment step — a faster, more direct flow for your customers.

Only set taxExempt: true when the products or customer are genuinely tax-exempt. A tax-exempt session calculates and collects no sales tax. If you mark a taxable order as tax-exempt, no tax is collected and you remain responsible for any sales tax that should have been collected. When in doubt, leave taxExempt as false.

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

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	`checkoutMode: "donation"`	Charities, non-profits, tips
Recurring	`checkoutMode: "recurring"` + `recurringConfig`	Subscriptions, memberships

Mutual exclusivity rules: - Cannot use amount + items together - Cannot use items + checkoutMode: "donation" together - Cannot use items + checkoutMode: "recurring" — recurring requires a scalar amount - Can use amount + checkoutMode: "donation" (sets the default pre-selected donation amount)

See Donation Mode and Recurring Mode for full guides.

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 shown as a badge on the item
`sku`	string	Internal SKU or barcode shown beneath the item name (max 100 chars)
`url`	string	URL that the product name links to (HTTPS, opens in new tab)

Pricing & Discount Fields (Optional)

Field	Type	Description
`originalPrice`	number	Original price before discount (renders as strikethrough next to the final price)
`discountLabel`	string	Discount badge text shown beside the item name, e.g., `"SALE"`, `"20% OFF"`
`taxExempt`	boolean	If `true`, item displays a “Tax Free” badge
`discount`	object	Shorthand to compute the discounted price automatically — see below

discount object — pass this instead of computing price/originalPrice/discountLabel yourself:

Sub-field	Type	Description
`type`	string	`"percentage"` or `"fixed"`
`value`	number	For `percentage`: 0–100. For `fixed`: amount to subtract in currency units
`label`	string	Badge text. Auto-generated (e.g. `"20% OFF"`) if omitted

When discount is provided, the price field is treated as the original price. Checkout computes the final charge price, sets the strikethrough originalPrice, and generates a discountLabel badge automatically.

{
  "productId": "prod_annual",
  "name": "Annual Plan",
  "price": 99.0,
  "quantity": 1,
  "discount": {
    "type": "percentage",
    "value": 20,
    "label": "SAVE 20%"
  }
}

Response

{
  "success": true,
  "data": {
    "sessionId": "session_xxxxxxxxxxxxxx",
    "checkoutUrl": "https://checkout.ozura.com/checkout/session_xxxxxxxxxxxxxx",
    "expiresAt": "2025-01-07T12:15:00.000Z",
    "embedCode": "<script>...</script>",
    "pricing": {
      "subtotal": 25.0,
      "tax": 0,
      "shipping": 0,
      "total": 25.0,
      "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, 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

Tax-exempt checkout experience

Cart Items (Alternative to Amount)

Checkout Modes

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

​Tax-exempt checkout experience

​Cart Items (Alternative to Amount)

​Checkout Modes

​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

Tax-exempt checkout experience

Cart Items (Alternative to Amount)

Checkout Modes

Cart Item Fields

Required Fields

Visual Display Fields (Optional)

Pricing & Discount Fields (Optional)

Response

What’s Next?