> ## 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.
# Handle the Payment Result
> Process successful payments, cancellations, and errors after checkout
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¤cy=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](/guides/payments/checkout/payment-links#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
```javascript title="JavaScript (any framework)" theme={null}
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
```
```python title="Python (Flask/Django)" theme={null}
transaction_id = request.args.get('transactionId')
amount = request.args.get('amount')
checkout_mode = request.args.get('checkoutMode')
```
```php title="PHP" theme={null}
$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:
```json theme={null}
{
"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:
```javascript theme={null}
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](/guides/payments/checkout/integration-modes)
* Having issues? → [Troubleshooting](/guides/payments/checkout/troubleshooting)
* Need all the details? → [API Reference](/guides/payments/checkout/api-reference)