> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ozura.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Complete reference for all Ozura Checkout API endpoints
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](/guides/payments/checkout/recurring-mode) |
| `donationConfig` | object | No | — | Donation settings. See [Donation Mode](/guides/payments/checkout/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](/guides/payments/checkout/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](/guides/payments/checkout/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
```json theme={null}
{
"success": true,
"data": {
"sessionId": "session_xxxxxxxxxxxxxx",
"checkoutUrl": "https://checkout.ozura.com/checkout/session_xxxxxxxxxxxxxx",
"expiresAt": "2025-01-07T12:15:00.000Z",
"embedCode": "",
"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:
```json theme={null}
{
"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
```json theme={null}
{
"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](/guides/payments/checkout/recurring-mode) |
| `donationConfig` | object | No | — | Donation settings. See [Donation Mode](/guides/payments/checkout/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](/guides/payments/checkout/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](/guides/payments/checkout/payment-links#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`](/guides/payments/checkout/recurring-mode); also persisted on the plan so you can look the plan up by it.
### Response
```json theme={null}
{
"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)
```json theme={null}
{
"success": true,
"available": true,
"message": "Payment link is available"
}
```
### Response (Unavailable)
```json theme={null}
{
"success": false,
"available": false,
"error": "Payment link usage limit reached"
}
```
## Error Responses
All errors follow this format:
```json theme={null}
{
"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` |