NFC Payments

The Keshless User App supports NFC-enabled payments through linked physical cards, allowing tap-to-pay functionality at supported terminals.

Overview

NFC (Near Field Communication) enables contactless payments using physical cards linked to the user's Keshless wallet.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Keshless      │     │   NFC Card      │     │   Vendor        │
│   Wallet        │────▶│   (Linked)      │────▶│   Terminal      │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Card Types

Card Type	Technology	Usage
Keshless Card	NFC NTAG	Tap-to-pay at vendors
Bank Card	EMV	Traditional POS
Phone NFC	HCE	Contactless payments

Linking a Card

Link Flow

┌─────────────────┐
│  Navigate to    │
│  Card Settings  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Tap "Link New  │
│  Card"          │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Hold Card to   │
│  Phone NFC Area │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Card PIN │
│  (if existing)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Set Card PIN   │
│  (4 digits)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Card Linked    │
│  Successfully   │
└─────────────────┘

Link Process

1. Check NFC availability on device
2. Start NFC session
3. Read card UID when tapped
4. Register card UID with backend
5. Set PIN for card

Card Management

Linked Cards View

The app displays all linked cards with:

• Card nickname
• Card type icon
• Last 4 digits (masked)
• Active/Blocked status
• Default card indicator

Card Operations

Operation	Description
Set Default	Primary card for payments
Block	Temporarily disable card
Unblock	Re-enable blocked card
Reset PIN	Change card PIN
Remove	Unlink card from wallet

Tap-to-Pay Process

Payment Flow

User taps card at vendor terminal
           │
           ▼
┌─────────────────┐
│ Terminal reads  │
│ card UID        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Terminal sends  │
│ payment request │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ API validates   │
│ card & balance  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ User enters PIN │
│ on terminal     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Payment         │
│ processed       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Notification    │
│ sent to user    │
└─────────────────┘

Transaction Limits

Setting	Limit
Per tap (no PIN)	E100
Per tap (with PIN)	E2,000
Daily total	E5,000

Card Security

PIN Management

Requirement	Value
PIN Length	4 digits
PIN Format	Numeric only
Hashing	Hashed before transmission

Blocking Rules

Cards are automatically blocked when:

• 3 consecutive wrong PIN attempts
• Suspicious transaction patterns
• User reports lost/stolen
• Account suspended

NFC Reading (Phone)

Users can read NFC cards to check balance or top up.

API Endpoints

Endpoint	Method	Description
/cards	GET	List linked cards
/cards/link	POST	Link new card
/cards/:id	DELETE	Unlink card
/cards/:id/block	POST	Block card
/cards/:id/unblock	POST	Unblock card
/cards/:id/pin	POST	Set/reset PIN
/cards/:id/default	POST	Set as default

Error Handling

Error	Cause	Action
NFC_001	NFC not available	Enable NFC
NFC_002	Card read failed	Reposition card
NFC_003	Card already linked	Use different card
NFC_004	Card blocked	Contact support
NFC_005	Invalid PIN	Try again (3 attempts)

Troubleshooting

Common Issues

Issue	Solution
Card not detected	Remove phone case, hold steady
"NFC not available"	Enable NFC in phone settings
Card read timeout	Hold for 3+ seconds
Wrong card type	Only Keshless NFC cards supported

Related Files

File	Purpose
lib/screens/cards/cards_list_screen.dart	Cards list
lib/screens/cards/link_card_screen.dart	Link card
lib/screens/cards/card_details_screen.dart	Card details
lib/controllers/card_controller.dart	Card controller
lib/services/nfc_service.dart	NFC service
lib/services/card_service.dart	Card service