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 (payments fail with any other value)	`"merchant_abc123"`
`merchantName`	Your business name (customer sees this)	`"Bob's Coffee Shop"`
`amount`	How much to charge, in dollars (not cents)*	`"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), in major currency units: 25.00 is $25.00, and `10000` is $10,000.00 (not $100). 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"`, or `"new_tab"`. `"iframe"` is coming soon; for now it runs as `"redirect"` and the response includes an `EMBED DOWNGRADE` warning. See Integration Modes
`parentOrigin`	—	Exact origin of the page that opens checkout, e.g. `"https://yoursite.com"`. Required for `"popup"`; needed for `"new_tab"` to receive events. Result events are sent only to this origin
`allowPopup`	`true`	Accepted for compatibility; currently has no effect
`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. Ignored on hosted payment sessions (the default), where any surcharge is applied by the processor’s payment page; see Surcharge.
`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, and shows the exact tax in the order summary (see Sales tax in the order summary) — 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.

Sales tax in the order summary

When the session isn’t tax-exempt, checkout shows the customer the exact tax before they continue to payment. It comes from the same calculation that sets the tax on the charge, so the tax shown is the tax charged. Tax is added on top of your amount, so set prices excluding tax. Outside the US this is the country’s VAT, GST or sales tax; see International billing addresses for the countries covered.

Before the address is complete, the tax line reads Calculated once you enter your billing address. Checkout doesn’t show an estimate.
Once the address is complete, checkout calculates the tax for it. The tax line shows Calculating tax…, then the exact amount (for example $9.75), and the total includes it. What “complete” means depends on the country:
- United States: street address, city, state and ZIP code. ZIP codes must be 5 digits or ZIP+4; anything else is rejected on the form with Please enter a 5-digit ZIP code.
- Canada: street address, city, province (code or name, e.g. ON or Ontario) and a postal code in the A1A 1A1 format.
- Every other country: street address and city.
Addresses with no tax due (for example a US state with no sales tax) show No sales tax for this address.
Billing countries where Ozura doesn’t calculate tax show No sales tax for this country, and no tax is added.
If a US state doesn’t match the ZIP code, tax is calculated from the ZIP code.

Only the billing address is used to calculate tax; the customer’s name, email and phone are not. The customer never has to wait for the calculation: Continue to payment works while tax is still calculating. For recurring sessions, the summary shows the exact tax on the first charge (Due today) and on the regular charge.

If the address can’t be verified

If the billing address is rejected (for example, a ZIP code that doesn’t exist), the tax line reads Check your billing address. The first click on Continue to payment shows Make sure your billing address is correct! We couldn’t calculate tax for it. If it’s right, press Continue to payment again. The customer can correct the address, or click again to continue. Tax is always calculated again before the secure payment page opens. If that calculation fails, the payment page doesn’t open: the customer stays on checkout with There was a problem calculating your tax. Please make sure your billing address is correct. (or We couldn’t calculate tax right now. Please try again.) and can correct the address and try again on the same session. No customer reaches the payment page without sales tax calculated. After 5 failed attempts on one session, checkout cancels the session.

If the tax preview is unavailable

If the order summary can’t load the tax (for example, during a brief outage), it shows We couldn’t preview your tax. It will be calculated when you continue. with a Try again link. The customer isn’t blocked: tax is still calculated before the payment page opens, as described above.

International billing addresses

Checkout takes billing addresses from any country. Ozura calculates tax for the countries below; for any other billing country, no tax is added (No sales tax for this country).

Countries where tax is calculated

Americas: United States, Canada, Argentina, Bahamas, Barbados, Chile, Colombia, Peru, UruguayEurope: Albania, Austria, Belgium, Bulgaria, Croatia, Cyprus, Czechia, Denmark, Estonia, Finland, France, Georgia, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Moldova, Montenegro, Netherlands, North Macedonia, Norway, Poland, Portugal, Romania, Serbia, Slovakia, Slovenia, Spain, Sweden, Switzerland, Türkiye, United KingdomAsia-Pacific: Australia, Bangladesh, Hong Kong, India, Indonesia, Japan, Kazakhstan, Laos, Macao, Malaysia, New Zealand, Philippines, Singapore, South Korea, Taiwan, Thailand, VietnamMiddle East and Africa: Bahrain, Benin, Cameroon, Cape Verde, Côte d’Ivoire, Egypt, Ghana, Israel, Kenya, Morocco, Niger, Nigeria, Oman, Saudi Arabia, South Africa, Tanzania, Uganda, United Arab Emirates

Countries not supported yet

Tax isn’t available yet for billing addresses in Mexico, China, Paraguay and Costa Rica, so payments from these countries can’t be completed for now:

The tax line reads Not available for this country yet.
The first click on Continue to payment shows Sales tax isn’t available for your billing country yet, so this payment may not go through. Check the country, or contact the merchant.
If the customer continues anyway, the payment is refused with Sales tax isn’t available for your billing country yet, so this payment can’t be completed. Please contact the merchant. Nothing is charged, and the customer stays on checkout.

The address form follows the billing country

When the customer picks their billing country, the form adapts to it:

Field names match the country, for example State and ZIP code in the US, Province and Postal code in Canada, County and Postcode in the United Kingdom, Prefecture in Japan, PIN code in India and Emirate in the United Arab Emirates.
Region and postal code are required wherever the country uses them.
No postal code field is shown for countries without postal codes: Hong Kong, Macao, United Arab Emirates, Ghana, Uganda, Cameroon, Côte d’Ivoire, Benin and the Bahamas.
The phone country code follows the billing country; the customer can change it.

Names and addresses in Latin letters

Names and addresses must be written in Latin letters, because that’s what card processors accept. Accented letters are fine: checkout sends them to the processor as plain letters (José Müller becomes Jose Muller). Text in other scripts, such as Japanese, Chinese or Arabic, is refused on the form with a message such as Please enter your name using Latin letters (A-Z).

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 the session’s `embedMode`.
`embedMode`	The mode the session actually runs in. A request for `"iframe"` comes back as `"redirect"`.
`warnings`	Present when something in your request was adjusted, e.g. the `EMBED DOWNGRADE` message for `"iframe"`.
`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

Sales tax in the order summary

If the address can’t be verified

If the tax preview is unavailable

International billing addresses

Countries not supported yet

The address form follows the billing country

Names and addresses in Latin letters

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

​Sales tax in the order summary

​If the address can’t be verified

​If the tax preview is unavailable

​International billing addresses

​Countries not supported yet

​The address form follows the billing country

​Names and addresses in Latin letters

​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

Sales tax in the order summary

If the address can’t be verified

If the tax preview is unavailable

International billing addresses

Countries not supported yet

The address form follows the billing country

Names and addresses in Latin letters

Cart Items (Alternative to Amount)

Checkout Modes

Cart Item Fields

Required Fields

Visual Display Fields (Optional)

Pricing & Discount Fields (Optional)

Response

What’s Next?