Stamp Mini App - User Guide
The Stamp Mini App is a "collect stamps, win a prize" loyalty program. Members collect stamps by visiting merchant stores and making purchases. When all 5 stamps are collected, the member taps Redeem to win a random prize (a token or a voucher) based on the probability configured by operators.
Note: This Mini App has three audiences and three separate entry points:
- Members open the Stamp Collect tile in the VIO Member App.
- Merchant staff scan the member's QR code on a separate device; this opens the Merchant page where they enter the operator PIN and confirm the receipt.
- Operators / brand admins open the Stamp Ops Portal from the Admin Portal to manage prizes, view records, and edit the on-screen instructions.
Table of Contents
- How to Access
- Member Experience - Stamp Collect
- Merchant Experience - Issuing Stamps
- Ops Portal - Collect Stamp Page
- Ops Portal - Prize Information
- Business Rules & Notes
1. How to Access
For Members (PWA)
- Open the VIO Member App and sign in.
- From Home, tap the Stamp Collect tile in the Mini Apps section. The app reuses your VIO session — no separate login is needed.
- The header shows a back arrow (<) on the left and the title Stamp Collect.
Note: If no VIO session is available, the page cannot render the member's QR code and the Collect flow will not start. Sign in to the Member App and reopen the tile.
For Merchant Staff (Merchant Page)
Merchant staff do not log in to a separate account. They work on a dedicated merchant device that:
- Opens the URL embedded in the member's QR code (
/#merchant/pin). The header reads Enter PIN. - Enters the Operator PIN (6 characters, first 2 letters, last 4 digits, format like
AB-1234). - After a valid PIN is entered, the device moves to the Action Center page, where the staff inputs the receipt amount and store location, then confirms.
For Administrators (Ops Portal)
- Open the Admin Portal and sign in with a tenant account.
- From Dashboard or Mini Apps, open the Stamp entry. The Stamp Ops Portal loads inside the Admin Portal frame.
- The default landing page is Collect Stamp, with the title Collect Stamp, an Edit PWA Configuration button on the right, a Program Summary card, and two tabs (Stamp Collections / Reward Records).
Note: Operator access requires Admin Portal permissions assigned by your tenant administrator.
2. Member Experience - Stamp Collect
The member side is a single page with five stamp slots, a Redeem button, and a "How to Collect Stamps?" link.
2.1 Page Layout
| Element | Purpose |
|---|---|
| < (back arrow) | Top-left back button. Returns to the page the Mini App was launched from (the redirect URL passed in). |
| Stamp Collect (title) | Page title in the header. |
| Visit Merchants to Claim Free Vouchers or Tokens! | Hero heading just below the header. |
| Turn your visits into rewards by collecting stamps! | Sub-line under the hero. |
| Stamp grid | Five circular slots laid out as 2 - 1 - 2 (stamps 1 & 2 on row 1, stamps 4 & 3 on row 2, stamp 5 in the middle of row 3). The 5th stamp is the Reward stamp and looks different from the four Store stamps. |
| Redeem (button) | Disabled until all 5 stamps are collected. |
| You've collected N/5 stamps. | Live counter below the Redeem button. |
| How to collect stamps? | Link at the bottom. Opens the instructions modal (operators edit this content from the Ops Portal — see §4.1). |
2.2 Collecting a Stamp
Stamps are not collected by tapping alone — a merchant has to scan and confirm the receipt. The member's role is to show their QR code.
How to use:
Step 1: Tap the next stamp slot
- The first uncollected slot is tappable; collected and not-yet-reachable slots are inactive.
- Tapping a tappable slot opens the Membership QR Code modal. The modal shows a QR code and the member's username underneath. If the QR code is still being generated, a Generating QR Code... placeholder appears in the same area.
Step 2: Show the QR code to staff
- Merchant staff use their own device to scan the QR code, which carries the member's user ID, username, and wallet address.
- Once the merchant confirms the receipt on their side, the page updates in real time:
- The matching stamp slot plays a "filled" animation.
- A Stamp Collected! modal appears with the message You have successfully collected a stamp! You can collect only one stamp per store per day. Visit other stores to collect more stamps. and a Done button.
- The grid line / curve connecting that stamp to the next is filled in.
Step 3: Repeat for stamps 1 through 4
- Each stamp must come from a different store on the same day — the system blocks a second stamp from the same store within the same day. When that happens, a Stamp Collected Here modal appears with You've already collected a stamp today. Come back tomorrow for your next stamp!
Step 4: Collect the Reward stamp (slot 5)
- The 5th slot has a different look ("Reward stamp"). Tap it and follow the same scan-and-confirm flow.
- On success, the Stamp Collected! modal carries a stronger message: You have successfully collected all stamps! Redeem your reward now! and a Done button.
Tip: The grid does not show a per-store name. The "one stamp per store per day" rule is enforced behind the scenes by the merchant device — there is nothing the member needs to track themselves.
2.3 Redeeming a Prize
When all five stamps are filled, the Redeem button becomes active.
How to use:
Step 1: Tap Redeem
- The app picks a prize automatically. The selection is random, weighted by the Winning Probability (%) each prize was given in the Ops Portal (see §5.1).
Step 2: See the result
- A celebration modal opens with the heading Congratulations! and a Hooray! You get {prize name}! sub-line.
- The visual differs by prize type:
- Voucher — a card showing the voucher image, name, and validity period.
- Token — two circular token icons with a +{amount} badge underneath.
- A Done button closes the modal.
Step 3: After closing
- All five stamps are wiped and the page reloads.
- The page now shows 0 / 5 stamps, ready for another cycle. Already-issued rewards stay in the member's wallet.
Note: The page only ever shows one prize at a time. If you redeem before the operator has configured any prizes, an error toast appears: No rewards available at this moment. Your stamps are not consumed in that case — you can try again later.
2.4 How to Collect Stamps? Modal
Tap How to collect stamps? at the bottom of the landing page to open an instructions modal.
| Section | Content |
|---|---|
| Header | How to Collect Stamps? — fixed title. |
| Body | The numbered steps shown to members. Set by operators in the Ops Portal under Collect Stamp > Edit PWA Configuration (see §4.1). The default copy is 1) Visit a nearby merchant. 2) Make any purchase at the store. 3) Click on the stamp icon. 4) Show the QR code to the staff to collect your stamp. 5) When all stamps are collected, click on 'Redeem' to claim a reward! |
| Terms | Two fixed bullets — By participating the draw you are agreeing to these draw terms and conditions. and We reserve the right to amend these terms and conditions at any time without prior notice. Not editable from the Ops Portal. |
| Close button | X in the top-right corner. |
3. Merchant Experience - Issuing Stamps
The merchant side runs on a separate device. It is launched the moment merchant staff scans the member's QR code.
3.1 Enter PIN Page
The first page after scanning is Enter PIN.
| Element | Purpose |
|---|---|
| Header title | Enter PIN (gradient purple background). |
| Sub-heading | Enter Operator PIN with helper text Enter your PIN to proceed with Stamp Distribution. |
| PIN input | Six boxes in the format AA - 1234: positions 1–2 accept letters only; positions 3–6 accept digits only. A - separator sits between the 2nd and 3rd box. |
| Status line | While the device fetches a session token, a small spinner appears with the text Initializing session... |
| Error line | If a PIN box gets an invalid character (e.g. a digit in a letter box), a red message appears below — First two characters must be letters or Last four characters must be numbers. Invalid PINs return Invalid operator PIN. |
How to use:
Step 1: Confirm the QR was scanned
- The page only loads after a successful QR scan, so the member's user ID, username, and wallet address are already attached internally. If they are missing, the page shows Invalid QR code. Missing user information. — ask the member to reopen the QR modal and re-scan.
Step 2: Type the PIN
- Type the 6-character PIN exactly as issued to the staff. Letters auto-uppercase; the cursor moves to the next box automatically.
- Backspace clears the current box, or moves back one box and clears that one if the current box is already empty.
Step 3: Wait for verification
- The PIN is verified as soon as the 6th character is entered. Initializing session... may appear briefly.
- On success, the device navigates to the Action Center.
- On failure, the original boxes stay editable and a red error line appears.
Note: The PIN is per merchant store/operator and is rotated by the brand admin. Treat it like a password — do not share it outside the operator group.
3.2 Action Center
After the PIN is accepted, the device shows the Action Center.
| Field | What it shows / does |
|---|---|
| Recipient | The member's avatar (👤), username, and wallet address — pulled from the QR code so staff can confirm they have the right customer. |
| Operation Type | Fixed text Stamp Collect. This screen only issues stamps; it cannot issue any other operation. |
| Receipt amount | Pill-shaped input. The left side is a currency selector (defaults to HKD$, tapping it opens a currency picker). The right side is a numeric input (digits + max one decimal, max 2 decimal places). Helper text below: Please input receipt amount. Validation errors appear in red. |
| Store Location | Pill-shaped selector. Tapping it opens the store location picker, scoped to the operator's company. Required. |
| Confirm (button) | Disabled until both fields are valid. Reads Processing... while the request is in flight. |
How to use:
Step 1: Cross-check the recipient
- Verify the username matches the customer in front of you. The wallet address is shown for cases where the same username is shared across tenants.
Step 2: Enter the receipt amount and pick the store
- Tap HKD$ to switch currency if needed.
- Type the receipt amount. If you type a non-number, the helper text turns red with Please enter numbers only.
- Tap Select store location and pick the right store.
Step 3: Confirm
- Tap Confirm. The button reads Processing... while saving.
- Three outcomes are possible:
- Stamp Collection Approved — the receipt was accepted; the customer's stamp count goes up by 1. The device navigates to the Stamp Collection Approved confirmation screen (see §3.3). The customer's PWA updates in real time too.
- Already collected today — the customer already collected a stamp at this store today. The device shows the Stamp Collection Rejected state (see §3.4). The customer's PWA shows a Stamp Collected Here modal.
- Error — for anything else (expired session, invalid PIN, missing fields, etc.), the device navigates to the Unexpected Error page (see §3.5). Common causes appear with a friendlier message — e.g. Session expired. Please scan QR code again. or Stamp collection is already complete. You have collected all 5 stamps!
Note: A new session needs a fresh QR scan. If a staff member sees Session expired, ask the customer to reopen the QR code on their device, then start again from §3.1.
3.3 Stamp Collection Approved
When the receipt is accepted, the device shows a confirmation screen with the customer's stamp number, time, and receipt details.
| Element | What it shows |
|---|---|
| Heading | Stamp Collection Approved (or Congratulations! Prize Won! if the 5th stamp also triggered a prize). |
| Sub-line | User has successfully collected stamp #N. (or the prize-won variant). |
| Collection Date and Time | The merchant device's current date and time, e.g. dd/mm/yyyy HH:MM:SS. |
| Stamp Number | #1 through #5. |
| Receipt Amount | Currency + amount typed on the previous screen. |
| Store Location | The store you selected. |
| Recipient | Username and wallet address. |
| Prize Won / Redemption Code (5th stamp only) | If the customer happened to win a prize on this stamp, the prize name and a monospaced redemption code appear. |
There is no button on this screen — close the page or return to the start to issue another stamp.
3.4 Stamp Collection Rejected (Already Collected)
If the customer already collected a stamp from the same store today, the Action Center routes here instead of the approval screen.
| Element | What it shows |
|---|---|
| Header | Action Center (purple). |
| Alert banner | Purple banner with a ! icon and the text This user has already collected a stamp here today. Users only can collect one stamp per day from the same store. |
| Last collected on | A line in the format Last collected on dd Mon yyyy, hh:mm AM/PM, when the previous collection time is known. |
| Recipient | The same Recipient block (avatar, username, wallet address). |
Tip: The merchant device does not retry automatically. Ask the customer to come back tomorrow or visit another store in the same brand.
3.5 Unexpected Error
Any other failure (network problem, missing info, invalid session, validation error) lands on the Unexpected Error page.
| Element | What it shows |
|---|---|
| Heading | Unexpected Error |
| Body | The actual error message, e.g. Session expired. Please scan QR code again. If the raw error is empty, the page falls back to There was an unexpected error. Try again after a few seconds. |
The error page does not have a "Retry" button — close the page and re-scan the customer's QR code to start again.
4. Ops Portal - Collect Stamp Page
The Collect Stamp page is the Ops Portal's default landing view. It has three areas:
- Page header — title + Edit PWA Configuration button.
- Program Summary — three at-a-glance counters and a link into Prize Information.
- Tabbed records area — Stamp Collections tab and Reward Records tab, each with filters, a search box, and a paginated table.
4.1 Page Header
| Element | Purpose |
|---|---|
| Collect Stamp (title) | Page title. |
| Edit PWA Configuration | Opens the PWA Configuration modal, where you edit the How to Collect Stamps? instructions shown in the member-app modal (see §2.4). |
PWA Configuration modal
| Element | Purpose |
|---|---|
| Heading | PWA Configuration. |
| How to Collect Stamp (User Instructions) | Rich-text editor (basic formatting: bold, italics, lists, links). Pre-filled with the current saved content, falling back to the 5 default steps if none is saved. |
| Character count | Counter below the editor; the editor enforces a maximum of 2000 characters. |
| Confirm | Saves the new HTML as the user instructions. Disabled when the editor is empty. The modal shows a success toast PWA configuration has been updated. on save, then closes. |
| X (top-right) | Closes the modal without saving. Unsaved changes are discarded; reopening fetches the last saved content. |
Note: The fixed terms-and-conditions bullets at the bottom of the member modal are not edited from here — only the numbered instructions on top.
4.2 Program Summary
A card just below the header with three at-a-glance counters and a link into Prize Information.
| Element | Purpose |
|---|---|
| Program Summary | Section heading. |
| View Prize Information | Underlined link on the right that navigates to the Prize Information page (see §5). |
| Total Participants | Count of unique users who have ever collected at least one stamp for this tenant. The ! tooltip reads Total number of users who have participated in the stamp collection program. |
| Total Stamps Collected | Total number of stamps issued across all participants. |
| No. of Redemptions | Total number of rewards redeemed (a prize was actually delivered to a member's wallet). |
Each stat shows ... while it loads.
4.3 Stamp Collections Tab
The default tab. One row per stamp issued.
| Element | Purpose |
|---|---|
| Stamp Collections (tab) | Active tab. The number reflects all stamps issued for this tenant. |
| Search input (placeholder Search by Username) | Filters the table by member username. |
| Store Location (filter) | Multi-select checkbox filter populated from the stores that have actually issued a stamp. Empty filter = no filtering. |
Table columns
| Column | What it shows |
|---|---|
| Collection Date Time | When the stamp was issued. |
| Username | Member's username. |
| Spending Amount | Receipt amount that the merchant typed at the Action Center, with currency. |
| Store Location | Store the stamp came from. |
If there are no rows, the empty-state image and the standard "no records" message appear. Pagination shows 6 rows per page.
4.4 Reward Records Tab
One row per prize delivery attempt.
| Element | Purpose |
|---|---|
| Reward Records (tab) | Active tab. |
| Search input (placeholder Search by Username/ Prize Name) | Free-text search across username and prize name. |
| Prize Type (filter) | Checkbox filter with Voucher and Token. |
| Distribution Status (filter) | Checkbox filter with Success and Fail. |
Table columns
| Column | What it shows |
|---|---|
| Redemption Date Time | When the redemption happened. |
| Username | Member who tapped Redeem. |
| Prize Name | Name of the prize at the time of redemption (e.g. 5 PTS Token, Free Coffee Voucher). |
| Prize Type | Badge: Voucher or Token. |
| Distribution Status | Success (green) or Fail (red). Failed rows mean the prize was selected but the platform could not deliver it — please open the row to see the failure message in the row component, then take corrective action. |
Pagination: 6 rows per page.
Note: Failed deliveries do not consume the member's stamps — the stamps stay full so the member can tap Redeem again once you have fixed the cause (e.g. add stock, fix the token balance).
5. Ops Portal - Prize Information
The Prize Information page sits at /prize-information and is reached from the View Prize Information link in the Program Summary, or from the breadcrumbs (Collect Stamp > Prize Information).
It has two tabs:
- Prize Configuration — manage the list of prizes that can be won.
- Prize Claim Statistic — see how many of each prize have actually been claimed.
5.1 Prize Configuration Tab
This tab is the active prize pool. The member-side roulette only picks from prizes saved here.
| Element | Purpose |
|---|---|
| Orange info banner | Please set the winning probability for each prize. The total must be 100% or less. |
| Add Prize (button) | Opens the Add New Prize modal (see below). |
| Search input (placeholder Search in Prize Configuration...) | Filters the table by prize name or prize type. |
Table columns
| Column | What it shows |
|---|---|
| Prize Name | Display name pulled from the selected token or voucher. |
| Prize Type | Badge: Voucher or Token. |
| Quantity | Remaining quantity. For tokens, an extra line Per user: N shows the per-redemption amount. |
| Winning Probability (%) | Editable numeric input, 0–100. The page enforces that the sum of all probabilities is ≤ 100. If your edit makes the sum exceed 100, a validation toast appears and the row shows an inline error. |
| Actions | Per-row Edit and Delete controls. |
Save Configuration
Changes (add / edit / delete / probability) are kept locally until you click Save Configuration at the bottom-right.
- A small orange banner You have unsaved changes appears next to the button when there are pending edits.
- The Save Configuration button is disabled when there are no unsaved changes.
- While saving, the button reads Saving….
- On success, a green toast Prize configuration has been successfully saved to the database. appears and the table reloads.
- On failure, a red toast Failed to save configuration. Please try again. appears and the local edits stay so you can retry.
Add New Prize modal
Open this modal from the Add Prize button at the top-right of the Prize Configuration tab. The first field, Prize Type, controls which inputs are shown.
| Field | What it does |
|---|---|
| Prize Type | Required. Choose Voucher or Token. The fields below change based on this choice. |
| Voucher (Voucher only) | Shown when Prize Type = Voucher. Click Select to open the Select Voucher picker — filter the VIO catalogue by Brand, Category, Voucher Type, Country, or type into the Search by voucher name box, then pick a row and click Confirm. Vouchers already used by another prize in this configuration are greyed out. |
| Voucher Quantity (Voucher only) | Required. How many vouchers to put into the prize pool. A Max quantity: N helper text shows the remaining stock in VIO. |
| Token Type (Token only) | Shown when Prize Type = Token. A dropdown with a search box. Tokens already used by another prize are greyed out. |
| Total Token Quantity (Token only) | Required. Total token pool for this prize. A Max quantity: N helper text shows the wallet balance for the selected token. |
| Token Per User (Token only) | How many tokens each redeeming member receives. Must be between 1 and the Total Token Quantity. |
| Bottom action button | Add Prize when creating a new row, Confirm when reopened from the Edit action. Disabled until all required fields are valid. |
Note: Winning Probability (%) is not set in this modal — it is edited directly in the row on the Prize Configuration table after the prize is added (see §5.1). Likewise, deleting a prize from the list is staged locally; click Save Configuration at the bottom-right of the table for the deletion to take effect.
5.2 Prize Claim Statistic Tab
This tab tells you which prizes are actually being won.
| Element | Purpose |
|---|---|
| Prize Claim Status | Section heading. |
| Time filter | Segmented control with Today, This Week, This Month, All Time. Switching the filter refetches the redemption rows used in the table. |
| Search input (placeholder Search in Prize Claim Statistic...) | Filters the table by prize name. |
Table columns
| Column | What it shows |
|---|---|
| Prize Name | The prize. Includes prizes that have been deleted from the configuration but still have historical claims — they appear at the bottom with a (Deleted) tag and are greyed out so you know they are no longer winnable. |
| Prize Type | Voucher or Token. |
| Claims | A single number — the total successful claims in the selected time range. For tokens, this counts the total amount of tokens distributed (not the number of users). |
Note: Only successful redemptions are counted. Failed deliveries are not added to the claim count.
6. Business Rules & Notes
Stamp Cycle
- Each cycle is 5 stamps — 4 store stamps plus 1 reward stamp.
- A member can collect at most one stamp per store per day. This is enforced on the merchant device; the member just sees a Stamp Collected Here modal if they try again at the same store on the same day.
- When all 5 stamps are filled, the Redeem button activates. After a successful redemption, the stamp count resets to 0 / 5.
Prize Selection
- A prize is chosen at the moment of redemption, using Winning Probability (%) as a weight.
- If no prizes are configured, the page shows a toast No rewards available at this moment. and does not consume the member's stamps.
- A failed delivery (e.g. token balance hit zero) also does not consume the stamps — the member can retry.
- After a successful redemption, the page reloads and the cycle restarts.
Stamps and Time Zone
- The "one stamp per store per day" rule uses the merchant device's local day. Stores in different time zones are treated independently.
Operator PIN
- The 6-character PIN follows the format
AA-1234(2 letters then 4 digits). It is configured per company in the underlying operator system, not in the Ops Portal. - Letters and digits cannot be mixed inside the same half — the merchant device blocks invalid characters as you type.
Member Data on the Merchant Device
- The merchant device only sees the member's username, user ID, and wallet address — those are encoded into the QR code shown by the member. It does not see the member's other VIO data.
- A fresh QR scan is required for every new session; sessions expire on the backend after a short window.
Tenant Scope
- Prizes, stores, the How to Collect Stamps? instructions, and all records are per-tenant. Different brands can have completely different setups.
Access Control
| Role | Member App | Merchant Device | Ops Portal |
|---|---|---|---|
| Regular member | Collect stamps, redeem | No access | No access |
| Merchant staff | Same as a regular member, when using their personal account | Issue stamps after PIN verification | No access |
| Tenant admin | Same as a regular member | Same as merchant staff with their own PIN | Full access (Collect Stamp, Prize Information, Edit PWA Configuration) |
See also: Mini Apps overview, Daily Check-In Mini App, Referral Mini App.