> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# NFC Cards
> Understanding the OLIVE NFC card system
# NFC Cards
NFC cards are physical, contactless cards that let you spend money from your OLIVE wallet. Tap your card at any merchant's POS terminal, enter your PIN, and the payment is done.
***
## Why Cards?
Not everyone has a smartphone. Not everyone wants to use WhatsApp for payments. OLIVE cards solve this by giving you a simple, physical way to pay:
* **Tap to pay** - No apps, no internet on your phone needed
* **Secure** - Every transaction requires your 4-digit PIN
* **Family-friendly** - Give cards to children with spending limits
* **Works offline at POS** - The merchant terminal handles connectivity
***
## Card Types
OLIVE has two types of cards that work together:
### Parent Card
Your main card, linked directly to your wallet. When you register and get a card, it's a parent card.
* Controls the wallet
* Decides spending limits for child cards
* Can allocate funds to children
* Uses your subscriber PIN (the one you set at registration)
### Child Card
Secondary cards you give to family members (spouse, children) that share your wallet but with controlled limits.
* Spends from parent's wallet balance
* Has its own independent 4-digit PIN
* Has daily and monthly spending limits
* Can have a specific allocation of funds
***
## The Parent-Child Relationship
Think of it like a family bank account:
```mermaid theme={null}
flowchart TB
subgraph wallet["Your Wallet"]
balance["Balance: 500,000 SLE"]
end
wallet --> parentCard["Parent Card
(You)"]
wallet --> child1["Child Card 1
(Wife)
Allocated: 100,000"]
wallet --> child2["Child Card 2
(Son)
Allocated: 50,000"]
style wallet fill:#065f46,stroke:#10b981,color:#fff
style balance fill:#064e3b,stroke:#10b981,color:#a7f3d0
style parentCard fill:#1e40af,stroke:#3b82f6,color:#fff
style child1 fill:#7c3aed,stroke:#a78bfa,color:#fff
style child2 fill:#7c3aed,stroke:#a78bfa,color:#fff
```
***
## Fund Allocation for Child Cards
This is one of OLIVE's powerful features. When you create a child card, you can **allocate** a specific amount for that child to spend.
### How It Works
1. **Parent has wallet balance:** 500,000 SLE
2. **Create child card for son with 50,000 allocation**
3. **Son can only spend up to 50,000 SLE** - even though parent's wallet has more
4. **Parent's own spending:** Unaffected by child allocations
### The Safety Mechanism
When your child tries to pay, OLIVE checks TWO things:
1. **Does child have remaining allocation?** - If son's allocation is 50,000 and he's spent 30,000, he can only spend 20,000 more
2. **Does parent have actual balance?** - Child can never spend more than what parent actually has
### Setting Allocations
When creating a child card:
```
allocated_amount = 50,000 SLE
```
OLIVE validates:
* Parent must have enough balance
* Total allocations to all children can't exceed parent's balance
### What Happens When Child Spends
1. Child taps card, enters child PIN
2. OLIVE checks child's remaining allocation
3. OLIVE checks parent's actual balance
4. If both pass, payment proceeds
5. Money comes from parent's wallet
6. Child's spent amount is tracked
***
## Child Card Limits
Every child card has spending limits:
### Daily Limit
Maximum the child can spend in one day. Default: **25,000 SLE** (half of parent default).
### Monthly Limit
Maximum the child can spend in one month. Default: **250,000 SLE** (half of parent default).
### How Limits Are Enforced
Before each transaction, OLIVE checks:
1. Today's total spending + this amount is within daily limit?
2. This month's total spending + this amount is within monthly limit?
3. Remaining allocation covers this amount?
If any check fails, the transaction is rejected.
***
## Child Card PIN
Child cards have their own PIN, separate from the parent:
### Why Separate PINs?
* Children don't need to know parent's PIN
* Each child has their own PIN
* If child's PIN is compromised, parent's is still safe
### How Child PIN Works
* 4 digits (0-9)
* Hashed: `SHA256(PIN + card_serial_number)`
* Stored in `nfc_cards` table, not `subscribers`
### Changing Child PIN
To change a child's PIN:
1. Parent provides their own PIN (authorization)
2. Current child PIN is verified
3. New child PIN is set
Both parent AND old child PIN are required - this prevents unauthorized changes.
***
## Card Lifecycle
### 1. Card Uploaded
OLIVE receives a batch of physical cards from manufacturer. Each has a unique serial number and MAC address.
Status: `unassigned` | Type: `parent` (default)
### 2. Card Linked (Parent)
A subscriber registers and links the card to their wallet.
Status: `assigned` | Type: `parent`
Triggers:
* Card status changes
* `linked_at` timestamp set
* Default limits applied (50K daily, 500K monthly)
* SmartPay notification sent
### 3. Child Card Created
Parent creates a child card for a family member.
Status: `assigned` | Type: `child`
Required:
* A physical card (from inventory)
* Parent's PIN (to authorize)
* Child holder name
* Child's own 4-digit PIN
Optional:
* Child's phone number (for notifications)
* Child's relationship (son, daughter, spouse)
* Daily/monthly limits (defaults to half of parent)
* Allocated amount
### 4. Card Blocked
Card can be blocked if lost, stolen, or suspicious.
Status: `blocked`
Triggers:
* WhatsApp notification to owner
* All transactions rejected
### 5. Card Unblocked
Admin or owner restores the card.
Status: `assigned` (goes back to previous active state)
### 6. Card Lost/Expired
Terminal states - card cannot be recovered.
Status: `lost` or `expired`
***
## How Many Child Cards?
| Subscriber Category | Max Child Cards |
| ------------------- | --------------- |
| Retail | 4 |
| VIP | 4 |
| PEP | 4 |
| Corporate | 100 |
Corporate subscribers get 100 because they might issue cards to employees.
***
## Card Serial and MAC Address
Every card has two identifiers:
### Serial Number
* Human-readable: `CARD0005`, `NFC12345`
* Alphanumeric only (A-Z, 0-9)
* Printed on the card
### MAC Address
* Hardware identifier: `04:64:A6:62:CF:13:95`
* Used for NFC communication
* Can be stored with or without colons
OLIVE accepts either format when looking up a card - it normalizes automatically.
***
## Card Batches
Cards are uploaded in batches (from manufacturer):
```
Batch ID: BATCH-2025-01-001
Total Cards: 500
Uploaded By: admin@olive.sl
```
This helps track card inventory and manufacturing lots.
***
## What Happens at Payment
When you tap your card at a merchant:
### For Parent Cards
1. POS reads card serial/MAC
2. OLIVE finds the card, verifies it's `assigned`
3. OLIVE finds the subscriber, verifies they're `active`
4. You enter your subscriber PIN
5. OLIVE validates: `SHA256(PIN + phone_number)` matches stored hash
6. KYC limits checked
7. Balance checked
8. Payment processed
### For Child Cards
1. POS reads card serial/MAC
2. OLIVE finds the card, verifies it's `assigned` and type is `child`
3. OLIVE finds the parent subscriber (card owner)
4. Child enters child PIN
5. OLIVE validates: `SHA256(PIN + card_serial)` matches card's PIN hash
6. Allocation checked (child's remaining amount)
7. Parent's balance checked
8. Daily/monthly limits checked
9. Payment processed from parent's wallet
***
## Notifications
OLIVE sends WhatsApp notifications for card events:
| Event | Sent To | Message |
| ------------------ | ------------------------- | ------------------------------------ |
| Card linked | Parent | Card number confirmed |
| Child card created | Parent | Child name, card, allocation, limits |
| Child card created | Child (if phone provided) | "Your parent created a card for you" |
| Card blocked | Card owner | Security alert |
| Card unblocked | Card owner | Card is now active |
| Child PIN changed | Parent | Confirmation |
| Child PIN changed | Child | "Ask parent for new PIN" |
***
## SmartPay Integration
When a card is linked, OLIVE notifies SmartPay (the POS network) with:
* First name, last name
* Phone number
* Card serial
* MAC address
This enables the card for use at SmartPay terminals.
***
## Related Concepts
Card owners
Where money lives
Payment processing
Merchant setup