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. Payment is processed
↓
3. Ozura marks the session as "completed" ← Automatic!
↓
4. 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.
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 |
Handling Success
When payment succeeds, the customer is redirected to your successUrl with payment details in the URL:
https://yoursite.com/success?success=true&sessionId=session_xxx&transactionId=txn_abc123&amount=25.00¤cy=USD&cardLastFour=4242&cardBrand=visa&firstName=John&lastName=Doe&email=john@example.com
Success URL Parameters
Transaction Info:
| Parameter | What It Is | Example |
|---|
sessionId | Your session ID (for verification) | session_xxxxxx |
transactionId | Unique payment ID | txn_abc123 |
amount | Amount charged | 25.00 |
currency | Currency code | USD |
Card Info:
| Parameter | What It Is | Example |
|---|
cardLastFour | Last 4 digits of card | 4242 |
cardBrand | Card network | visa |
Customer Billing Info:
| Parameter | What It Is | Example |
|---|
firstName | Customer first name | John |
lastName | Customer last name | Doe |
email | Customer email | john@example.com |
Example: Success Page (JavaScript)
// Parse URL parameters
const params = new URLSearchParams(window.location.search);
const sessionId = params.get('sessionId');
const transactionId = params.get('transactionId');
const amount = params.get('amount');
// Parse metadata (JSON-encoded)
let metadata = {};
try {
metadata = JSON.parse(params.get('metadata') || '{}');
} catch (e) {}
console.log('Order ID:', metadata.orderId);
Handling Errors
Fixable Errors (Stay on Checkout)
Card declined, wrong CVV, invalid card number – the customer stays on the checkout page and sees an inline error. They can correct their info and try again.
Unrecoverable Errors (Redirect to errorUrl)
System errors, connectivity issues – the customer is redirected to your errorUrl with error details:
https://yoursite.com/error?success=false&errorCode=SYSTEM_ERROR&error=Payment+service+unavailable&cancelUrl=https://yoursite.com/cart
| Parameter | Description | Example |
|---|
errorCode | Error type code | SYSTEM_ERROR, AUTH_ERROR |
error | Human-readable message | Payment service unavailable |
cancelUrl | Return URL (your cancelUrl) | https://yoursite.com/cart |
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.io/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