> ## 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
```

> [!NOTE]
>
> **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.

```json theme={null}
{
  "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](https://docs.ozura.com/guides/payments/checkout/integration-modes.md#iframe-mode-coming-soon) |
| `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](https://docs.ozura.com/guides/payments/checkout/recurring-mode.md) |
| `donationConfig` | object | No | — | Donation settings. See [Donation Mode](https://docs.ozura.com/guides/payments/checkout/donation-mode.md) |
| `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](https://docs.ozura.com/guides/payments/checkout/appearance-reference.md) |
| `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](https://docs.ozura.com/guides/payments/checkout/donation-mode.md) |

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

> [!NOTE]
>
> **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": "<!-- 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:

```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": []
  }
}
```

> [!NOTE]
>
> `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
```

> [!NOTE]
>
> 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](https://docs.ozura.com/guides/payments/checkout/recurring-mode.md) |
| `donationConfig` | object | No | — | Donation settings. See [Donation Mode](https://docs.ozura.com/guides/payments/checkout/donation-mode.md) |
| `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](https://docs.ozura.com/guides/payments/checkout/appearance-reference.md) |
| `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.

> [!NOTE]
>
> **Correlating payments to your orders.** Payment links support three correlation references, all returned in the success-redirect `metadata` (see [Correlate Payments to Your Orders](https://docs.ozura.com/guides/payments/checkout/payment-links.md#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`](https://docs.ozura.com/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: 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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.