Skip to main content

​
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:

​
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 CategoryMax Child Cards
Retail4
VIP4
PEP4
Corporate100
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:
EventSent ToMessage
Card linkedParentCard number confirmed
Child card createdParentChild name, card, allocation, limits
Child card createdChild (if phone provided)“Your parent created a card for you”
Card blockedCard ownerSecurity alert
Card unblockedCard ownerCard is now active
Child PIN changedParentConfirmation
Child PIN changedChild”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.

Subscribers

Card owners

Wallets

Where money lives

Transactions

Payment processing

POS Integration

Merchant setup