Перейти к основному содержимому

Авторизация и подпись

Базовый адрес и формат​

  • Endpoint: https://api.cobrex.com
  • Формат: запрос и ответ — JSON (Content-Type: application/json там, где есть тело).
  • Ключи: создаются в настройках панели.

HTTP-статусы​

ДиапазонСмысл
200Успешная обработка (в документации Cobrex успех обычно кодируется 200).
4xxОшибка на стороне клиента: подпись, параметры, права, «не найдено».
5xxОшибка сервера; при необходимости повторите запрос позже.

Обязательные заголовки​

Каждый защищённый запрос должен содержать:

1. x-uid или x-mid​

  • x-uid — идентификатор пользователя (u-…). Используйте для операций от лица аккаунта.
  • x-mid — идентификатор мерчанта (m-…). Используйте, когда работаете в контексте мерчанта (например выплата со счёта, привязанного к мерчанту).

Передавайте ровно один из заголовков в зависимости от сценария.

2. x-timestamp​

Текущее время в виде целого числа секунд с 1 января 1970 UTC (Unix time). Нужно, чтобы снизить риск replay-атак: сервер может отклонять слишком старые или «из будущего» метки.

const timestampSec = Math.floor(Date.now() / 1000);

Важно: не используйте Date.now() без деления — это миллисекунды и не совпадёт с ожидаемой подписью.

3. x-signature​

Шестнадцатеричная HMAC-SHA256 подпись канонической строки (см. ниже), вычисленная с вашим API secret.

Как собрать строку для подписи (пошагово)​

  1. Полный URL запроса — как вы реально вызываете API:
    https + :// + хост + путь + query string (если есть).
    Порядок параметров в query должен совпадать с отправляемым запросом.
  2. Символ перевода строки LF \n.
  3. Строка с числом секунд — точно то же значение, что уйдёт в заголовок x-timestamp.
  4. Если у запроса есть тело (например JSON в POST):
    • снова \n;
    • сырое тело — тот же байтовый текст, что отправляете в теле HTTP (после JSON.stringify или эквивалента).
      Пробелы, порядок ключей и кодировка должны совпасть с реальным телом.

Если тела нет (типичный GET): после пункта 3 останавливайтесь. Не добавляйте второй \n «на пустое тело».

Пример для POST​

Каноническая строка (визуально три блока, разделённые \n):

https://api.cobrex.com/wallet
1752675847
{"asset":["USDT","TRX"],"network":"TRON","client":"test1","callback":"https://api.cobrex.com/webhook"}

Пример для GET​

https://api.cobrex.com/payment/p-1a9a67a1-46ce-11f1-8b35-7cc255316480
1752675847

Как получить hex-подпись в коде​

Логика эквивалентна привычной записи с CryptoJS, но без привязки к Postman:

  1. Соберите canonicalString, как в разделе выше.
  2. Вычислите HMAC-SHA256 от canonicalString с ключом API secret.
  3. Преобразуйте результат в hex (нижний регистр — обычная практика для сравнения).

Пример на Node.js (встроенный модуль crypto):

const crypto = require('crypto');

function cobrexRequestSignature(canonicalString, apiSecret) {
  return crypto.createHmac('sha256', apiSecret).update(canonicalString).digest('hex');
}

В браузере или другом окружении используйте любую проверенную реализацию HMAC-SHA256 с тем же входом и ключом; результат должен совпасть побайтово с серверной проверкой при идентичной канонической строке.

Типичные ошибки​

ПроблемаПоследствие
Миллисекунды вместо секунд в x-timestampПодпись не совпадёт.
Другой порядок полей в JSON или другое форматированиеТело другое → другая подпись. Сериализуйте один раз и используйте ту же строку и в теле, и в подписи.
URL без query или с другим порядком параметровКаноническая строка отличается от серверной.
Лишний \n в конце при отсутствии телаПодпись не совпадёт.

Webhooks: как проверить входящий запрос​

Cobrex вызывает ваш URL при смене статуса платежа или выплаты. Тело — JSON (объект платежа или объект выплаты).

Способ A — allowlist IP​

Разрешайте запросы только с IP Cobrex:

46.166.162.83

(При изменении инфраструктуры список может обновляться — уточняйте в поддержке при продакшене.)

Способ B — подпись x-signature​

На вашей стороне:

  1. Прочитайте сырое тело HTTP как текст/буфер до парсинга JSON (важно для идентичности байтов).

  2. Распарсьте JSON в объект data для бизнес-логики.

  3. Вычислите ожидаемую подпись по правилу Cobrex для тела вебхука:

    x-signature (ожидаемая) = HMAC-SHA256( JSON.stringify(data), api_secret ).toString('hex')

    Здесь data — распарсенный из тела JSON-объект, api_secret — секрет из панели (если для вебхуков выдан отдельный ключ — используйте его; уточните в поддержке).

    Важно: JSON.stringify должен дать ту же строку, что лежит в основе подписи на стороне Cobrex. Поэтому для первичной проверки часто сравнивают подпись не с повторной сериализацией, а вычисляют HMAC от сырого тела как строки:

    const crypto = require('crypto');
    const expected = crypto.createHmac('sha256', apiSecret).update(rawBodyString).digest('hex');

    Если оба подхода согласованы с сервером Cobrex, результат совпадёт; при расхождении опирайтесь на сырое тело, чтобы не зависеть от порядка ключей при парсинге.

  4. Сравните ожидаемый hex с заголовком x-signature функцией сравнения постоянного времени (constant-time), чтобы снизить риск атак по времени.

Дальше: список счетов и балансы, платежи, выплаты.