Skip to main content
NFC cards are physical payment cards that link to subscriber wallets. OLIVE supports parent cards (full access) and child cards (limited/delegated access).

​
Card Types

Parent Card

Primary card linked to subscriber
  • Full wallet access
  • Can create child cards
  • Required for most operations

Child Card

Delegated access card
  • Daily spending limit
  • For dependents/employees
  • Separate PIN from parent

​
Endpoints

Link Card

POST /api/v1/cards/linkLink parent card to subscriber

Create Child

POST /api/v1/cards/childCreate child card with limits

Get Card

GET /api/v1/cards/{serial}Get card details by serial

List Cards

GET /api/v1/cardsList all cards with filters

Block Card

POST /api/v1/cards/{serial}/blockBlock card from transactions

Unblock Card

POST /api/v1/cards/{serial}/unblockRestore blocked card

Upload CSV

POST /api/v1/cards/upload-csvBulk upload cards from CSV

​
Card Object

{
  "serial": "OLIV0001",
  "mac_address": "AA:BB:CC:DD:EE:01",
  "type": "PARENT",
  "status": "ACTIVE",
  "subscriber_id": "sub_abc123",
  "subscriber_name": "John Doe",
  "parent_serial": null,
  "daily_limit": null,
  "linked_at": "2025-01-15T10:30:00Z",
  "created_at": "2025-01-01T00:00:00Z"
}

​
Card Status

Unassigned

Available for linking

Active

Ready for transactions

Blocked

Temporarily disabled

Lost

Permanently disabled

​
Card Lifecycle

1

Upload

Admin uploads cards via CSV with serial and MAC address
2

Assign

Card linked to subscriber as parent or child
3

Active

Card ready for POS payments and transactions
4

Block/Unblock

Card can be temporarily blocked if needed

​
Common Workflows

  1. Parent must have a linked parent card
  2. Call POST /api/v1/cards/child with limits and child info
  3. Child PIN is set (different from parent)
  4. Child can spend up to daily limit
  1. Customer reports lost card
  2. Call POST /api/v1/cards/{serial}/block with reason “lost”
  3. Card is permanently blocked
  4. Issue new card and link to subscriber
  1. Prepare CSV with columns: Serial No., MAC Address
  2. MAC supports 6-octet (AA:BB:CC:DD:EE:FF) or 7-octet formats
  3. Upload via POST /api/v1/cards/upload-csv
  4. Cards created with status “Unassigned”

Subscriber Cards

List cards for a specific subscriber

POS Payment

Process payment with NFC card