Registration Reward Mini App - User Guide

The Registration Reward Mini App gives a welcome reward (tokens and/or vouchers) to every new member the moment they finish signing up. Members do not need to do anything — the reward is delivered automatically. Operators use the Ops Portal to choose the rewards and turn the feature on or off.

Note: This Mini App has no member page. New members simply see the reward appear in their wallet after registration. Operators access the Ops Portal from the Admin Portal.

How to Access
Member Experience
VIO External API Key Gate
Ops Portal - Reward Configuration
Ops Portal - Grant History
Business Rules & Notes

1. How to Access

For Members

Nothing to do. New members receive the welcome reward in the background after registering with VIO.
There is no tile, no scan, and no claim button on the Member App.

For Administrators (Ops Portal)

Open the Admin Portal and sign in with an account that belongs to the tenant.
From Dashboard or Mini Apps, open Register. The Ops Portal loads inside the Admin Portal frame.
The page header shows Registration Reward with the subtitle Configure rewards and review grant history, plus a VIO External API key button on the right.
Two tabs appear below the header:
- Reward configuration (default landing page) — configure tokens / vouchers and switch the campaign on or off.
- Grant history — review every registration where a reward was attempted, and resend failed lines.

Note: Operator access requires Admin Portal permissions assigned by your tenant administrator. The Ops Portal also requires the VIO External API Key to be saved for the tenant — without it, rewards cannot be delivered. See Section 3.

2. Member Experience

There is no dedicated member screen for Registration Reward. After a member completes registration with VIO, the configured tokens and vouchers are delivered automatically in the background and show up in the standard Member App surfaces.

Where	What to look for
Home - Balance	Token balance increases by the configured amount. The exact label and icon follow whatever is set up for the token in VIO.
Transaction History	A new transaction line for the token reward, with the timestamp matching when the platform delivered it.
Vouchers	A new voucher card for each voucher reward. The card shows the voucher name, image, and validity dates straight from VIO.

Tip: Rewards are queued through the VIO platform and may not appear instantly. If a member does not see a reward right after registering, ask them to wait a moment and refresh the relevant page once. If it is still missing after a few minutes, check Grant history in the Ops Portal to confirm the delivery status.

3. VIO External API Key Gate

On first access (or when no key is saved), a gate modal asks the administrator to set up the VIO External API Key. The modal cannot be closed by clicking outside — you must save a valid key before the rest of the Ops Portal becomes usable. Without the key, the system can record registrations but cannot deliver tokens or vouchers.

How to use:

Step 1: Get API Key

Obtain the tenant API Key from the VIO Admin Portal (look under the API Keys section).
The key starts with vio_live_…. Each tenant has its own key.

Step 2: Enter API Key

Paste the key into the field. The placeholder reads Paste your vio_live_… key.
If you submit an empty value, the modal shows Paste your VIO External API key to continue.

Step 3: Submit

Click Confirm to save. The label changes to Saving… while the request runs.
On success the modal closes and the Reward configuration tab becomes available.
On failure the modal stays open and shows the server's error message — fix the key and try again.

To change the key later, click the VIO External API key button in the top-right of the page header. The same modal reopens; saving overwrites the previous key.

Note: The key is stored on the server, not in the browser. Only operators with Admin Portal access can update it. Rotate the key here — do not paste it into other portals or share it through unencrypted channels.

4. Ops Portal - Reward Configuration

The Reward configuration tab is the default landing page. It has two simple steps:

Step 1 — Reward items: Build the list of tokens / vouchers a new member will receive.
Step 2 — Registration rewards: Turn the feature on so the list is actually delivered.

4.1 Step 1 — Reward items

The list shows every reward that will be granted after registration.

Control	Purpose
Add token	Pick a token from VIO and set the amount each new member receives.
Add voucher	Pick a voucher from VIO.
Edit	Change the amount or selection on an existing row.
Remove	Delete a row from the list.
Save reward list	Save the changes. Nothing is applied to new registrations until you save.

Note: Empty state shows No reward items yet. Each saved row shows either a Token or Voucher badge with the reward name.

How to use:

Step 1: Add a reward

Click Add token or Add voucher. A picker opens:
- Select token — Search box, scrollable token list (icon, name, symbol, supply / available). Pick a token, enter the Amount each new member should receive, then click OK. Tokens with zero available balance are greyed out and cannot be selected.
- Select voucher — Search box, scrollable voucher list (image, name, value, stock such as Unlimited stock / N left / Sold out, and per-user limit). Pick a voucher and click OK. Sold-out vouchers are greyed out and cannot be selected.
Both pickers have Cancel and a close (✕) button to back out without saving. After clicking OK, the new reward appears as a row in the list but is not yet saved — the row is held as an unsaved edit until you click Save reward list in Step 3.

Step 2: Adjust the list

Edit reopens the same picker with the existing values prefilled. Change the amount or selection, then click OK to update the row.
Remove opens a confirm dialog Remove this reward? with Cancel and Remove. Choose Remove to delete the row; Cancel keeps it.
Like Step 1, changes here are held locally until you click Save reward list.

Step 3: Save

Click Save reward list. The label changes to Saving… while the request runs.
On success a toast shows Reward list saved, and the saved list becomes the one used for new registrations.
Once saved, the button becomes disabled until you make another change.
If you reload the page or leave without saving, any pending edits are discarded.

4.2 Step 2 — Registration rewards

This block decides whether the saved reward list is actually delivered to new members.

Control	Purpose
Grant rewards to new users	Master switch. The current state is shown next to the toggle as On or Off.
Save registration rewards setting	Save the toggle change. Until you click save, the live system is unchanged.

What On / Off do

On — Every new member registered through VIO will automatically receive the items in the saved reward list. To enable it, you must already have (a) a saved API key and (b) at least one saved reward item; otherwise the system will reject the save with an error toast.
Off — New registrations are skipped. No reward is delivered and no row is written to Grant history. Existing rewards already in members' wallets are not affected.

How to use:

Step 1: Toggle

Switch Grant rewards to new users on (or off). The label next to the switch immediately updates to the new state, but the live system has not changed yet.

Step 2: Save

Click Save registration rewards setting. The label changes to Saving… while the request runs.
On success a toast confirms the new state: Registration rewards enabled or Registration rewards disabled.
Once saved, the button becomes disabled until you toggle the switch again.
If the save fails (for example because there is no API key or no reward item), a toast explains the problem and the live state is not changed.

Note: Turning the switch Off only stops future registrations. Rewards already given to members stay in their wallets — there is no automatic reversal.

5. Ops Portal - Grant History

The Grant history tab lists every registration where a reward was attempted. Each row is one registration; if a registration includes multiple rewards, they appear as extra lines under the same time and user.

5.1 Filters

There is no search bar. Use the filters at the top to narrow the list. Changing any filter automatically resets the table to page 1.

Filter	Options	What it does
Per page	10, 20, 50, 100	Sets how many registrations appear on one page.
Sort	Newest first, Oldest first	Orders the list by the attempt time.
Overall	All, All sent, Partial, All failed, Unknown	Filters by the registration-level result (see Section 5.2).
Type	All, Token, Voucher	Filters by reward line type, useful for finding a specific failure pattern.

Pagination buttons at the bottom («, ‹, ›, ») move between pages, and a footer line shows N record(s) · Rows X–Y of Z when the list spans multiple pages.

5.2 Table

Each registration takes one block in the table. Time, User, and Overall are shown once for the whole block; each reward line (Token / Voucher) adds an extra row beneath.

Column	Description
Time	When the reward was attempted. Format follows your browser locale.
User	The new member's name (as supplied by VIO).
Overall	Result for the registration as a whole: All sent (every line delivered), Partial (some delivered, some failed), All failed (none delivered), or Unknown (status still unclear, often because of a network hiccup).
Reward type	Token or Voucher badge for that line.
Reward name	Name of the token or voucher exactly as returned by VIO.
Status	Sent (green) or Failed (red) for each reward line. Failed lines show a short reason such as Out of stock or Invalid key.
Action	Resend button — visible only on failed lines, and only for operators with the admin role.

If the page is empty, you will see No grant records yet. along with a hint that grants will appear here once new users register and rewards are attempted.

5.3 Resend Failed Rewards

For administrators, when a reward shows Failed:

How to use:

Step 1: Find the row

Use the Overall filter (Partial / All failed) to locate the registration. The Type filter (Token / Voucher) helps narrow further.
Each registration may have several reward lines stacked under the same Time and User.

Step 2: Fix the cause

Read the Reason on the failed row to understand why it failed (for example: out of stock, invalid key, insufficient token balance).
Address the underlying issue before retrying — clicking Resend without fixing the cause will simply fail again.

Step 3: Resend

Click Resend on the failed line. The label changes to Sending… while the request runs.
On success the row's Status flips to Sent, and the Overall badge for the registration may move from Partial or All failed to All sent depending on the other lines.
On failure the row stays Failed and the Reason is updated with the latest error.

Note: Resend retries only that one reward line, not the whole registration. Other failed lines need to be retried individually.

6. Business Rules & Notes

Trigger

The reward fires automatically when VIO records a successful registration.
This Mini App does not poll for new members — it relies on VIO calling it.

One reward per member

Each new member receives the welcome reward once. Repeats are ignored, so members cannot be rewarded twice for the same registration.

Reverting

Switching Grant rewards to new users off only affects future registrations.
There is no automatic way to take back a reward that has already been delivered.

Tenant differences

The reward content (tokens, vouchers, amounts) and the per-voucher per-user limit are configured per tenant and can differ between brands.

Access Control

Role	Member App	Ops Portal
Regular Member	Receives the reward automatically	No access
Tenant Admin	Receives the reward like any other member	Full access (Reward configuration, Grant history, Resend)

Registration Reward Mini App - User Guide ​

Table of Contents ​

1. How to Access ​

For Members ​

For Administrators (Ops Portal) ​

2. Member Experience ​

3. VIO External API Key Gate ​

How to use: ​

4. Ops Portal - Reward Configuration ​

4.1 Step 1 — Reward items ​

How to use: ​

4.2 Step 2 — Registration rewards ​

How to use: ​

5. Ops Portal - Grant History ​

5.1 Filters ​

5.2 Table ​

5.3 Resend Failed Rewards ​

How to use: ​

6. Business Rules & Notes ​

Trigger ​

One reward per member ​

Reverting ​

Tenant differences ​

Access Control ​

Registration Reward Mini App - User Guide

Table of Contents

1. How to Access

For Members

For Administrators (Ops Portal)

2. Member Experience

3. VIO External API Key Gate

How to use:

4. Ops Portal - Reward Configuration

4.1 Step 1 — Reward items

How to use:

4.2 Step 2 — Registration rewards

How to use:

5. Ops Portal - Grant History

5.1 Filters

5.2 Table

5.3 Resend Failed Rewards

How to use:

6. Business Rules & Notes

Trigger

One reward per member

Reverting

Tenant differences

Access Control