Skip to main content
POST
/
api
/
v1
/
payment
/
lookup-card
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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/payment/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"
{
  "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"
}
Administrative endpoint to resolve a card serial or MAC address to a subscriber.

Request

X-API-Key-ID
string
required
API key ID assigned to the integration
X-Timestamp
string
required
RFC3339 timestamp used in the HMAC signature
X-Signature
string
required
Hex-encoded HMAC-SHA256 of the request

Body Parameters

card_identifier
string
required
Card Serial OR MAC Address

Response

success
boolean
Whether lookup succeeded
message
string
Lookup result message
card_serial
string
Card serial returned by the lookup
card_type
string
Card type
status
string
Card status
holder_name
string
Linked subscriber name
holder_phone
string
Linked subscriber phone number
balance
string
Formatted balance

Examples

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 "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/payment/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"
{
  "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

StatusCodeDescription
400Validation errorInvalid payload
401HMAC auth errorMissing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
404Not foundCard not found
500Internal errorServer error

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Key-ID
string
required

API key ID assigned to the integration

X-Timestamp
string
required

RFC3339 timestamp used in the HMAC signature

X-Signature
string
required

Hex-encoded HMAC-SHA256 of the request

Body

application/json
card_identifier
string
required

Card Serial OR MAC Address

Response

200 - application/json

Response 200

success
boolean

Whether lookup succeeded

message
string

Lookup result message

card_serial
string

Card serial returned by the lookup

card_type
string

Card type

status
string

Card status

holder_name
string

Linked subscriber name

holder_phone
string

Linked subscriber phone number

balance
string

Formatted balance