ProtoPays · API
кабинет

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

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

заголовки

  • X-Merchant-Secret — ваш секрет ключа в том виде, в каком он был выдан (используется и как ключ HMAC).
  • Signature — шестнадцатеричная строка (hex), см. расчёт ниже.
  • X-Merchant-Key-Id — публичный идентификатор строки API-ключа в кабинете (обязательный заголовок).
  • 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-Secret и Signature переданы и не пустые.

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

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

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