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

# Cards

> Manage NFC cards - linking, child cards, blocking, and bulk upload

<Info>
  NFC cards are physical payment cards that link to subscriber wallets. OLIVE supports parent cards (full access) and child cards (limited/delegated access).
</Info>

## Card Types

<CardGroup cols={2}>
  <Card title="Parent Card" icon="credit-card" color="#6366f1">
    **Primary card linked to subscriber**

    * Full wallet access
    * Can create child cards
    * Required for most operations
  </Card>

  <Card title="Child Card" icon="id-card" color="#8b5cf6">
    **Delegated access card**

    * Daily spending limit
    * For dependents/employees
    * Separate PIN from parent
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Link Card" icon="link" href="/api-reference/cards/link">
    `POST /api/v1/cards/link`

    Link parent card to subscriber
  </Card>

  <Card title="Create Child" icon="plus" href="/api-reference/cards/child">
    `POST /api/v1/cards/child`

    Create child card with limits
  </Card>

  <Card title="Get Card" icon="search" href="/api-reference/cards/get">
    `GET /api/v1/cards/{serial}`

    Get card details by serial
  </Card>

  <Card title="List Cards" icon="list" href="/api-reference/cards/list">
    `GET /api/v1/cards`

    List all cards with filters
  </Card>

  <Card title="Block Card" icon="ban" href="/api-reference/cards/block">
    `POST /api/v1/cards/{serial}/block`

    Block card from transactions
  </Card>

  <Card title="Unblock Card" icon="check-circle" href="/api-reference/cards/unblock">
    `POST /api/v1/cards/{serial}/unblock`

    Restore blocked card
  </Card>

  <Card title="Upload CSV" icon="upload" href="/api-reference/cards/upload">
    `POST /api/v1/cards/upload-csv`

    Bulk upload cards from CSV
  </Card>
</CardGroup>

***

## Card Object

```json theme={null}
{
  "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

<CardGroup cols={4}>
  <Card title="Unassigned" icon="circle" color="#6b7280">
    Available for linking
  </Card>

  <Card title="Active" icon="circle-check" color="#10b981">
    Ready for transactions
  </Card>

  <Card title="Blocked" icon="ban" color="#ef4444">
    Temporarily disabled
  </Card>

  <Card title="Lost" icon="circle-x" color="#374151">
    Permanently disabled
  </Card>
</CardGroup>

***

## Card Lifecycle

<Steps>
  <Step title="Upload">
    Admin uploads cards via CSV with serial and MAC address
  </Step>

  <Step title="Assign">
    Card linked to subscriber as parent or child
  </Step>

  <Step title="Active">
    Card ready for POS payments and transactions
  </Step>

  <Step title="Block/Unblock">
    Card can be temporarily blocked if needed
  </Step>
</Steps>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="Link New Card" icon="link">
    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
  </Accordion>

  <Accordion title="Create Child Card" icon="plus">
    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
  </Accordion>

  <Accordion title="Report Lost Card" icon="alert-triangle">
    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
  </Accordion>

  <Accordion title="Bulk Card Import" icon="upload">
    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"
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Subscriber Cards" icon="user" href="/api-reference/subscribers/cards">
    List cards for a specific subscriber
  </Card>

  <Card title="POS Payment" icon="store" href="/api-reference/pos/payment">
    Process payment with NFC card
  </Card>
</CardGroup>