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

Every Create Session and Create Payment Link request checks your API keys. If too many requests check the Vault API Key in a short time, the request is rejected with 429 Too Many Requests and errorCode: "VAULT_RATE_LIMITED". This says nothing about your key: wait for the number of seconds in the Retry-After header, then send the same request again. When you create many sessions or links at once, space the requests out instead of sending them in one burst.

{
  "success": false,
  "error": "Too many requests: the Vault API key could not be checked. Please retry shortly.",
  "errorCode": "VAULT_RATE_LIMITED"
}

If the key check can’t be completed at all, the request is rejected with 503 Service Unavailable and errorCode: "VAULT_UNAVAILABLE". Retry with backoff. Opening a payment link is also limited per visitor. A visitor who opens payment links too quickly in a short time sees a “Please Wait” page, which links back to your cancelUrl, and can try again a moment later.

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 in major currency units (dollars for USD, not cents): `"25.00"` charges $25.00
`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"`, or `"new_tab"`. `"iframe"` is coming soon; for now it is accepted but runs as `"redirect"` with an `EMBED DOWNGRADE` warning. See Integration Modes
`parentOrigin`	string	Cond.	—	Origin of the page that opens checkout (e.g. `"https://yoursite.com"`). Required for `embedMode: "popup"`; needed for `"new_tab"` to receive events. Result events are sent only to this origin
`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`	Accepted for compatibility; currently has no effect
`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, for example an EMBED DOWNGRADE message when you request embedMode: "iframe" (the session then runs as "redirect"). 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"` (validation only; payment links always open as redirect)
`allowPopup`	boolean	No	`true`	Accepted for compatibility; currently has no effect
`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: the API key check was throttled (`errorCode: "VAULT_RATE_LIMITED"`). Retry after `Retry-After` seconds
`500`	Server error (retry recommended)
`503`	The API key check couldn’t be completed (`errorCode: "VAULT_UNAVAILABLE"`). Retry with backoff

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