POS Guide

This is a step-by-step walkthrough of the entire POS system, from initial setup to accepting payments.

End-to-End Overview

Setup (once) --> Cashier logs in --> Creates payment --> Customer pays --> Payment tracked

---

Phase 1: Merchant Setup (One-Time)

The merchant does this from the main dashboard, logged in with their account.

Step 1: Create Terminals

Go to Dashboard > POS > Terminals > Create Terminal.

For each physical register or POS station:

1. Enter a name (e.g., "Register 1")

2. Enter a short code (e.g., R1) -- this is an identifier, not a password

3. Select the merchant wallet address to receive payments

4. Optionally set a default blockchain network and token

5. Click Create

Repeat for each register.

Step 2: Create Cashiers

Go to Dashboard > POS > Cashiers > Create Cashier.

For each staff member:

1. Enter their name (e.g., "John Doe")

2. Enter a short code (e.g., JD) -- used in order tracking

3. Enter a PIN -- must be 8+ digits, numbers only

4. Click Create

5. Share the PIN with the cashier privately

Repeat for each staff member.

Step 3: (Optional) Set Cashier Restrictions

If you want to limit which cashiers can use which terminals:

1. Go to Dashboard > POS > Terminals

2. Click Edit on a terminal

3. Toggle on only the cashiers who should access this terminal

4. Click Save

See Cashier Restrictions for details.

Step 3b: (Optional) Set Token Restrictions

If you want to limit which tokens are available on a terminal:

1. Go to Dashboard > POS > Terminals

2. Click Edit on a terminal (or configure during creation)

3. Toggle on Restrict Available Tokens

4. Select the tokens you want this terminal to accept

5. Click Save

When enabled, cashiers will only see the selected tokens and networks. See Token Restrictions for details.

Step 4: Set Up the Device

On your POS device (tablet, phone, laptop):

1. Open a browser

2. Navigate to the terminal URL: https://your-domain.com/pos/{terminalId}

3. Bookmark it or add to home screen

4. Use fullscreen mode for the best experience

5. The PIN login screen appears -- ready for cashiers

---

Phase 2: Cashier Login

This happens at the start of a shift or after a session expires.

1. Cashier sees the PIN keypad on screen

2. Cashier enters their 8+ digit PIN using the on-screen number pad

   • Only digits are shown -- no letters, no special characters

3. If the PIN is valid and the cashier is allowed on this terminal:

   • Login succeeds

   • 15-minute session starts

   • Payment screen appears

4. If the PIN is invalid or cashier is not allowed:

   • Error message is shown

   • Cashier can try again

---

Phase 3: Creating a Payment

Once logged in, the cashier creates payments for customers.

Step 1: Enter Amount

1. The payment creation screen shows a numeric keypad

2. Cashier enters the amount in USD (e.g., 50.00)

3. Clicks Next or Continue

Step 2: Select Network & Token

1. Choose the blockchain network (e.g., Ethereum, Polygon, Base)

2. Choose the token (e.g., USDC, USDT, ETH)

3. If a non-stablecoin is selected, the system calculates the equivalent amount at current price

4. Clicks Create Payment

Step 3: Customer Pays

1. A QR code is displayed on screen

2. Below the QR, the wallet address is shown in truncated form -- tap it to reveal the full address (useful for customers who cannot scan)

3. The customer scans the QR code with their crypto wallet

4. The customer confirms the payment in their wallet

5. The terminal shows payment status (pending > confirmed > completed)

Partial payments: If the customer sends less than the requested amount, the terminal detects it automatically and shows a progress bar with options to collect the partial amount or wait for the remainder. See Payment History & Recovery for details.

Step 4: Order ID is Generated

The system automatically creates an Order ID:

POS-R1-JD-1707842400000

This links the payment to Register 1, cashier John Doe, at the exact timestamp.

---

Payment Flow Summary

#	Who	Action
1	Cashier	Enters PIN on numeric keypad
2	Server	Verifies PIN, finds matching cashier
3	Server	Creates session (15 min)
4	Cashier	Enters payment amount ($50.00)
5	Cashier	Selects network and token
6	Server	Generates Order ID (POS-R1-JD-17078...)
7	Server	Creates QR code
8	Customer	Scans QR code with wallet
9	Customer	Confirms and sends payment
10	Blockchain	Confirms transaction
11	Server	Marks payment complete

---

Phase 4: Session Management

During the shift:

• The countdown timer shows remaining session time

• Every action (entering amounts, creating payments) resets the timer to 15 minutes

• If the cashier is idle for 15 minutes, they are automatically logged out

• A warning appears when less than 60 seconds remain

• The cashier can manually log out at any time (e.g., end of shift, break)

• The History button (clock icon) lets cashiers view their payment history and resume pending payments

Payment Recovery

If the terminal crashes, loses power, or the browser closes mid-payment:

1. Reopen the terminal and log in

2. Tap the History button in the header

3. Find the pending payment and tap Resume

The original payment is restored -- same QR code, same address, same amount. See Payment History & Recovery for full details.

---

Phase 5: Merchant Monitoring

The merchant can monitor all activity from the dashboard:

• View all payments across terminals

• Filter by terminal or cashier using Order IDs

• See which cashier processed each payment

• Manage terminals and cashiers in real-time

• Reset PINs if a cashier forgets theirs

• Deactivate cashiers who leave the team

---

Quick Reference

Action	Where	Who
Create terminal	Dashboard > POS > Terminals	Merchant
Create cashier	Dashboard > POS > Cashiers	Merchant
Set restrictions	Dashboard > POS > Terminals > Edit	Merchant
Reset PIN	Dashboard > POS > Cashiers > Reset PIN	Merchant
Login to terminal	Terminal URL (/pos/{id})	Cashier
Create payment	Terminal (after login)	Cashier
View payments	Dashboard > Payments	Merchant