Verify Card

POST/pos/verify-cardOpen in the API playground →

Info

Used before a transaction to verify the card and fetch the holder name and current balance.

Request

X-API-Key-IDstringheaderrequired

API key ID assigned to the POS integration

X-Timestampstringheaderrequired

RFC3339 timestamp used in the HMAC signature

X-Signaturestringheaderrequired

Hex-encoded HMAC-SHA256 of the request

Body Parameters

card_serialstringbodyrequired

Card serial number

pinstringbodyrequired

Cardholder 4-digit PIN

---

Response

successboolean

Whether verification succeeded

messagestring

Verification result message

is_activeboolean

Whether the card is active

balancestring

Formatted available balance

holder_namestring

Card holder display name

---

Examples

Request

cURL

BODY='{"card_serial":"OLIV0001","pin":"1234"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/pos/verify-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/pos/verify-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 Valid

{
  "success": true,
  "message": "Card verified successfully",
  "is_active": true,
  "balance": "48,500.00 SLE",
  "holder_name": "John Doe"
}

400 Invalid

{
  "success": false,
  "error": "Invalid PIN"
}

---

Use Cases

Pre-Auth

Check card before entering amount

Identity

Verify card holder name matches id

---

Errors

Status	Code	Description
400	Validation or business error	Invalid payload, unknown card, blocked card, or bad PIN
401	HMAC auth error	Missing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
500	Internal error	Server error