API Docs

API терминала для мерчантов: создание и просмотр заказов, счета мерчанта, справочники.

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

Защита в два слоя:

1. mTLS — соединение устанавливается с клиентским сертификатом, который мы выдаём мерчанту при подключении. Без сертификата — 401 AUTH_MTLS_REQUIRED.
2. HMAC-подпись — каждый запрос подписывается секретным ключом мерчанта. Терминал проверяет подпись по заголовку X-Signature. Нет заголовка, подпись не совпала — 401 AUTH_HMAC_INVALID.

Формат ответа

Успешные ответы оборачиваются в конверт { data, metadata, request_id }, ошибки — в { error, request_id }. Ошибки валидации тела запроса (422) отдаются массивом ошибок полей.

Каждый ответ содержит заголовок X-Request-ID. Если клиент передал его в запросе, значение возвращается без изменений, иначе генерируется сервером.

Суммы

Суммы передаются строкой, разделитель — только точка, не более 2 знаков после неё: "1500.00". Значение с запятой ("1500,00") отклоняется.

Колбэки

При смене состояния заказа на callback_url мерчанта отправляется POST (см. webhooks.orderStateChanged). Ответ 2xx в течение 5 секунд — доставлено, иначе до 8 попыток с нарастающей задержкой (30 с … 30 мин). Ключ события — пара order_id + sequence; повторы и события с меньшим sequence игнорируйте.