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

Project API позволяет вашему бэкенд-серверу программно создавать платёжные заказы, проверять их статус и выполнять выводы средств. Все запросы аутентифицируются парой ключ/секрет и HMAC-подписью запроса.

Получение API-ключей

1. Войдите в CryptumPay Console
2. Откройте ваш проект
3. Перейдите в Интеграция и API
4. Нажмите Получить API-ключи
5. Опционально добавьте IP-адреса в whitelist — это обязательно, если планируете использовать эндпоинты вывода средств (см. IP Whitelist ниже)

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

API-секрет показывается только один раз при генерации. Храните его надёжно (например, в переменных окружения). Никогда не коммитьте его в систему контроля версий.

Требование HTTPS

Домены вашего проекта должны быть настроены с валидным HTTPS. Запросы с доменов только на HTTP будут отклонены с ошибкой 3002. Это применяется как к домену вашего сайта, зарегистрированному в консоли, так и к URL вебхука.

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

Каждый запрос к API должен содержать следующие заголовки:

Заголовок	Описание
x-api-key	Ваш API-ключ
x-signature	HMAC-подпись запроса (см. алгоритм ниже)
x-timestamp	Текущий Unix-timestamp в миллисекундах (например, Date.now())
Content-Type	Должен быть application/json

Алгоритм подписи

Сервер верифицирует каждый запрос, пересчитывая подпись из содержимого запроса. Запросы старше 1 минуты автоматически отклоняются вне зависимости от валидности подписи.

Пошагово (независимо от языка)

1. Сериализуйте тело запроса Для POST-запросов: body = JSON.stringify(params) Для GET-запросов: body = "{}"

2. Хешируйте телоbodyHash = hex(SHA-256(body))

3. Нормализуйте путь

   • Добавьте / в начало, если отсутствует
   • Уберите завершающий /, если присутствует Пример: orders/ → /orders

4. Сформируйте строку для подписи

   prehash = bodyHash + "|" + METHOD + "|" + path + "|" + timestamp + "|" + apiKey

   Где METHOD — HTTP-метод в верхнем регистре (GET, POST и т.д.)

5. Вычислите подписьsignature = hex(HMAC-SHA256(prehash, secret))

6. Установите заголовки

   x-api-key: <apiKey>
   x-signature: <signature>
   x-timestamp: <timestamp>

Пример: Node.js SDK

Самый простой путь — использовать официальный SDK, который подписывает запросы автоматически:

npm install @cryptumpay/node-sdk

import { CryptumPayClient, CryptumPaySigner } from '@cryptumpay/node-sdk';

const client = new CryptumPayClient(
  new CryptumPaySigner(
    process.env.CRYPTUMPAY_API_KEY,
    process.env.CRYPTUMPAY_API_SECRET
  )
);

// Все методы подписывают запросы автоматически
const response = await client.createOrder({ ... });

IP Whitelist

Эндпоинты вывода средств (POST /v1/withdraw и GET /v1/withdraw/:id) дополнительно проверяют IP-адрес запроса.

• Если для API-ключа не настроен IP-whitelist, запросы на вывод будут отклонены с ошибкой 8002
• Настройте whitelist в консоли при генерации или редактировании API-ключа

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

Все API-ответы используют единый формат:

{
  "data": { ... },
  "errorObject": null
}

В случае ошибки data равен null, а errorObject заполнен:

{
  "data": null,
  "errorObject": {
    "httpCode": 401,
    "appCode": 7005,
    "message": "Invalid signature"
  }
}

Справочник ошибок

Ошибки аутентификации и middleware

HTTP	appCode	Описание	Как исправить
401	7000	Отсутствует один или несколько обязательных заголовков (x-api-key, x-signature, x-timestamp)	Добавьте все три заголовка в запрос
401	7001	API-ключ не найден или отозван	Проверьте значение x-api-key
401	7002	Внутренняя ошибка аутентификации	Обратитесь в поддержку
401	7003	IP запроса не в whitelist	Добавьте IP-адрес сервера в консоли
401	7004	Timestamp отличается от времени сервера более чем на 1 минуту	Убедитесь в синхронизации часов сервера (NTP)
401	7005	Вычисленная подпись не совпадает	Проверьте алгоритм подписи, особенно сериализацию тела и нормализацию пути
403	8002	У API-ключа не настроен IP-whitelist; выводы заблокированы	Добавьте хотя бы один IP-адрес в whitelist в консоли

Смотрите также

• API Эндпоинты — доступные эндпоинты и форматы запросов/ответов
• Webhooks & Redirects — получение уведомлений о платежах