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

# Lookup Card

> Get administrative details about a card

<Info>
  Administrative endpoint to resolve a card serial or MAC address to a subscriber.
</Info>

## Request

<ParamField header="X-API-Key-ID" type="string" required>
  API key ID assigned to the POS integration
</ParamField>

<ParamField header="X-Timestamp" type="string" required>
  RFC3339 timestamp used in the HMAC signature
</ParamField>

<ParamField header="X-Signature" type="string" required>
  Hex-encoded HMAC-SHA256 of the request
</ParamField>

### Body Parameters

<ParamField body="card_identifier" type="string" required>
  Card Serial OR MAC Address
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Whether lookup succeeded
</ResponseField>

<ResponseField name="message" type="string">
  Lookup result message
</ResponseField>

<ResponseField name="card_serial" type="string">
  Card serial returned by the lookup
</ResponseField>

<ResponseField name="card_type" type="string">
  Card type
</ResponseField>

<ResponseField name="status" type="string">
  Card status
</ResponseField>

<ResponseField name="holder_name" type="string">
  Linked subscriber name
</ResponseField>

<ResponseField name="holder_phone" type="string">
  Linked subscriber phone number
</ResponseField>

<ResponseField name="balance" type="string">
  Formatted balance
</ResponseField>

***

## Examples

<RequestExample>
  ```bash cURL - Serial theme={null}
  BODY='{"card_identifier":"OLIV0001"}'
  TIMESTAMP='2026-03-10T12:00:00Z'
  SIGNATURE=$(printf 'POST\n/api/v1/pos/lookup-card\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

  curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/lookup-card" \
    -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
    -H "X-Timestamp: $TIMESTAMP" \
    -H "X-Signature: $SIGNATURE" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```

  ```bash cURL - MAC theme={null}
  BODY='{"card_identifier":"AA:BB:CC:DD:EE:01"}'
  TIMESTAMP='2026-03-10T12:00:00Z'
  SIGNATURE=$(printf 'POST\n/api/v1/pos/lookup-card\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

  curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/lookup-card" \
    -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
    -H "X-Timestamp: $TIMESTAMP" \
    -H "X-Signature: $SIGNATURE" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Found theme={null}
  {
    "success": true,
    "message": "Card found",
    "card_serial": "OLIV0001",
    "card_type": "PARENT",
    "status": "ACTIVE",
    "holder_name": "John Doe",
    "holder_phone": "+23277123456",
    "balance": "48,500.00 SLE"
  }
  ```
</ResponseExample>

***

## Uses

<CardGroup cols={2}>
  <Card title="Support" icon="headset">
    Help customers find lost card details
  </Card>

  <Card title="Diagnostics" icon="activity">
    Check if MAC address matches serial
  </Card>
</CardGroup>


## OpenAPI

````yaml olive-openapi.json POST /pos/lookup-card
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths: {}

````