Skip to main content

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