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

# POS Terminal

> Smart PAY POS terminal integration with OLIVE

<Info>
  The POS API enables Smart PAY terminals to accept payments using OLIVE NFC cards. It provides endpoints for card verification, payment processing, and refunds.
</Info>

<Warning>
  POS endpoints do not use `Authorization: Bearer ...`. They require HMAC headers: `X-API-Key-ID`, `X-Timestamp`, and `X-Signature`.
</Warning>

## Features

<CardGroup cols={2}>
  <Card title="Card Verification" icon="check-circle">
    Instantly verify card status and balance before purchase
  </Card>

  <Card title="NFC Payments" icon="wifi">
    Process secure offline-first or online NFC transactions
  </Card>

  <Card title="Smart Routing" icon="route">
    Route transactions to correct subscriber wallet
  </Card>

  <Card title="Refunds" icon="rotate-ccw">
    Process full or partial refunds directly from terminal
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Process Payment" icon="credit-card" href="/api-reference/pos/payment">
    `POST /api/v1/pos/payment`

    Execute a payment transaction
  </Card>

  <Card title="Verify Card" icon="search" href="/api-reference/pos/verify-card">
    `POST /api/v1/pos/verify-card`

    Check card validity, holder name, and balance
  </Card>

  <Card title="Refund" icon="undo" href="/api-reference/pos/refund">
    `POST /api/v1/pos/refund`

    Refund a transaction
  </Card>

  <Card title="Lookup Card" icon="info" href="/api-reference/pos/lookup-card">
    `POST /api/v1/pos/lookup-card`

    Get card details (Admin/Support)
  </Card>
</CardGroup>

***

## Payment Flow

<Steps>
  <Step title="Tap Card">
    Customer taps NFC card on Smart PAY terminal
  </Step>

  <Step title="Verify">
    Terminal calls `verify-card` to check status and prompt for PIN
  </Step>

  <Step title="Authorize">
    Customer enters PIN on terminal
  </Step>

  <Step title="Process">
    Terminal calls `payment` with encrypted PIN and amount
  </Step>

  <Step title="Receipt">
    Transaction approved, terminal prints receipt
  </Step>
</Steps>

***

## Security

* **HMAC auth**: Every POS request must include `X-API-Key-ID`, `X-Timestamp`, and `X-Signature`.
* **Signature input**: Sign `METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY` using the integration's HMAC secret.
* **Merchant ID**: Include the registered merchant identifier in payment requests.
* **Processor ID**: Include the processor account ID that receives POS funds.

***

## Integration Status

<CardGroup cols={3}>
  <Card title="Online" icon="wifi" color="#10b981">
    Real-time processing
  </Card>

  <Card title="Offline" icon="wifi-off" color="#f59e0b">
    Store and forward (coming soon)
  </Card>

  <Card title="Sandbox" icon="box" color="#6366f1">
    Test environment available
  </Card>
</CardGroup>