Card Operations

Vendors with agent permissions can perform card operations for customers including linking, blocking, unblocking, and PIN reset.

Overview

Card operations available to agents:

• Link new card to customer wallet
• Block card (lost/stolen)
• Unblock previously blocked card
• Reset card PIN

Link Card

Link Flow

┌─────────────────────────────────────────────────────────┐
│                    Link Card Flow                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│
│  │   Find      │────▶│   Read NFC  │────▶│   Set PIN   ││
│  │   Customer  │     │   Card      │     │   (4 digits)││
│  └─────────────┘     └─────────────┘     └──────┬──────┘│
│                                                  │       │
│                                                  ▼       │
│                                          ┌─────────────┐│
│                                          │   Success   ││
│                                          │   Linked    ││
│                                          └─────────────┘│
│                                                          │
└─────────────────────────────────────────────────────────┘

Link Steps

1. Find customer by phone number
2. Tap NFC card on device
3. Customer sets 4-digit PIN
4. Card linked to wallet

NFC Scan States

State	Display
Waiting	Animated NFC icon
Scanning	"Reading card..."
Success	"Card detected" + masked UID
Error	Error message + retry button

Block Card

Block Steps

1. Find customer by phone number
2. Select card to block (from list)
3. Enter reason for blocking
4. Confirm block action

Block Reasons

Reason	Description
Lost	Customer lost card
Stolen	Card was stolen
Damaged	Card is damaged
Customer Request	General request
Fraud Suspected	Suspicious activity

Unblock Card

Unblock Steps

1. Find customer by phone number
2. View blocked cards only
3. Select card to unblock
4. Confirm unblock action

Note: Only previously blocked cards can be unblocked.

Reset PIN

PIN Reset Flow

Customer forgot PIN → Agent verifies identity → Agent initiates reset → Customer enters new PIN

Reset Steps

1. Find customer by phone number
2. Select card for PIN reset
3. Customer enters new 4-digit PIN
4. Customer confirms new PIN
5. PIN updated

Identity Verification

Always verify customer identity before resetting PIN. Request ID document and match with registered name.

PIN Requirements

Requirement	Value
Length	4 digits
Format	Numeric only
Confirmation	Must match

API Endpoints

Endpoint	Method	Description
/cards/link	POST	Link new card
/cards/:id/block	POST	Block card
/cards/:id/unblock	POST	Unblock card
/cards/:id/reset-pin	POST	Reset PIN

Error Handling

Error	Cause	Action
CARD_001	Card already linked	Use different card
CARD_002	Card not found	Verify card type
CARD_003	Customer not found	Verify phone
CARD_004	Already blocked	No action needed
CARD_005	Not blocked	Cannot unblock

Related Files

File	Purpose
lib/screens/cards/link_card_screen.dart	Link card
lib/screens/cards/block_card_screen.dart	Block card
lib/screens/cards/unblock_card_screen.dart	Unblock card
lib/screens/cards/reset_pin_screen.dart	Reset PIN
lib/controllers/card_controller.dart	Card controller
lib/services/card_service.dart	Card service