Skip to main content

Cards

Info

NFC cards are physical payment cards that link to subscriber wallets. SmartPay 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/link

Link parent card to subscriber

Create Child

POST /api/v1/cards/child

Create child card with limits

Get Card

GET /api/v1/cards/{serial}

Get card details by serial

List Cards

GET /api/v1/cards

List all cards with filters

Block Card

POST /api/v1/cards/{serial}/block

Block card from transactions

Unblock Card

POST /api/v1/cards/{serial}/unblock

Restore blocked card

Upload CSV

POST /api/v1/cards/upload-csv

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

Upload

Admin uploads cards via CSV with serial and MAC address

Assign

Card linked to subscriber as parent or child

Active

Card ready for POS payments and transactions

Block/Unblock

Card can be temporarily blocked if needed

Common Workflows​

Link New Card
  1. Ensure card exists in system (uploaded via CSV)
  2. Call POST /api/v1/cards/link with subscriber ID and card serial
  3. Subscriber's PIN is set on the card
  4. Card status changes to ACTIVE
Create Child Card
  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
Report Lost Card
  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
Bulk Card Import
  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