Security

Server-to-server calls to POST /sdk/server/create-payment use three coordinated mechanisms:

1. API key and secret — identifies the merchant and loads access-token verification.

2. HMAC request signature — proves possession of the secret and binds the request to method, path, time, and body.

3. Idempotency key — prevents accidental duplicate payments when clients retry.

All three are mandatory for the create-payment endpoint.

---

API key and secret

Where to send credentials

Credential	Header
API key	Authorization: Bearer <apiKey> or X-API-Key: <apiKey>
Secret	X-Secret-Key: <secretKey>

The server looks up an access token record matching both apiKey and secretKey. The record must be active; otherwise the API returns 403 or 401 depending on the case.

Merchant context

After successful authentication, downstream code receives:

• MerchantId (merchant identity)

• Per-merchant rate limit budget (numeric limit on the token, used by the per-key limiter)

---

Signature headers (required after auth)

Signing is enforced by dedicated middleware. In addition to credentials, you must send:

Header	Purpose
X-API-Key	Must equal the authenticated API key (signing requires this header explicitly).
X-Timestamp	Unix seconds; must fall within a ±300 second window of server time.
X-Signature	HMAC-SHA256 of the canonical base string (see Request signing).

---

Failure modes (authentication)

Symptom	Typical cause
401 + INVALID_API_KEY	Missing header, wrong key/secret pair, or inactive token.
401 + message about X-API-Key	API key header missing or does not match authenticated key.

Repeated failed authentication attempts may be rate limited separately; see Rate limits.

---

Related pages

• Request signing (HMAC)

• Idempotency

• Create payment URL