Member Wallet
The member wallet is a monetary balance system that allows members to prepay for cafe services. Instead of paying cash for each individual session, a member can load funds into their wallet and the system deducts from that balance automatically as they use PCs, consoles, or order products.
Credit-Based Architecture
The wallet uses a credit system rather than a single running balance. Every time funds are added to a member's wallet, the system creates a new wallet credit. Each credit entry is an individual record with its own balance, source, expiration, and device restriction. This design provides:
- Full traceability of where each unit of balance came from.
- Independent expiration dates per credit entry.
- Device-specific restrictions (some credits may only be usable on PCs, others only on consoles).
- Clear separation between paid funds and promotional bonuses.
The member's total wallet balance is the sum of all remaining values across their active credit entries.
Credit Types
Each wallet credit has a credit type that identifies how the funds entered the system:
| Credit Type | Description |
|---|---|
| Paid | The member paid for these funds (cash, card, or other payment method). Created when purchasing a money-based campaign package. |
| Bonus | Promotional funds granted as part of a package purchase. For example, "pay for 100 minutes, get 20 bonus minutes worth of credit." |
| Manual | Manually loaded by a cashier or admin. Used for goodwill credits or special arrangements. |
| Correction | An administrative adjustment to fix an error in the member's balance. |
| Migration | Funds imported from a legacy system during data migration. |
| Reversed refund | Funds restored when a previously issued refund is reversed. |
The credit type is set when the credit is created and cannot be changed afterward. It serves as a permanent audit trail.
Credit Status
Each wallet credit goes through a lifecycle tracked by its status:
- Active: The credit has remaining funds and has not expired. Funds can be consumed from this credit.
- Expired: The credit's expiration date has passed. Any remaining funds are no longer usable.
- Consumed: The credit's remaining balance has reached zero through normal consumption.
- Cancelled: The credit was manually cancelled by an administrator, voiding any remaining balance.
Wallet Consumption
When a member's wallet is charged (for session time, an order, or another billable event), the system creates a wallet consumption record that links to a specific credit entry and records exactly how much was deducted.
Each consumption record includes a context that identifies what triggered the deduction:
| Context | Description |
|---|---|
| Session usage | Funds consumed to pay for session usage time. The system deducts from the wallet as the session runs. |
| Wallet payment | A direct payment from the wallet (for example, when the member pays for a product order using wallet balance). |
| Order | Funds consumed to pay for a product order at the cafe counter or delivered to the member's PC. |
| Refund | A negative adjustment created when a refund is processed, reducing the consumption to return funds to the credit entry. |
Each consumption record links back to the specific session, order, or transaction that caused it, enabling full audit tracing.
Balance Log
In addition to the credit-level consumption records, the system maintains a member balance log that records every event that changes the member's overall wallet balance:
| Event Type | Description |
|---|---|
load |
Funds were added to the wallet (new credit entry created or existing one topped up). |
spend |
Funds were consumed from the wallet (session payment, order payment). |
refund |
Funds were returned to the wallet (order refund, session refund). |
adjustment |
An administrative change was made to the balance (correction, write-off). |
Each balance log entry records the amount of the change and the resulting balance, so you can reconstruct the member's balance at any point in time by reading the log chronologically.
Device Restriction
Each wallet credit has a device restriction that controls which types of devices can consume from it:
| Restriction | Meaning |
|---|---|
| Client | Usable on client PCs. Also usable on consoles unless the credit was explicitly restricted. |
| Console | Usable on gaming consoles. Also usable on PCs unless explicitly restricted. |
| PCs only | Usable exclusively on client PCs. Cannot be consumed by console sessions. |
| Consoles only | Usable exclusively on gaming consoles. Cannot be consumed by PC sessions. |
| Both | Usable on any device type with no restriction. This is the default. |
When the system needs to deduct from a member's wallet, it filters the available credits by device restriction to ensure only eligible credits are charged.
Wallet Category and Cross-Category Spend
Wallet credits can be tagged with a wallet category (for example, "gaming" or "general"). This allows the cafe to create isolated balance pools that can only be spent in certain contexts.
The cross-category spending option on each credit controls whether its funds can be used outside the designated category:
- When disabled (default), the credit can only be consumed in its own category.
- When enabled, the credit can also be consumed by transactions in other categories.
If a credit has no wallet category assigned, it is treated as a general-purpose credit and can be consumed by any transaction regardless of category.
How Top-Ups Work
Wallet funds can be added through several methods:
Campaign package purchase: When a member buys a money-based package from a campaign, the system automatically creates wallet credits based on the package definition. A single package purchase may create multiple credits (one for the paid portion, one for the bonus portion).
Manual load: A cashier can manually add funds to a member's wallet from the member detail panel. This creates a credit entry with the "Manual" credit type.
Migration: During system setup, existing balances from a previous system can be imported as credit entries with the "Migration" credit type.
How the Wallet Is Consumed During Sessions
When a member with wallet balance starts a session, the system can automatically pay for the session from the wallet:
- The session pricing engine calculates the cost per minute based on the active pricing slot and any applicable tier discounts.
- As the session runs, the system periodically deducts the accumulated cost from the member's eligible wallet credits.
- Credits are consumed in order of expiration date (earliest-expiring credits are used first) to minimize waste from expiration.
- If the wallet balance is exhausted before the session ends, the remaining cost is charged as a cash payment at session close.
- Each deduction creates a consumption record linked to the session as a "Session usage" entry.