Skip to main content

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.

Create reusable payment URLs for email campaigns, social media, or invoices. Payment Links are URLs you can share with customers. When they click the link, a checkout session is automatically created for them. Perfect for:
  • Email invoices
  • Social media bio links
  • SMS campaigns
  • QR codes
  • Donation pages
POST /api/payment-links/create

​
Headers

HeaderValue
Content-Typeapplication/json
X-API-KEYYour Vault API Key
X-OZURA-API-KEYYour Merchant API Key

​
Request Body

FieldTypeRequiredDefaultDescription
merchantIdstringYes—Your Merchant ID
merchantNamestringYes—Business name shown to customer
amountstringYes*—Payment amount (e.g., "25.00")
currencystringNo"USD"Currency code
successUrlstringYes—Redirect after payment
cancelUrlstringYes—Redirect if cancelled
errorUrlstringYes—Redirect if failed
metadataobjectNo{}Custom data (max 10KB) passed to each session spawned from this link
expiresInDaysnumberNo7Days until link expires (1-3650)
usageLimitnumberNonullMax payments (null for unlimited)
*Not required when using items or checkoutMode: "donation".

​
Example Request

curl -X POST https://checkout.ozura.com/api/payment-links/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_vault_api_key" \
  -H "X-OZURA-API-KEY: your_merchant_api_key" \
  -d '{
    "merchantId": "your_merchant_id",
    "merchantName": "My Store",
    "amount": "50.00",
    "currency": "USD",
    "successUrl": "https://mystore.com/thank-you",
    "cancelUrl": "https://mystore.com/cancelled",
    "errorUrl": "https://mystore.com/error",
    "expiresInDays": 7,
    "usageLimit": 1,
    "metadata": {
      "invoiceId": "INV-12345"
    }
  }'

​
Response

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

​
Branding and appearance

Payment links store the same request fields as session creation. Include an appearance object (and merchantName) on create payment link to brand every session spawned from that link. Options match Customize Appearance and the Appearance Reference. Send the url from the response to your customer: 
https://checkout.ozura.com/pay/pl_xxxxxxxxxxxxxx
When they click it:
  1. A new checkout session is created automatically
  2. They see the checkout page with the amount you specified
  3. After payment, they’re redirected to your success URL
One-Time Payment Link (Invoice style): 
{
  "usageLimit": 1
}
Reusable Link (Donation/Tip Jar style): 
{
  "usageLimit": null
}
Limited Uses: 
{
  "usageLimit": 100
}
Create a payment link with a rich itemized checkout display: 
{
  "merchantId": "store_abc123",
  "merchantName": "Fashion Boutique",
  "items": [
    {
      "productId": "JACKET-001",
      "name": "Winter Jacket",
      "price": 149.99,
      "quantity": 1,
      "imageUrl": "https://cdn.example.com/jacket.jpg",
      "originalPrice": 199.99,
      "discountLabel": "25% OFF"
    }
  ],
  "currency": "USD",
  "successUrl": "https://fashionboutique.com/thank-you",
  "cancelUrl": "https://fashionboutique.com/cart",
  "errorUrl": "https://fashionboutique.com/error"
}

{
  "merchantId": "charity_abc123",
  "merchantName": "Save The Whales Foundation",
  "successUrl": "https://savethewhales.org/thank-you",
  "cancelUrl": "https://savethewhales.org/donate",
  "errorUrl": "https://savethewhales.org/error",
  "checkoutMode": "donation",
  "donationConfig": {
    "presets": [25, 50, 100, 250],
    "defaultAmount": 50,
    "allowCustomAmount": true
  },
  "expiresInDays": 365,
  "usageLimit": null
}
Before directing a customer to a payment link, you can verify it’s still valid: 
GET /api/payment-links/{linkId}/check-availability
Response (Available): 
{
  "success": true,
  "available": true,
  "message": "Payment link is available"
}
Response (Limit Reached): 
{
  "success": false,
  "available": false,
  "error": "Payment link usage limit reached"
}