Payment Links

Create reusable payment URLs for email campaigns, social media, or invoices.

What Are Payment Links?

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

Create a Payment Link

POST /api/payment-links/create

Headers

Header	Value
`Content-Type`	`application/json`
`X-API-KEY`	Your Vault API Key
`X-OZURA-API-KEY`	Your Merchant API Key

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 (e.g., `"25.00"`)
`currency`	string	No	`"USD"`	Currency code
`successUrl`	string	Yes	—	Redirect after payment
`cancelUrl`	string	Yes	—	Redirect if cancelled
`errorUrl`	string	Yes	—	Redirect if failed
`metadata`	object	No	`{}`	Custom data (max 10KB) passed to each session spawned from this link
`expiresInDays`	number	No	`7`	Days until link expires (1-3650)
`usageLimit`	number	No	`null`	Max payments (null for unlimited)
`merchantPayLinkReference`	string	No	—	Link-scoped correlation ID returned on every transaction from this link (max 128 chars; letters, numbers, `. _ : -`). See Correlate Payments to Your Orders.

*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:

A new checkout session is created automatically
They see the checkout page with the amount you specified
After payment, they’re redirected to your success URL

Correlate Payments to Your Orders

Because a reusable link shares one paymentLinkId across every customer, that ID alone can’t tell you which of your orders a given payment belongs to. Ozura gives you two correlation references, and they work together:

merchantReference — a per-payer value you set via a ?ref= query parameter, unique to each checkout. Use it to tie a payment to a specific order or customer.
merchantPayLinkReference — a static, link-level value you set once when creating the link. It comes back on every transaction from that link, so you can identify which link or campaign produced a payment.

To tie a payment back to your own order or customer, append a ref query parameter when you render the link for that customer:

https://checkout.ozura.com/pay/pl_xxxxxxxxxxxxxx?ref=ORD-12345

Ozura captures ref on the checkout session and returns it to you after a successful payment as merchantReference — alongside the paymentLinkId and the processor transactionId — so you can match the transaction to your order without guesswork.

This is the recommended setup for links embedded on your website (a “Pay” button, a stored link, etc.). Render the link per customer with that customer’s order ID in ref. You choose the value.

How it comes back

After payment, ref is returned inside the metadata object appended to your successUrl, as merchantReference:

https://yoursite.com/thank-you?success=true&transactionId=2603130000113B86C&amount=25.00&metadata=%7B%22paymentLinkId%22%3A%22pl_xxx%22%2C%22merchantReference%22%3A%22ORD-12345%22%7D

const params = new URL(location.href).searchParams;
const metadata = JSON.parse(params.get('metadata') || '{}');

metadata.merchantReference; // "ORD-12345"        ← the value you set in ?ref=
metadata.paymentLinkId;     // "pl_xxxxxxxxxxxxxx"
const transactionId = params.get('transactionId');

// Look up your order by merchantReference, then record transactionId against it.

See Handle the Payment Result for every success parameter.

Requirements for `ref`

Rule	Detail
Opaque ID only	Use an order ID, cart ID, or similar. Never put PII (names, emails) or secrets in `ref` — it is visible in the URL, browser history, and server logs.
Allowed characters	Letters, numbers, and `. _ : -` only. URL-encode the value before appending it.
Max length	128 characters.
Invalid values are dropped	A `ref` with disallowed characters or over 128 characters is ignored — the payment still succeeds, but no `merchantReference` is returned. Validate the value on your side before building the link.
One value per customer	Generate the `ref` per checkout so each payment maps to exactly one of your orders.

The shopper’s browser supplies ref in the URL, so treat merchantReference as a correlation hint, not a trusted value — a customer could change it. Always confirm the payment server-side before fulfilling an order, and reconcile on the transactionId.

Link-level reference (`merchantPayLinkReference`)

When you need the same value returned on every payment from a link — for example to attribute payments to a campaign, an invoice batch, or the link itself — set merchantPayLinkReference when you create the link (see the request body above):

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",
    "successUrl": "https://mystore.com/thank-you",
    "cancelUrl": "https://mystore.com/cancelled",
    "errorUrl": "https://mystore.com/error",
    "merchantPayLinkReference": "CAMPAIGN-Q3"
  }'

Every transaction created from that link then returns merchantPayLinkReference in the same metadata object as merchantReference and paymentLinkId. It follows the same character/length rules as ref (max 128 chars; letters, numbers, . _ : -). merchantPayLinkReference and ?ref= compose — a single payment can return both: the link/campaign it came from, and the specific order that payer was checking out.

Which reference should I use?

	Set when	Same for every payer?	Returned on	Use for
Link `metadata`	At link creation	Yes — baked into the link	Every txn from the link	Arbitrary static data (SKU, notes)
`merchantPayLinkReference`	At link creation	Yes — one value per link	Every txn from the link	Which link/campaign produced the payment
`ref` → `merchantReference`	Per click, as you render the link	No — unique per customer	The one txn for that checkout	Per-order / per-customer correlation

For recurring payment links there is a third reference, merchantRecurringReference, which is tied to the subscription plan — set it in recurringConfig. It’s returned in the success metadata alongside the other two, and is also persisted on the plan so you can look the plan up by it. See Recurring Payments.

Coming soon — server-to-server delivery. Today merchantReference and merchantPayLinkReference are returned on the success redirect (above). We’re rolling out delivery of these references on your transaction webhook, plus the ability to look them up directly — so you’ll be able to reconcile orders entirely server-side, even if a customer never returns to your successUrl. No integration changes will be needed: start setting them now and they will flow through automatically the moment this lands.

One-Time vs Reusable Links

One-Time Payment Link (Invoice style):

{
  "usageLimit": 1
}

Reusable Link (Donation/Tip Jar style):

{
  "usageLimit": null
}

Limited Uses:

{
  "usageLimit": 100
}

Itemized Product Link

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"
}

Donation Link

{
  "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
}

Check Link Availability

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"
}

​What Are Payment Links?

​Create a Payment Link

​Headers

​Request Body

​Example Request

​Response

​Branding and appearance

​Share the Link

​Correlate Payments to Your Orders

​How it comes back

​Requirements for ref

​Link-level reference (merchantPayLinkReference)

​Which reference should I use?

​One-Time vs Reusable Links

​Itemized Product Link

​Donation Link

​Check Link Availability

What Are Payment Links?

Create a Payment Link

Headers

Request Body

Example Request

Response

Branding and `appearance`

Share the Link

Correlate Payments to Your Orders

How it comes back

Requirements for `ref`

Link-level reference (`merchantPayLinkReference`)

Which reference should I use?

One-Time vs Reusable Links

Itemized Product Link

Donation Link

Check Link Availability