1. Customer clicks "Pay Now" ↓2. Card data is tokenized (PCI compliant) ↓3. Payment is processed server-side ↓4. Ozura marks the session as "completed" ← Automatic! ↓5. Customer is redirected to your successUrl with payment details
Ozura marks the session complete automatically before redirecting – you don’t need to call a “complete” endpoint. However, you should verify the session status server-side before fulfilling orders to prevent URL spoofing.
After a successful payment, the customer is redirected to your successUrl with transaction details appended as query parameters. Use these to display an order confirmation.
Billing PII is not included in the redirect URL. Name, email, phone, and address are omitted from the success URL to avoid them appearing in server access logs and browser history. If you need billing details, retrieve them server-side from the session via GET /api/sessions/{sessionId}.
Parameters are only appended when the value is present in the processor response — do not assume every key is always in the URL. success, sessionId, checkoutMode, and transactionType are always present.Transaction Info:
Parameter
Description
Example
success
Always "true" for successful payments
true
sessionId
Your session ID (for verification)
session_xxxxxx
checkoutMode
Session type: payment, donation, or recurring
payment
metadata
Your custom metadata (JSON-encoded string). Internal fields apiKey, ozuraApiKey, idempotencyKey, merchantName, and waxKey are automatically filtered. For sessions that originated from a payment link, paymentLinkId is not filtered and will appear here.
const url = new URL(window.location.href);const transactionId = url.searchParams.get('transactionId');const amount = url.searchParams.get('amount');const currency = url.searchParams.get('currency');const checkoutMode = url.searchParams.get('checkoutMode');const metadata = JSON.parse(url.searchParams.get('metadata') || '{}');// Display your confirmation page with this data
Do not rely solely on redirect parameters for order fulfillment. The success redirect is a client-side browser redirect — a user could fabricate these query parameters. For backend order processing (marking orders as paid, triggering shipping, etc.), verify the transaction server-side by checking the session status via the API. The redirect data is for displaying a confirmation UI, not for trusted business logic.
When a customer cancels checkout, they are redirected back to your cancelUrl. No additional parameters are appended — this is a simple navigation back to your site.Recommended: Set cancelUrl to your cart or product page so the customer can return to shopping seamlessly. The checkout session is automatically marked as cancelled.
No special page is needed for cancelUrl. Point it at your existing cart or storefront page.
Behavior by integration mode:
Mode
What happens on cancel
Redirect
Plain redirect to cancelUrl
Iframe
Plain redirect to cancelUrl
Popup / New Tab
Popup closes automatically and a CHECKOUT_CANCELLED postMessage is sent to the opener. If window.close() fails (browser restrictions), falls back to redirecting to cancelUrl
Non-recoverable errors (system failures, authentication issues) redirect customers to errorUrl with diagnostic query parameters.
Recoverable errors like card declines are handled inline on the checkout page — the customer sees the error and can retry immediately. Only non-recoverable errors trigger the errorUrl redirect.
Recommended: Use Ozura’s default error page:
{ "errorUrl": "https://checkout.ozura.com/error"}
This provides a clean, branded error page with a “Return to Store” button that uses your cancelUrl — no extra work required.If you prefer a custom error page, parse these query parameters:
Parameter
Description
Example
success
Always "false"
false
errorCode
Machine-readable error code (see below)
SYSTEM_ERROR
error
Human-readable error message
Payment processing failed
cancelUrl
Your cancel URL (use for a “Return to Store” button)
Always verify payments server-side before fulfilling orders.
A malicious user could attempt to visit your success URL directly. Always check the session status:
app.get('/success', async (req, res) => { const { sessionId } = req.query; // Check session status with Checkout API // No headers required - session ID acts as access token const response = await fetch(`https://checkout.ozura.com/api/sessions/${sessionId}`); const data = await response.json(); if (data.data.session.status === 'completed') { // ✅ Session verified as completed // ⚠️ YOUR RESPONSIBILITY: Fulfill the order with your business logic await updateOrderStatus(sessionId, 'paid'); // YOUR implementation res.render('success'); } else { // Not confirmed - don't fulfill res.redirect('/error?error=Payment+not+confirmed'); }});
