POS (Point of Sale)

The POS screen enables vendors to accept NFC card payments from Keshless users.

Overview

The vendor taps the customer's Keshless card on their phone to initiate a payment. The amount is deducted from the customer's wallet and credited to the vendor's account.

Payment Flow

┌─────────────────────────────────────────────────────────┐
│                    POS Payment Flow                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│
│  │   Enter     │────▶│   Tap Card  │────▶│   Verify    ││
│  │   Amount    │     │   (NFC)     │     │   Customer  ││
│  └─────────────┘     └─────────────┘     └──────┬──────┘│
│                                                  │       │
│                                                  ▼       │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│
│  │   Receipt   │◀────│   Success   │◀────│   Enter     ││
│  │   Screen    │     │             │     │   PIN       ││
│  └─────────────┘     └─────────────┘     └─────────────┘│
│                                                          │
└─────────────────────────────────────────────────────────┘

Step 1: Enter Amount

The vendor enters the payment amount using a numeric keypad.

Amount Validation

Rule	Limit
Minimum	E1
Maximum	E10,000
Decimals	2 places

Step 2: NFC Card Reading

After entering amount, the app waits for card tap:

NFC States

State	Display
Waiting	Animated NFC icon
Reading	"Reading card..."
Success	Green checkmark
Error	Error message + retry

Process Flow

1. Start NFC session
2. Read card UID on tap
3. Lookup card owner via API
4. Check if PIN required (amount > E100)
5. Proceed to PIN entry or process directly

Step 3: PIN Verification

For amounts over E100, customer enters PIN:

PIN Rules

Setting	Value
PIN Length	4 digits
Max Attempts	3
Lockout	15 minutes
PIN-free Limit	E100

PIN Entry

• Customer enters 4-digit PIN on vendor's device
• PIN is hashed before transmission
• On 3 failed attempts, card is locked

Step 4: Payment Success

Display confirmation and receipt:

• Success animation
• Amount displayed
• Transaction reference
• Receipt options

Receipt Options

Option	Description
Print	Bluetooth thermal printer
SMS	Send to customer phone
Share	Share via apps
None	Skip receipt

POS Service Methods

Method	Description
lookupCard(cardUid)	Get card owner info
verifyAndPay(cardUid, amount, pin)	Process payment

API Endpoints

Endpoint	Method	Description
/pos/lookup	GET	Lookup card info
/pos/pay	POST	Process payment
/pos/verify-pin	POST	Verify PIN only
/pos/receipt/:id	GET	Get receipt data

Error Handling

Error	Cause	Action
POS_001	Card not found	Check card is Keshless
POS_002	Insufficient funds	Customer needs top-up
POS_003	Card blocked	Contact support
POS_004	Invalid PIN	3 attempts max
POS_005	Daily limit exceeded	Try tomorrow
POS_006	NFC read failed	Reposition card

Related Files

File	Purpose
lib/screens/pos/amount_entry_screen.dart	Amount entry
lib/screens/pos/nfc_payment_screen.dart	NFC payment
lib/screens/pos/pin_entry_screen.dart	PIN entry
lib/screens/pos/payment_success_screen.dart	Payment success
lib/controllers/pos_controller.dart	POS controller
lib/services/pos_service.dart	POS service
lib/services/nfc_service.dart	NFC service