1. Authentication and security

General requirements

• All requests must be sent over HTTPS.
• Responses are returned in JSON format. On error, the body contains an object {"message": "..."} with a description.
• A valid API Key issued to the merchant is required for access.
• All external endpoints described below use the prefix /api/v1.

Required headers

Header	Description
X-API-Key	Integration identifier (API key) issued to the merchant.
X-Timestamp	Request time: ISO-8601 (UTC) or UNIX timestamp in seconds (UTC). Used for replay protection; allowed skew ±60 seconds.
X-Signature	Request signature (see below).
Content-Type	For requests with a body: application/json.

Request signature (X-Signature)

The signature ensures request integrity and that the request belongs to your key.

1. String to sign: timestamp + body.
   • timestamp — the value of the X-Timestamp header exactly as sent (unchanged).
   • body — raw request body (empty string for GET).
2. Algorithm: HMAC-SHA256 using the secret key (api_secret or merchant webhook secret).

Formula:

signature = HMAC_SHA256(secret, timestamp + body)

The result is sent in the X-Signature header as a string (hex or base64 depending on your specification; typically hex).

Example (pseudocode)

timestamp = "2025-12-05T10:00:00Z"
body = '{"external_id":"PAY-001","amount":1000,"currency":"RUB","card_number":"4111111111111111"}'
message = timestamp + body
signature = hmac_sha256(api_secret, message)
# Header: X-Signature: "signature"

For GET requests the body is empty: message = timestamp + "".

Authentication error responses

HTTP	Message	Cause
401	API key required	Missing X-API-Key header.
401	Invalid API key	Invalid or inactive API key.
401	Timestamp required	Missing X-Timestamp.
401	Signature required	Missing X-Signature.
401	Invalid timestamp format	Invalid time format.
401	Timestamp window exceeded	Request time outside allowed window (±60 sec).
401	Invalid signature	Signature does not match the computed value.

For other errors, see API errors.