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

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

API-ключ

Для интеграции нужен один API-ключ. Отдельного секрета нет: этим же ключом подписываются запросы.

Что	Как выглядит	Где используется
API-ключ	`live_...` (боевой) или `test_...` (песочница)	заголовок `X-Api-Key` и ключ для HMAC-подписи
Подпись	lowercase hex HMAC-SHA256	заголовок `X-Signature`

Ключ создаётся в ЛК: «Настройки → Интеграция и API».

Полный ключ показывается один раз — при создании или перевыпуске. Потом в ЛК виден только его префикс.

Потеряли ключ — перевыпустите его в ЛК и обновите на своём сервере.

Ключ хранится только на вашем backend: не передавайте его в мобильное приложение, браузер или фронтенд.

Заголовки

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

X-Timestamp принимается в окне примерно ±300 секунд от серверного времени.
X-Smerch-Request-Id нельзя повторять (anti-replay, окно около 10 минут).
Не путать с X-Request-Id: тот только для correlation в логах/ответах и не входит в подпись (прокси часто его переписывают).

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

Возьмите сырое тело запроса ровно как отправите (для 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, …).

Подпись — HMAC-SHA256, где ключ подписи — тот же API-ключ, что в X-Api-Key:

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

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

apiKey = live_AbC...            # то же значение, что в X-Api-Key
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(apiKey, canonical)

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

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

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

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

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

Перевыпускайте ключ при утечке.

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

API-ключ#

Заголовки#

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

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