API Reference

Complete reference for all Ozura Checkout API endpoints.

Base URL

https://checkout.ozura.com

Environments: Use https://checkout.ozura.com for production. For staging, use the URL provided by your Ozura representative.

Authentication

All requests require these headers:

Header	Description
`X-API-KEY`	Your Vault API Key
`X-OZURA-API-KEY`	Your Merchant API Key
`Content-Type`	`application/json`

Rate Limits

Rate limits are applied per API key to ensure fair usage. If you exceed rate limits, you’ll receive a 429 Too Many Requests response.

Create Session

Creates a checkout session and returns a checkout URL.

POST /api/sessions/create

Request Body

Field	Type	Required	Default	Description
`merchantId`	string	Yes	—	Your Merchant ID
`merchantName`	string	Yes	—	Business name shown to customer
`amount`	string/number	Yes*	—	Payment amount
`currency`	string	No	`"USD"`	Currency code
`successUrl`	string	Yes	—	Redirect after successful payment
`cancelUrl`	string	Yes	—	“Go back” destination
`errorUrl`	string	Yes	—	Redirect if payment fails
`embedMode`	string	No	`"redirect"`	`"redirect"`, `"popup"`, `"iframe"`, `"new_tab"`
`parentOrigin`	string	Cond.	—	Required for `embedMode: "popup"` and `"iframe"`
`checkoutMode`	string	No	`"payment"`	`"payment"`, `"donation"`, or `"recurring"`
`recurringConfig`	object	Cond.	—	Required when `checkoutMode: "recurring"`. See Recurring Mode
`donationConfig`	object	No	—	Donation settings. See Donation Mode
`surchargePercent`	string/number	No	No surcharge (treated as `0%` at charge time)	Credit card surcharge, max `"3.00"` (3%). Shown as a line item when set
`transactionChannel`	string	No	`"ecommerce"`	`"ecommerce"` or `"moto"`. Forwarded to the payment processor
`taxExempt`	boolean	No	`false`	Skip sales tax calculation for this session
`items`	array	No	—	Cart items (alternative to `amount`). Not allowed with `recurring` mode
`metadata`	object	No	`{}`	Custom data (max 10KB), returned in the success URL
`appearance`	object	No	`{}`	Styling options — see Appearance Reference
`idempotencyKey`	string	No	—	Unique key for network retry protection
`allowPopup`	boolean	No	`true`	Allow popup-mode upgrade when iframe is blocked
`hideHeader`	boolean	No	`false`	Hide the merchant name / logo header
`donationConfig`	object	No	—	Donation preset amounts and limits. See Donation Mode

*amount is required when checkoutMode is "payment" or "recurring" and items is not provided. Not required for "donation" mode.

Deprecated fields: taxRate and shippingCost are accepted and validated but ignored — they have no effect on pricing. Do not send these fields in new integrations.

Response

{
  "success": true,
  "data": {
    "sessionId": "session_xxxxxxxxxxxxxx",
    "checkoutUrl": "https://checkout.ozura.com/checkout/session_xxxxxxxxxxxxxx",
    "expiresAt": "2025-01-07T12:15:00.000Z",
    "embedCode": "<!-- HTML embed snippet based on embedMode -->",
    "pricing": {
      "subtotal": 55.00,
      "tax": 0,
      "shipping": 0,
      "total": 55.00,
      "currency": "USD"
    }
  }
}

The response may also include a top-level "warnings" array with advisory messages. On an idempotent replay (same idempotencyKey), "cached": true is added at the top level and a new session is not created.

Get Session

Retrieve session details. The session ID acts as the access token — no additional authentication headers are required.

GET /api/sessions/{sessionId}

Response

The full session object is returned. Key fields include:

{
  "success": true,
  "data": {
    "session": {
      "id": "session_xxxxxxxxxxxxxx",
      "status": "pending",
      "amount": "25.00",
      "currency": "USD",
      "merchantId": "your_merchant_id",
      "checkoutMode": "payment",
      "embedMode": "redirect",
      "taxExempt": false,
      "appearance": {},
      "metadata": {
        "merchantName": "My Store",
        "orderId": "order_123"
      },
      "recurringConfig": null,
      "surchargePercent": null,
      "transactionChannel": "ecommerce",
      "expiresAt": "2025-01-07T12:15:00.000Z",
      "createdAt": "2025-01-07T11:45:00.000Z"
    },
    "pricing": {
      "subtotal": 25.00,
      "tax": 0,
      "shipping": 0,
      "total": 25.00,
      "currency": "USD"
    },
    "items": []
  }
}

merchantName is stored inside metadata, not as a top-level session field. For recurring sessions, recurringConfig contains the full plan config object. The metadata object may contain internal fields used by the checkout page — do not expose, log, or forward the full metadata object to clients.

Session Statuses

Status	Description
`pending`	Awaiting payment
`completed`	Payment successful
`cancelled`	Customer cancelled
`expired`	Session timed out
`failed`	Payment failed

Cancel Session

Cancels a pending session. This endpoint is called automatically by the Ozura checkout page when the customer clicks “Cancel” — you do not need to call it from your server.

POST /api/sessions/{sessionId}/cancel

This endpoint is browser-facing. It is called by the checkout page using a short-lived internal session credential. It cannot be called from your server using your Vault API Key — requests with X-API-KEY are rejected. If a session is not cancelled explicitly, it expires automatically after 30 minutes.

Response

{
  "success": true
}

Create Payment Link

Creates a reusable payment URL.

POST /api/payment-links/create

Request Body

Field	Type	Required	Default	Description
`merchantId`	string	Yes	—	Your Merchant ID
`merchantName`	string	Yes	—	Business name shown to customer
`amount`	string	Yes*	—	Payment amount
`currency`	string	No	`"USD"`	Currency code
`successUrl`	string	Yes	—	Redirect after payment
`cancelUrl`	string	Yes	—	Redirect if cancelled
`errorUrl`	string	Yes	—	Redirect if failed
`checkoutMode`	string	No	`"payment"`	`"payment"`, `"donation"`, or `"recurring"`
`recurringConfig`	object	Cond.	—	Required when `checkoutMode: "recurring"`. See Recurring Mode
`donationConfig`	object	No	—	Donation settings. See Donation Mode
`surchargePercent`	string/number	No	No surcharge	Credit card surcharge, max `"3.00"` (3%)
`transactionChannel`	string	No	`"ecommerce"`	`"ecommerce"` or `"moto"`
`taxExempt`	boolean	No	`false`	Skip sales tax calculation for this link’s sessions
`embedMode`	string	No	`"redirect"`	`"redirect"`, `"popup"`, `"iframe"`, `"new_tab"`. Stored on the link but payment links always open checkout as redirect — this field is persisted for informational purposes only
`parentOrigin`	string	Cond.	—	Required if `embedMode` is `"popup"` or `"iframe"`
`allowPopup`	boolean	No	`true`	Allow popup-mode upgrade when iframe is blocked
`hideHeader`	boolean	No	`false`	Hide the merchant name / logo header
`items`	array	No	—	Cart items (alternative to `amount`)
`metadata`	object	No	`{}`	Custom data (max 10KB)
`merchantPayLinkReference`	string	No	—	Link-scoped correlation ID returned on every transaction from this link, inside the success `metadata`. Max 128 chars: letters, numbers, `. _ : -`.
`appearance`	object	No	`{}`	Styling options — see Appearance Reference
`idempotencyKey`	string	No	—	Unique key for network retry protection
`expiresInDays`	number	No	`7`	Days until link expires
`usageLimit`	number	No	`null` (unlimited)	Max successful payments before the link is deactivated

*Required when checkoutMode is "payment" or "recurring" and items is not provided. Not required for donation mode.

Correlating payments to your orders. Payment links support three correlation references, all returned in the success-redirect metadata (see Correlate Payments to Your Orders for the full guide):

merchantPayLinkReference — set here at link creation; static, returned on every transaction from the link (attribute a link/campaign).
merchantReference — set per checkout via a ?ref= query parameter appended to the link URL (not a request-body field); unique per payer.
merchantRecurringReference — for recurring links, set inside recurringConfig; also persisted on the plan so you can look the plan up by it.

Response

{
  "success": true,
  "data": {
    "paymentLinkId": "pl_xxxxxxxxxxxxxx",
    "url": "https://checkout.ozura.com/pay/pl_xxxxxxxxxxxxxx",
    "expiresAt": "2025-01-14T00:00:00.000Z"
  }
}

On an idempotent replay (same idempotencyKey), the response also includes "cached": true. Either response may include a top-level "warnings" array with merchant-facing advisory messages.

Check Payment Link Availability

Check if a payment link is still valid. No authentication required.

GET /api/payment-links/{linkId}/check-availability

Response (Available)

{
  "success": true,
  "available": true,
  "message": "Payment link is available"
}

Response (Unavailable)

{
  "success": false,
  "available": false,
  "error": "Payment link usage limit reached"
}

Error Responses

All errors follow this format:

{
  "success": false,
  "error": "Human-readable error message",
  "details": ["Field-level detail — only present for validation errors"]
}

details is only included when there are multiple specific validation failures (e.g. several invalid fields at once). Single-field and non-validation errors return error only.

Common Error Codes

Code	Meaning
`400`	Bad request (validation failed)
`401`	Invalid or missing API credentials
`404`	Session not found
`409`	Conflict — session already completed, or `idempotencyKey` reuse rejected (see below)
`410`	Session expired
`429`	Too many requests (rate limit exceeded)
`500`	Server error (retry recommended)

Idempotency Conflict Codes

When you replay a request with an idempotencyKey that does not match the original active session, the API returns 409 with one of these machine-readable errorCode values:

`errorCode`	Meaning
`IDEMPOTENCY_KEY_EXPIRED_SESSION`	The session previously created with this `idempotencyKey` has expired. Use a new `idempotencyKey` to create a fresh session
`IDEMPOTENCY_KEY_TERMINAL_SESSION`	The session for this `idempotencyKey` is in a terminal state (`cancelled` or `failed`). Use a new `idempotencyKey`

​Base URL

​Authentication

​Rate Limits

​Create Session

​Request Body

​Response

​Get Session

​Response

​Session Statuses

​Cancel Session

​Response

​Create Payment Link

​Request Body

​Response

​Check Payment Link Availability

​Response (Available)

​Response (Unavailable)

​Error Responses

​Common Error Codes

​Idempotency Conflict Codes

Base URL

Authentication

Rate Limits

Create Session

Request Body

Response

Get Session

Response

Session Statuses

Cancel Session

Response

Create Payment Link

Request Body

Response

Check Payment Link Availability

Response (Available)

Response (Unavailable)

Error Responses

Common Error Codes

Idempotency Conflict Codes