Session Management

Sessions are the core billing unit in HandyCafe. Every time a customer in your internet cafe or gaming center uses a PC or gaming console, a session tracks their usage time and calculates the cost. This page explains the full session lifecycle, from starting a session to collecting payment.

Session Types

HandyCafe supports two types of sessions:

• PC sessions. Sessions on client PCs managed through the Admin Panel. The client software locks the PC when idle and unlocks it when a session starts.
• Console sessions. Sessions on gaming consoles (PlayStation, Xbox, etc.) managed through the Consoles page. These are tracked by the server only; there is no client software on the console itself.

Both session types follow the same pricing engine and lifecycle but are managed from different pages in the dashboard.

Session Lifecycle

Every session follows a defined lifecycle with clear state transitions:

Start --> Running --> (Pause <--> Resume) --> Add Time --> Stop

The states in detail:

1. Start. A cashier initiates the session. The client PC unlocks or the console timer begins.
2. Running. The session is active. Time is counting and billing is accumulating.
3. Pause. The cashier temporarily halts the session. Billing stops. The client shows a paused state.
4. Resume. The cashier continues a paused session. Billing resumes from a new pricing segment.
5. Add Time. The cashier adds (or removes) minutes to an active session.
6. Stop. The session ends. The system calculates the final cost and prompts for payment.

Starting a Session

To start a new session on a client PC:

1. Select the client. In the Admin Panel, click a PC that is in the Idle (cyan) state to reveal the action buttons.
2. Choose the billing type. Select either Postpaid (pay at the end) or Prepaid (pay upfront).
3. Assign a member (optional). If the customer is a registered member, search for their account using the autocomplete member search field. Assigning a member enables wallet payments and tracks the session in their history.
4. Set duration or amount (prepaid only). For prepaid sessions, enter either the number of minutes the customer is purchasing or the monetary amount they are paying. The system calculates the corresponding time based on the current pricing slot.
5. Select payment method. Choose the payment method (Cash, Credit Card, or any custom method you have configured).
6. Confirm. Review the details and confirm. The client PC unlocks immediately and the session timer begins.

For console sessions, the process is similar but is initiated from the Consoles page.

Postpaid Sessions

In a postpaid session, the customer uses the PC first and pays when they are done. This is the most common billing mode in internet cafes, cybercafes, and gaming centers.

How it works:

• The session starts with no upfront payment.
• The timer runs and the cost accumulates in real time based on the active pricing slot.
• When the session is stopped, the system presents the final calculated cost.
• The cashier collects payment and confirms the transaction.

Postpaid sessions have no time limit. They run until the cashier stops them or the customer requests to leave.

Prepaid Sessions

In a prepaid session, the customer pays upfront for a specific amount of time. The session automatically ends when the purchased time expires.

There are two prepaid pricing modes, configured in Settings > Pricing:

Lock at Purchase

The cost is frozen at the moment the session starts. The pricing slot and multiplier active at the time of purchase are used for the entire session duration, regardless of schedule changes that occur while the session is running.

Example: A customer buys 60 minutes at 10:00 AM during a standard-rate slot. Even if the pricing schedule switches to a half-price slot at 11:00 AM, the customer's remaining time is not affected. They received exactly what they paid for at the original rate.

Live Schedule

The cost adjusts in real time as the session passes through different pricing slots. If the customer's session spans a slot change, the remaining time is recalculated based on the new pricing.

Example: A customer buys 60 minutes at 10:00 AM during a standard-rate slot. At 11:00 AM, the schedule switches to a half-price slot. Since each minute now costs half as much, the customer's remaining time effectively stretches. They may end up with more total minutes than originally purchased.

Pausing a Session

Pausing temporarily halts billing without ending the session. This is useful when a customer needs to step away briefly.

To pause a session:

1. Select the active PC in the Admin Panel and click the Pause button on the card.

What happens when a session is paused:

• Billing stops immediately. No cost accrues during the pause.
• The current pricing segment is closed with a "pause" boundary.
• The client PC displays a paused state with an orange status indicator.
• The session timer freezes.

Paused sessions remain paused indefinitely until a cashier resumes or stops them.

Resuming a Session

Resuming continues a paused session from where it left off.

To resume a session:

1. Select the paused PC in the Admin Panel and click the Resume button on the card.

What happens when a session is resumed:

• A new pricing segment begins at the current time, using the active pricing slot.
• Billing resumes.
• The client PC returns to the active (green) state.

Note that the pricing slot at resume time may differ from the slot when the session was paused. The new segment uses whatever rate is currently active on the pricing schedule.

Adding Time

You can add or remove minutes from an active session at any time.

To add time:

1. Select the active PC in the Admin Panel and click the Add Time button on the card.
2. Enter the number of minutes to add. Use a positive value to extend the session or a negative value to reduce it.
3. Confirm.

What happens when time is added:

• A transaction record is created in the session history.
• For prepaid sessions, the end time is adjusted forward (or backward) by the specified number of minutes.
• For postpaid sessions, the add-time event is recorded but does not set a hard end time.

Stopping a Session

Stopping a session ends all billing, locks the client PC, and triggers the payment process.

To stop a session:

1. Select the active or paused PC in the Admin Panel and click the Stop button on the card.
2. The Payment Dialog appears showing a summary of the session.

Payment Dialog

The payment dialog displays the following information:

Cashier override: The cashier can manually adjust the charged amount. For example, a cashier might round down as a courtesy or apply a manual discount. The original computed amount is always preserved in the records for auditing.

4. Select a payment method and confirm. The session is recorded, the client PC locks, and the transaction is saved.

Settlement Process

When a session is stopped, the settlement engine runs through these steps:

1. Close the last open pricing segment.
2. Sum all closed segment amounts.
3. Apply rounding rules (always rounds up to the configured rounding step).
4. Apply the startup fee minimum (the total is never less than the startup fee).
5. Calculate payment method commission (BPS-based) and fixed fee.
6. Present the final amounts in the payment dialog.

For a detailed explanation of how pricing segments and settlement calculations work, see Session Pricing.

Member Sessions

When a member is assigned to a session, additional billing options become available:

• Wallet payment. The session cost can be deducted from the member's wallet balance.
• Time package deduction. If the member has purchased a time package, minutes are deducted from their package balance instead of charging a monetary amount.
• Member discount. If the member has a discount configured (in basis points), it is applied to the session cost.
• Session history. The session is linked to the member's account and appears in their session history.

Members can also start their own sessions from the client idle screen by logging in with their username and password or through OAuth (if configured).

Session Status Values

Each client PC displays a color-coded status indicator:

These status colors appear on client cards in the Admin Panel, making it easy to see the state of every PC at a glance.

Session Pricing Segments

Each session is divided into one or more pricing segments. A new segment is created whenever a billing-relevant event occurs:

• Session start
• Pause
• Resume
• Pricing slot change (when the clock crosses into a different time slot on the schedule)
• Base price change (if the admin changes the hourly rate mid-session)
• Disconnect or reconnect

Each segment records the pricing slot, multiplier, base price, start time, end time, and calculated amount. The session total is the sum of all segments, subject to rounding and minimum charge rules.

For full details on how segments are calculated, see Session Pricing.

Minimum Charge and Startup Fee

Even very short sessions are charged at least the startup fee amount. This is configured in Settings > Pricing and ensures that every session generates a minimum level of revenue, regardless of how brief the usage was.

Example: If your startup fee is set to $1.00 and a customer uses a PC for only 30 seconds, the charged amount is $1.00, not the fraction of a cent that 30 seconds would cost at the hourly rate.

Next Steps

• Session Pricing: Deep dive into the pricing engine, segments, and settlement math
• Admin Panel: Monitor and control client PCs
• Members: Manage member accounts and wallets
• Cash Report: Review session revenue and shift summaries