Integration Guide
This guide explains how to connect your existing systems (POS, e-commerce, or mobile app) to the Otonum loyalty platform. It covers the full checkout cycle, from member identification to reward confirmation.
For the exact request and response format of each operation, see the API Reference.
Architecture Overview
Your system calls the Otonum API on behalf of your members. Otonum handles all reward logic server-side. Your system provides member identity and transaction data, then Otonum determines and applies rewards.
Step-by-Step Flow
Step 1: Identify the Member
At checkout, collect the member personal code (loyalty card, app scan, or manual entry). If you only have the member email, you can look up the personal code through the dedicated route.
Once you have the code, fetch the member balance and show available rewards early. This usually increases redemption rates and gives a better experience than showing options after checkout.
Step 2: Redemption (Optional)
If the member wants to redeem rewards, the flow is the same for points and cashback:
- Create a voucher from the member balance by specifying program type (
PointsorCashback) and redemption amount. - Validate the voucher at checkout to confirm it is still active and get the final cash discount value (
cashValue) to apply.
Validation is important because the voucher may have been created on another channel. Always validate before applying the discount.
Store the voucher reference. You need it when submitting the purchase to mark the voucher as consumed.
Step 3: Apply the Discount in Your System
Otonum tells you how much to reduce. Your system applies the discount. Otonum never changes your prices and does not interact with your payment processor.
Calculate the two amounts you submit:
| Field | Formula |
|---|---|
amount | Net transaction value — original price minus any redemption discount |
redemptionAmount | Voucher cashValue |
amount is the value used for reward calculation.
Step 4: Submit Activity
After transaction completion in your system, submit it to Otonum. Two fields are critical:
reference: Use your internal order ID. It is the Otonum deduplication key. The same reference is never processed twice. This protects members from double rewards during network retries.redemptionCode: Include the voucher reference when redemption happened. This marks the voucher as consumed.
The activity endpoint returns a taskId immediately. Reward processing runs in the background.
Step 5: Reward Processing
After receiving your submission, Otonum:
- Evaluates the activity against all active campaigns
- Calculates earned points or cashback according to campaign rules
- Marks the redeemed voucher as consumed (when applicable)
- Updates member balance
- Notifies the member (email or push, depending on your settings)
This is asynchronous. Your checkout returns before processing is complete. See Task Status when your UX needs completion tracking.
To avoid drift with effective routes, this page does not duplicate API URLs. Use the API Reference for current endpoints, parameters, and payload examples.
Integration Patterns
POS (In-Store)
- Add a loyalty step before payment: collect personal code, show balance, offer redemption
- After payment, submit purchase to Otonum asynchronously. Do not block POS on API completion.
- Surface personal code as QR/barcode in your loyalty app for fast scanning
E-commerce
- Add a loyalty code field at checkout (next to promo codes)
- When code is entered, fetch balance and show available rewards in real time
- After order confirmation, trigger Otonum purchase submission from your order webhook or post-payment event
Mobile App
- Display personal code as QR/barcode on home screen for in-store scanning
- Show balance preview and recent reward history on profile screen
- Always submit purchases from your backend server, never directly from mobile app (API key must stay server-side)
Key Integration Decisions
| Decision | Recommendation |
|---|---|
| When to show balance | Before checkout, not after. This improves redemption adoption. |
| When to poll task status | Only if your interface must show earned rewards immediately |
| Voucher cancellation | Cancel if member changes their mind before purchase submission |
| Duplicate prevention | Always use order ID as reference |
| Notification ownership | Otonum sends notifications by default. Decide whether your system also sends them, and disable one channel to avoid duplicates. |
Idempotency
To prevent duplicate reward processing during network retries, always provide a unique reference per activity.
Webhooks (Coming Soon)
Otonum plans webhooks for real-time notifications to your systems (reward earned, voucher issued, status changes). In the meantime, monitor the Changelog for availability updates.