Claim Mini App - User Guide

The Claim Mini App lets members upload receipts and receive rewards. Operators review submissions and configure rules in the Claim Ops Portal.

Note: The mini app runs inside the VIO Member App. Members must be signed in. Operators access the Ops Portal from the Admin Portal and need the VIO External API Key configured for their tenant (see Registration Reward - VIO External API Key).

---

Table of Contents

1. How to Access
2. Member App Screen Overview
3. Member Experience - Upload Receipts
4. Member Experience - Confirm, Summary & Result
5. Member Experience - Claim History
6. Ops Portal - Submissions
7. Ops Portal - Users
8. Ops Portal - Rules Configuration
9. Operational Workflows
10. Troubleshooting
11. Business Rules & Notes

---

1. How to Access

Members — Sign in to the VIO Member App, open Mini programme -> See all, and tap the Claim tile. The mini app loads inside the Member App shell and lands on Upload Receipts.

Operators — Sign in to the Admin Portal and open Claim from the Mini Apps section. The Ops Portal opens with top tabs Submissions / Users and an Edit Rules Configuration button.

Tip: If the page bounces to login or shows Authentication Required, reopen Claim from Mini programme — the Member App passes the VIO session via a refresh token in the URL.

---

2. Member App Screen Overview

The Member App shell wraps every Claim page with Back (←), the page Title, and a Refresh button (top right, circular-arrows icon). Refresh reloads the mini app and re-sends the latest session tokens.

On Upload Receipts you will also see:

• claim history link (top right) — opens Claim History at /history.
• Take a photo — opens the camera. Accepts JPG, PNG, HEIC (HEIC is auto-converted).
• Upload images — opens the file picker. Same formats; up to the campaign's Max N receipts per submission limit.
• Submission Criteria card — auto-generated from the active rules (per-category receipt cap, minimum spend, overall cap).

Tip: Refresh keeps the local draft but re-fetches campaign rules. Back leaves Claim entirely.

---

3. Member Experience - Upload Receipts

3.1 Page states

State	When it appears	Upload buttons
Campaign Not Active	Ops rules are incomplete or saved checks failed (banner lists the missing items).	Disabled
Campaign is not currently active	Outside the campaign period and outside any Receipt Date Buffer.	Disabled
Ready to upload	Inside the campaign period.	Active
Within Receipt Date Buffer	Outside the official period but inside the configured buffer window. Shows a banner like Campaign starts on {date}. You can submit receipts now. or Campaign has ended. Submit receipts by {endWithBuffer date}.	Active

3.2 How to upload

How to use:

1. Tap Take a photo or Upload images on Upload Receipts.
2. Wait for the processing overlay (Uploading..., Converting HEIC image..., or Compressing image...).
3. Each receipt is OCR-scanned in the background. When the in-progress list shows completed, the Submission Criteria card refreshes so you can check category, count, and total.
4. Tap a thumbnail to review or remove a receipt. Repeat step 1 to add more, up to the Max N receipts per submission limit.
5. When all receipts are ready, the page advances to Confirm receipt.

Warning: All receipts in one submission must be from the same merchant category. Mixed categories trigger This receipt is from a {category} store. You can only add receipts from {locked} stores in this submission.

Note: Exceeding a per-category or overall limit opens an Upload Error modal (You can only upload up to N… or Only N more receipt(s) can be added.).

3.3 Submission Criteria

The card lists the active rules: per-category receipt cap, minimum spend (in RM), and the overall Max N receipts per submission (default 3). Category names, caps, and minimums vary by tenant — always use the card on the page as the source of truth.

Tip: All receipts in one submission must belong to the same category, even if multiple categories appear in the card.

---

4. Member Experience - Confirm, Summary & Result

4.1 Confirm receipt (/confirm)

Each receipt is shown as Receipt N of M with the parsed merchant, category, and amount.

• Tap the thumbnail to open the Receipt N zoom dialog (− / + / Close).
• Use Add another receipt (N receipt(s) left) to add more; it reads No receipts left to add at the cap.
• Use the row delete icon to open Delete Receipt (Cancel / Delete).
• Tap Continue to proceed.

Note: If the per-category total is below the minimum, the page shows Your total amount does not meet the minimum requirement of RM … for {category} stores. together with You can add up to … more receipt(s).

4.2 Summary (/summary)

The final step before submission. For each receipt, fill in:

• Merchant (opens a Merchant drawer with Search brand)
• Receipt date
• Receipt amount (prefixed RM)

Submit is enabled only when every receipt has an eligible Merchant, a Receipt date, and an Amount > 0. It shows Submitting... while processing. A session timeout shows User not authenticated. Please log in again.

4.3 Submission Result (/result)

On success the page shows You have submitted the claim request. The approval takes within 3 days., a Receipt summary card, and a Done button that returns to Upload Receipts (the local draft is cleared).

---

5. Member Experience - Claim History

Tap claim history on Upload Receipts to open /history. Submissions are listed most recent first with date, Merchant, Amount, Reward (when issued), and a status badge.

Status badges (member view)

Badge	Meaning
Pending	Awaiting review.
Processing	Backend or reward delivery in progress.
Approved	Approved (covers backend approved and processed).
Rejected	Operator rejected the submission.
Failed	Submission could not be processed.
Reward Failed	Approved but reward delivery failed.
Partial	Some rewards sent, others failed (partial_failed).

Empty state shows No submissions yet with a Submit a Receipt button.

---

6. Ops Portal - Submissions

6.1 Page layout

The Ops Portal lands on Submissions (/submissions). The page provides a Status filter dropdown (All Status, Pending, Processing, Processed, Approved, Rejected, Failed, Partial Failed, Reward Failed), a Search input (placeholder Search by user ID or username), and a paginated table.

Submissions table columns: Date & Time, Username, User ID, Receipts (N receipt(s)), Status, Total Amount (RM), Reward Obtained, Actions (Verify claim for manual queue items, View details otherwise).

Empty state: No Submissions Found / Try adjusting your filters or search criteria.

6.2 Submission detail drawer

Click View details or Verify claim to open Submission Details. The drawer contains:

• Submission Info — SUBMISSION ID, USER ID, USERNAME, DATE, STATUS, TOTAL AMOUNT, plus AMOUNT EDITED BY/AT, REVIEWED BY, REVIEWED AT, REJECT REASON when present.
• Receipts (N) — each card shows the editable Receipt amount, Receipt Date:, Store:, Store Name:, and an expandable OCR Text section. Use Save Amounts before approving. Clicking a thumbnail opens a lightbox with zoom + / −, Reset, Escape.
• Rewards — status pill (Success, Partial, Failed, Pending approval) and a per-reward table (Reward type, Voucher name, NFT ID, Status, Error reason, Sent at).
• System Error — raw error text when the backend reports an error.
• Footer actions — Approve & send rewards, Reject, and Resend failed rewards (only when some rewards failed).

Each action opens a confirmation modal (Approve Submission, Reject Submission with a required reason, Resend Rewards).

Warning: The Ops front end has no bulk Export / CSV action — exports must be pulled from the API or database.

6.3 How to use

How to use:

1. Open Submissions and filter by Pending for the manual queue.
2. Click Verify claim (or View details) to open the drawer.
3. Verify each receipt's Store, Receipt Date, and Receipt amount; expand OCR Text if needed.
4. Adjust amounts where necessary and Save Amounts.
5. Approve & send rewards or Reject with a written reason.
6. If Rewards shows Failed / Partial, fix the underlying cause (token balance, voucher availability, External API key), then Resend failed rewards.

---

7. Ops Portal - Users

The Users tab shows member-level activity:

• Users Overview counters: Total Users:, Total Submissions:, Total Rewards Sent:.
• Search input with placeholder Search by user ID, username or email.
• Users table columns: Username, User ID, Email, Submissions, Rewards, Last Active, Actions (View details).
• User ID is shown as a 5-character preview (e.g. abcde…). Click the copy icon next to it (tooltip Copy full user ID) to copy the complete ID — a toast shows User ID copied to clipboard and the icon turns into a ✓. If your browser blocks clipboard access, a Copy failed modal appears with the message Could not copy to the clipboard. Your browser may block copying on this URL; try HTTPS or copy the ID manually from the network tab or logs.

View details opens a User Details drawer with a User Info card and a Submission History (...) table (Date, Amount, Reward type, Voucher name, Tokens, Status).

Empty states: No Users Yet (system not yet synced) or No Users Found (no search match).

---

8. Ops Portal - Rules Configuration

Edit Rules Configuration opens the rules wizard at /rules (breadcrumb Receipt Ops > Rules Configuration). Each step has its own Save Changes with toasts such as Receipt quantity rules saved successfully!. A Configuration completeness {pct}% indicator tracks progress and lists any missing steps.

Wizard steps:

1. Receipt Scope — define Eligible Merchants and group them under Merchant Categories (e.g. NSK, OTHER). Receipts whose detected store is not eligible are rejected with Store "{storeName}" is not in the eligible tenants list.
2. Quantity — set Overall Limit (Maximum Total Receipts per Claim, default 3, shown to members as Max N receipts per submission) and Category Limits (one {Category} Max Receipts field per category, each must be ≤ the overall limit). Inline note: ⚠️ Note: Users can only submit receipts from ONE category per claim. Each category limit must be ≤ overall limit.
3. Thresholds — per-category Minimum spend required in RM.
4. Review Mode — Automatic auto-approves; Manual routes submissions into the Verify claim queue (Section 6).
5. Rewards — choose Vouchers (linked to a VIO Voucher Pool, search Select voucher from VIO...) or Tokens (the system divides the receipt total by the configured spend amount, rounds down, and grants that many times the configured earn amount). Requires the VIO External API Key to be configured for the tenant; the Ops Portal opens a VIO External API Key gate (placeholder Paste your vio_live_… key, button Confirm) when one is missing.
6. User Limits — Maximum Claims per User. Validation: Maximum claims per user must be at least 1. At the cap, members see You have reached the maximum number of submissions allowed for this campaign.
7. Time Rules — Campaign Period (Start Date / End Date) and Receipt Date Buffer (days before/after the window in which receipts remain valid). A Receipt Date Range preview shows the resulting accepted dates.

Bottom navigation: Cancel on Step 1, Back on later steps, Next between steps, Done at the end.

Warning: Changing Time Rules mid-campaign immediately affects which receipts members can submit. Communicate the change before saving.

---

9. Operational Workflows

9.1 Launch a new claim campaign

1. Configure the VIO External API Key for the tenant.
2. Run the Rules Configuration wizard in order (Receipt Scope -> Quantity -> Thresholds -> Review Mode -> Rewards -> User Limits -> Time Rules), saving each step.
3. Confirm Configuration completeness reaches 100%.
4. With a test account, walk through Upload Receipts -> Confirm receipt -> Summary -> Submission Result in the Member App.
5. Verify the submission appears under Submissions with the expected Status.

9.2 Daily manual review (Manual mode)

1. Filter Submissions by Pending and click Verify claim.
2. Inspect images, OCR text, and parsed Receipt amount; adjust and Save Amounts if needed.
3. Approve & send rewards or Reject with a written reason.
4. Confirm Rewards reports Success; otherwise use Resend failed rewards after checking the cause.

9.3 Handle reward delivery failures

1. Filter Submissions by Reward Failed or Partial Failed.
2. Review the Rewards table and System Error field to identify the cause (token balance, voucher availability, External API key, network).
3. After resolving the cause, click Resend failed rewards.
4. Confirm the row moves to Approved with all rewards reporting Sent.

9.4 End-of-campaign housekeeping

When the campaign window passes, members start seeing Campaign is not currently active. Clear any Pending / Processing rows, capture the final metrics from Submissions and Users, and decide whether to keep the VIO External API Key and rules for the next campaign.

---

10. Troubleshooting

For members

Symptom	What to check
Page blank / spinner	Tap Refresh; if still blank, check the network and reopen Claim from Mini programme.
Authentication Required modal	Reopen Claim from the Member App — do not paste the URL into a browser.
Campaign Not Active banner	Ops rules are incomplete — contact the operator.
Campaign is not currently active banner	Outside the campaign and any Receipt Date Buffer window.
Upload Error modal	Reduce the number of files or change the category to the locked one.
Total below minimum on Confirm receipt / Summary	Add another receipt from the same category.
Reward not visible	Open Claim History first. Tokens show in Home -> Balance and Transaction History; vouchers in Vouchers.

For operators

Symptom	What to check
Submissions stuck on Loading...	Confirm the VIO External API Key is configured (gate modal VIO External API Key).
Verify claim action missing	Review Mode is Automatic — switch to Manual if you need manual review.
Save Amounts fails	Each edited amount must be > 0.
Approved row turns into Reward Failed	Open the row and read the per-line Error reason; use Resend failed rewards after the fix.
New submissions not visible	Check Time Rules — dates outside Campaign Period + Receipt Date Buffer are rejected.
Rules step refuses to save	Follow the inline messages (e.g. Maximum claims per user must be at least 1.) and the Configuration completeness banner.

---

11. Business Rules & Notes

• Session — Members must open Claim from the Member App so the refresh token is in the URL. Direct browser access shows Authentication Required.
• Single category per submission — Receipts in one submission must be from the same category; mixed categories are rejected.
• Overall receipt cap — Maximum Total Receipts per Claim (default 3), surfaced to members as Max N receipts per submission.
• Currency — Amounts are displayed in RM. Multi-currency tenants need an additional integration layer (out of scope).
• OCR & compression — PNG/JPEG over 1 MB are compressed client-side; HEIC is converted before upload.
• Approval text — Submission Result hard-codes The approval takes within 3 days. Align internal SLA messaging.
• Status alignment — Member-facing Approved covers backend approved and processed. Ops Submissions distinguishes them in the filter.
• Reward delivery — Rewards are issued via the VIO External API. Failed lines remain visible in Rewards and can be retried with Resend failed rewards.
• Compliance — Surface the active rules clearly via the Submission Criteria card; avoid changing Time Rules, Quantity, or Thresholds mid-campaign.

---

See also Mini Apps overview, Lucky Draw Mini App, Marketing Mini App, Registration Reward Mini App, and Member App - Home.