🔐 Authentication Guide

To access our API, all requests must be authenticated using a valid API key and a signed HMAC signature. This ensures secure communication and verifies both your identity and request integrity.

---

✅ API Key Requirement

Before making any requests, you must obtain a unique API key and API secret. These credentials allow you to authenticate requests and generate valid signatures.

---

📡 How to Authenticate Requests

All requests to /api/v1/merchant/... must include the following headers:

x-payments-api-key: YOUR_API_KEY
x-timestamp: UNIX_TIMESTAMP
x-signature: SIGNATURE

Header	Required	Description
x-payments-api-key	✅	Your merchant API key (public)
x-timestamp	✅	Current UNIX time in seconds
x-signature	✅	HMAC SHA256 of {timestamp}{path}{body} using your API secret

---

🚫 Exception: Public iFrame Endpoint

The following endpoint does not require signature or API key authentication:

GET /api/v1/merchant/cards/pan/iframe/{token}/

This endpoint is designed for embedding card details inside a secure iFrame on the frontend. Access is protected using a time-limited token embedded in the URL.

---

🧮 How to Generate the Signature

To generate the signature, you must concatenate the following three elements in this order:

{timestamp}{request_path}{request_body}

Element	Description
timestamp	e.g. 1716752000 (must match x-timestamp)
request_path	The exact request path with trailing slash, e.g. /api/v1/merchant/cards/abc123/reveal-html/
request_body	The raw JSON string sent in the body, e.g. {} or "" if empty

Then compute the signature using HMAC SHA256:

hmac.new(api_secret, data_to_sign, hashlib.sha256).hexdigest()

⚠️ Important: JSON object field order matters. Always use a consistent ordering of keys when signing and sending the request.

---

🕒 Timestamp Rules

• Must be within ±60 seconds of server time
• Prevents replay attacks and ensures freshness

---

🧷 Common Issues

Problem	Solution
Body mismatch	Ensure body string matches exactly ({} vs "")
Field order in JSON	Always use consistent key order when signing
Signature mismatch	Compare with data_to_sign used on backend

---

✅ Example Header Block

x-payments-api-key: abc123xyz
x-timestamp: 1716751234
x-signature: 3f34d4f3e3ad1e54f7d7... (computed HMAC SHA256)

---

If you're unsure how to format a request or need help debugging a signature error, contact our support team.