Авторизация и HMAC

Каждый запрос к /api/v1/integration/* (кроме GET /health) должен быть подписан.

Что нужно

Параметр	Где	Комментарий
API Key	заголовок `X-Api-Key`	публичный идентификатор ключа
API Secret	только на вашем сервере	пароль для HMAC; не в мобильном/фронтенде
Подпись	заголовок `X-Signature`	lowercase hex HMAC-SHA256

Рекомендуемый режим: HMAC v2.

HMAC v2 (рекомендуется)

Заголовки

Заголовок	Пример	Обязателен
`X-Api-Key`	`mk_...`	да
`X-Timestamp`	`1710000000`	да (Unix seconds)
`X-Request-Id`	UUID	да, уникальный на каждый запрос
`X-Signature-Version`	`v2`	да
`X-Signature`	hex	да
`Content-Type`	`application/json`	для запросов с телом
`Idempotency-Key`	свой ключ	для возвратов и части create в v2

X-Timestamp принимается в окне примерно ±300 секунд от серверного времени.
X-Request-Id нельзя повторять (anti-replay, окно около 10 минут).

Как собрать подпись

Возьмите сырое тело запроса ровно как отправите (для GET/HEAD тело = пустая строка).

Посчитайте bodyHash = SHA256(rawBody) → hex.

Соберите path как path info без query (например /api/v1/integration/transactions).

Соберите canonical query:

нет query → пустая строка;

иначе отсортируйте ключи (SORT_STRING), для каждого:

скаляр: rawurlencode(key)=rawurlencode(value);

массив: value = json_encode(..., JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES), затем rawurlencode;

склейте через &.

Соберите canonical string из шести строк, разделённых \n:

METHOD
path
canonicalQuery
requestId
timestamp
bodyHash

METHOD — в верхнем регистре (POST, GET, …).

Подпись:

X-Signature = HMAC_SHA256(apiSecret, canonicalString)  → lowercase hex

Пример (псевдокод)

METHOD = POST
path = /api/v1/integration/transactions
canonicalQuery =            # пусто, если query нет
requestId = 550e8400-e29b-41d4-a716-446655440000
timestamp = 1710000000
rawBody = {"amount":10000,"currency":"RUB",...}
bodyHash = sha256(rawBody)

canonical =
POST
/api/v1/integration/transactions

550e8400-e29b-41d4-a716-446655440000
1710000000
<bodyHash>

signature = hmac_sha256_hex(apiSecret, canonical)

Частые ошибки 401

Симптом	Что проверить
Invalid signature	path с query / другой body / другой порядок JSON / не тот secret
Timestamp skew	синхронизация часов сервера (NTP)
Request id already used	генерируйте новый `X-Request-Id` на каждый HTTP-вызов
HMAC v2 required	добавьте `X-Signature-Version: v2` и `X-Request-Id`

HMAC v1 (устаревший)

Использовать только если платформа явно ещё принимает v1 для вашего ключа.
В production часто включено требование v2.

Заголовки

X-Api-Key, X-Timestamp, X-Signature
(без X-Signature-Version и без обязательного X-Request-Id)

Canonical string (4 строки)

timestamp
METHOD
path
sha256(rawBody)

Подпись: HMAC_SHA256(apiSecret, canonical) → hex.

Практика безопасности

Храните secret только на backend (KMS / secrets manager / env).

Не логируйте secret и полный X-Signature вместе с телом.

Ротируйте ключи при утечке.

Для мерчанта может быть включён IP allowlist — добавляйте egress IP ваших серверов.

Что нужно#

HMAC v2 (рекомендуется)#

Заголовки#

Как собрать подпись#

Пример (псевдокод)#

Частые ошибки 401#

HMAC v1 (устаревший)#

Заголовки#

Canonical string (4 строки)#

Практика безопасности#

Что нужно

HMAC v2 (рекомендуется)

Заголовки

Как собрать подпись

Пример (псевдокод)

Частые ошибки 401

HMAC v1 (устаревший)

Заголовки

Canonical string (4 строки)

Практика безопасности