Handle the Payment Result

After the customer completes checkout, they’re sent back to your website. Here’s what happens.

What Ozura Does Automatically

When a customer successfully pays:

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.

URL Overview

URL	Who hosts it?	Query params?	Purpose
`successUrl`	Merchant	Yes — transaction data	Order confirmation page
`cancelUrl`	Merchant	No	Return to cart / storefront
`errorUrl`	Ozura (recommended) or Merchant	Yes — error code + message	Non-recoverable error display

Possible Outcomes

Outcome	Where Customer Ends Up	Session Status
Payment succeeded	Your `successUrl`	`completed`
Fixable error (card declined)	Stays on checkout – inline error shown	`pending`
Unrecoverable error (system issue)	Your `errorUrl` with error details	`failed`
Customer cancelled	Your `cancelUrl`	`cancelled`
Session expired	Ozura expiration page → button → your `cancelUrl`	`expired`

Success URL

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.

https://yoursite.com/success?success=true&sessionId=session_xxx&checkoutMode=payment&transactionId=2603130000113B86C&transactionType=sale&amount=25.00&currency=USD&ozuraMerchantId=ozu_abc&cardLastFour=4242&cardBrand=VISA&metadata=%7B%22orderId%22%3A%22order_123%22%7D

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

Success URL Parameters

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 payment-link sessions, `paymentLinkId` appears here; `merchantReference` appears when you append a `ref` to the link, `merchantPayLinkReference` when the link was created with one, and (for recurring checkouts) `merchantRecurringReference` from the plan — see Correlate Payments to Your Orders.	`{"paymentLinkId":"pl_xxx","merchantReference":"ORD-12345","merchantPayLinkReference":"CAMPAIGN-Q3","merchantRecurringReference":"SUB-CUST-123"}`
`transactionId`	Unique transaction ID from the payment processor	`2603130000113B86C`
`transactionType`	Type of transaction	`sale`
`amount`	Final charged amount (includes tax/surcharge)	`25.00`
`currency`	ISO 4217 currency code	`USD`
`ozuraMerchantId`	Your merchant ID	`ozu_abc123`
`surchargeAmount`	Surcharge applied (if any)	`0.00`
`tipAmount`	Tip amount (if any)	`0.00`
`transDate`	Transaction timestamp (ISO 8601)	`2026-03-13T19:25:47.276Z`

Card Info:

Parameter	Description	Example
`cardLastFour`	Last 4 digits of card	`0002`
`cardExpMonth`	Card expiration month	`12`
`cardExpYear`	Card expiration year	`31`
`cardBrand`	Card network	`VISA`

Reading the Data

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

transaction_id = request.args.get('transactionId')
amount = request.args.get('amount')
checkout_mode = request.args.get('checkoutMode')

$transactionId = $_GET['transactionId'];
$amount = $_GET['amount'];
$checkoutMode = $_GET['checkoutMode'];

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.

Cancel URL

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`

Error URL

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)	`https://yoursite.com/cart`

Error Codes

Code	Meaning	When it triggers
`SESSION_FAILED`	Session is in a failed state	Session loaded but its status is already `failed`
`SYSTEM_ERROR`	Non-recoverable processing error	Server error, network failure, or unexpected exception during payment
`MANUAL_REVIEW`	Transaction flagged for manual review	Payment processor returned an ambiguous result requiring review
`FORBIDDEN`	Too many failed payment attempts	Customer exceeded the per-session attempt limit

Always Verify Before Fulfilling Orders

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');
  }
});

Session Statuses

Status	What It Means	Redirects To
`pending`	Waiting for payment (not done yet)	—
`completed`	Payment successful	`successUrl`
`failed`	Payment attempt failed	`errorUrl`
`cancelled`	Customer clicked cancel	`cancelUrl`
`expired`	Session timed out (30 minutes)	`cancelUrl`

Summary

Step	Who Does It
Process payment	Ozura (automatic)
Mark session complete	Ozura (automatic)
Redirect to successUrl	Ozura (automatic)
Show confirmation	You (your business logic)
Verify session status	You (recommended for security)
Fulfill order	You (your business logic: emails, database, shipping, etc.)

Next Steps

Want popup or iframe instead of redirect? → Integration Modes
Having issues? → Troubleshooting
Need all the details? → API Reference

Getting Started

Vault

Payments

Handle the Payment Result

What Ozura Does Automatically

URL Overview

Possible Outcomes

Success URL

Success URL Parameters

Reading the Data

Cancel URL

Error URL

Error Codes

Always Verify Before Fulfilling Orders

Session Statuses

Summary

Next Steps

​What Ozura Does Automatically

​URL Overview

​Possible Outcomes

​Success URL

​Success URL Parameters

​Reading the Data

​Cancel URL

​Error URL

​Error Codes

​Always Verify Before Fulfilling Orders

​Session Statuses

​Summary

​Next Steps

What Ozura Does Automatically

URL Overview

Possible Outcomes

Success URL

Success URL Parameters

Reading the Data

Cancel URL

Error URL

Error Codes

Always Verify Before Fulfilling Orders

Session Statuses

Summary

Next Steps