Complete reference for all Ozura Checkout API endpoints.
Base URL
https://checkout.ozura.io
Environments: Use https://checkout.ozura.io 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 popup and iframe |
metadata | object | No | {} | Custom data (max 10KB) |
appearance | object | No | {} | Styling options |
items | array | No | — | Cart items (alternative to amount) |
checkoutMode | string | No | "payment" | "payment" or "donation" |
donationConfig | object | No | — | Donation settings |
idempotencyKey | string | No | — | Unique key for retry protection |
items is not provided and checkoutMode is "payment".
Response
{
"success": true,
"data": {
"sessionId": "session_xxxxxxxxxxxxxx",
"checkoutUrl": "https://checkout.ozura.io/checkout/session_xxxxxxxxxxxxxx",
"expiresAt": "2025-01-07T12:15:00.000Z",
"embedCode": "<script>...</script>",
"pricing": {
"subtotal": 55.00,
"tax": 0,
"shipping": 0,
"total": 55.00,
"currency": "USD"
}
}
}
Get Session
Retrieve session details. The session ID acts as the access token - no additional authentication headers are required.
GET /api/sessions/{sessionId}
Response
{
"success": true,
"data": {
"session": {
"id": "session_xxxxxxxxxxxxxx",
"status": "pending",
"amount": "25.00",
"currency": "USD",
"merchantId": "your_merchant_id",
"merchantName": "My Store"
},
"pricing": {
"subtotal": 25.00,
"tax": 0,
"shipping": 0,
"total": 25.00,
"currency": "USD"
}
}
}
Session Statuses
| Status | Description |
|---|
pending | Awaiting payment |
completed | Payment successful |
cancelled | Customer cancelled |
expired | Session timed out |
failed | Payment failed |
Cancel Session
Cancel a pending session (from your server).
POST /api/sessions/{sessionId}/cancel
| Header | Description |
|---|
X-API-KEY | Your Vault API Key |
X-OZURA-API-KEY | Your Merchant API Key |
Response
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 |
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 |
expiresInDays | number | No | 7 | Days until link expires |
usageLimit | number | No | null | Max payments (null = unlimited) |
items.
Response
{
"success": true,
"data": {
"paymentLinkId": "pl_xxxxxxxxxxxxxx",
"url": "https://checkout.ozura.io/pay/pl_xxxxxxxxxxxxxx",
"expiresAt": "2025-01-14T00:00:00.000Z"
}
}
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": "Error message",
"details": ["Optional array of specific errors"]
}
Common Error Codes
| Code | Meaning |
|---|
200 | Success |
400 | Bad request (validation failed) |
401 | Invalid or missing API credentials |
404 | Session not found |
409 | Conflict (session already completed) |
410 | Session expired |
500 | Server error (retry recommended) |
