protopays · API

аутентификация

Серверные запросы к внешнему API подписываются HMAC-SHA256. Ниже — зачем в заголовке и сырой секрет, и подпись, обязательные поля и типичный расчёт для JSON POST. Детали по конкретному методу (включая нестандартные тела) смотрите в справочнике по созданию платежа.

зачем в запросе и секрет, и signature

Signature — это HMAC-SHA256 от согласованного для метода «сообщения» (тело JSON, пустая строка для GET, каноническая строка для multipart и т.д.); ключ HMAC — тот же сырой секрет, что вы передаёте в X-Merchant-Secret. Подпись фиксирует целостность подписываемых байт. Секрет в заголовке вместе с X-Merchant-Key-Id удостоверяет запрос по выданной паре и позволяет серверу проверить HMAC. Используйте только HTTPS.

заголовки

  • X-Merchant-Key-Id — публичный идентификатор строки API-ключа в кабинете; по нему выбирается запись ключа.
  • X-Merchant-Secret — сырой секрет, как в кабинете; вместе с X-Merchant-Key-Id идентифицирует ключ, тем же значением пользуется HMAC при проверке Signature.
  • Signature — hex-строка HMAC-SHA256 от подписываемого сообщения (см. расчёт ниже и описание эндпоинта), в нижнем регистре.
  • Idempotency-Key — по желанию; не влияет на дедупликацию на сервере (см. идемпотентность).

расчёт подписи (JSON POST)

  1. Сформируйте тело запроса — JSON в UTF-8. Для подписи используйте те же байты, что отправите в теле HTTP (без изменения пробелов и порядка полей относительно отправляемого запроса).
  2. Вычислите HMAC-SHA256, где ключ — байты секрета в UTF-8, сообщение — байты тела запроса.
  3. Представьте результат как строку hex в нижнем регистре и передайте в заголовке Signature.

Для запросов без тела (например часть GET) и для специальных сценариев (апелляции и т.д.) правило формирования сообщения для HMAC может отличаться — смотрите описание конкретной операции в списке эндпоинтов.

типичные ошибки подписи и заголовков

Если подпись не совпадает с телом или секретом, сервер обычно отвечает 401 Unauthorized или 403 Forbidden. Тело ответа часто содержит поле с причиной; точный формат может обновляться — ориентируйтесь на код HTTP и текст сообщения.

Иллюстративный ответ (структура не является гарантией дословного совпадения в каждой версии API):

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "message": "Неверная подпись запроса.",
  "code": "signature_invalid"
}

Проверьте по очереди:

  • Тело для HMAC — байт в байт с отправляемым JSON (без лишнего пересериализования в другом порядке полей).
  • Кодировка UTF-8.
  • Секрет — тот же, что в кабинете; для Signature используется hex в нижнем регистре, если ваша среда по умолчанию даёт upper — приведите к нижнему.
  • Указан корректный X-Merchant-Key-Id и сырой секрет для этой строки в X-Merchant-Secret (тот, что в кабинете).
  • Заголовки X-Merchant-Key-Id, X-Merchant-Secret, Signature заданы и не пусты.

Если не хватает обязательного заголовка, возможен ответ 422 или 400 с описанием валидации — см. раздел ошибки.

где взять ключи

Ключи выдаются в личном кабинете мерчанта: раздел «шлюзы», карточка шлюзы, блок credentials для API. Перейти в кабинет