Lookup Card

POST/payment/lookup-cardOpen in the API playground →

Info

Administrative endpoint to resolve a card serial or MAC address to a subscriber.

Request

X-API-Key-IDstringheaderrequired

API key ID assigned to the integration

X-Timestampstringheaderrequired

RFC3339 timestamp used in the HMAC signature

X-Signaturestringheaderrequired

Hex-encoded HMAC-SHA256 of the request

Body Parameters

card_identifierstringbodyrequired

Card Serial OR MAC Address

---

Response

successboolean

Whether lookup succeeded

messagestring

Lookup result message

card_serialstring

Card serial returned by the lookup

card_typestring

Card type

statusstring

Card status

holder_namestring

Linked subscriber name

holder_phonestring

Linked subscriber phone number

balancestring

Formatted balance

---

Examples

Request

cURL - Serial

BODY='{"card_identifier":"OLIV0001"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/payment/lookup-card\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SMARTPAY_HMAC_SECRET" -hex | sed 's/^.* //')

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

cURL - MAC

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

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

Response

200 Found

{
  "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"
}

---

Errors

Status	Code	Description
400	Validation error	Invalid payload
401	HMAC auth error	Missing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
404	Not found	Card not found
500	Internal error	Server error