Пример интеграции на JavaScript

Пример интеграции с платежным шлюзом HighHelp на основе Node.js. Демонстрируется H2H-интеграция с формированием подписи запросов по алгоритму RSA-SHA256, вызовами API для управления платежами и выплатами, а также обработкой оповещений.

В примере также присутствуют вспомогательные модули для реализации подписи по алгоритму HMAC-SHA512 для запросов и оповещений.

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

Требования

  • Node.js версии 18 и выше

  • npm версии 9 и выше

Пример проверен на указанных версиях. При использовании других версий корректность работы не гарантируется.

Установка

Загрузка примера

  1. Загрузите архив с примером: js_example.zip.

  2. Распакуйте архив.

  3. Откройте терминал в директории примера.

Установка зависимостей

Выполните команду:

npm install

Настройка параметров

Откройте файл config.js и укажите:

  • projectId — идентификатор кассы (доступен в личном кабинете мерчанта: Кассы → ID);

  • callbackUrl — URL для получения оповещений от HighHelp.

Настройка ключей для подписи запросов

Для подписи запросов к API в базовых скриптах примера используется приватный ключ RSA по алгоритму RSA-SHA256.

Выполните шаги:

  1. Сгенерируйте RSA-ключи в личном кабинете мерчанта, как описано в разделе Аутентификация и подпись запросов (RSA).

  2. Сохраните приватный ключ в файл private_key_for_api.pem в корне директории примера.

В примере присутствует модуль helper_hmac.js, реализующий подпись запросов по алгоритму HMAC-SHA512. Если для вашей кассы включен режим HMAC, реализуйте подпись по правилам из раздела Аутентификация и подпись запросов (HMAC) с использованием этого модуля. В режиме HMAC заголовок x-access-token содержит маску HMAC-ключа.

Состав примера

  • config.js — параметры интеграции (идентификатор кассы, URL оповещений и базовый URL API);

  • helper.js — функции для формирования подписи запросов по алгоритму RSA-SHA256;

  • helper_hmac.js — функции для формирования подписи запросов по алгоритму HMAC-SHA512;

  • hmac_sign_callback.js — функции для проверки подписи оповещений по алгоритму HMAC-SHA512;

  • banks_get.js — получение списка банков;

  • payment_create.js — создание заявки на оплату;

  • payment_get_info.js — получение статуса платежа;

  • payout_create.js — создание заявки на выплату;

  • payout_get_info.js — получение статуса выплаты;

  • callback_processor.js — обработка и валидация оповещений.

Каждый скрипт выполняет:

  • формирование заголовков аутентификации x-access-*;

  • создание подписи запроса (по RSA-SHA256, при необходимости — по HMAC-SHA512);

  • отправку HTTP-запроса к API;

  • обработку ответа и вывод результата.

Запуск примеров

Выполнение операций API

Запустите необходимый скрипт. Примеры:

node banks_get.js
node payment_create.js

Скрипт отправляет запрос к API и выводит результат в терминал.

Результат выполнения

При успешном выполнении скрипт выводит:

  • сформированное тело запроса;

  • ответ сервера.

При ошибке выводится информация об ошибке, возвращенной API или логикой формирования подписи.

Обработка оповещений

Настройка ключей для проверки подписи оповещений

Для проверки подписи оповещений от HighHelp в примере используются:

  • публичный RSA-ключ — при подписи оповещений по алгоритму RSA-SHA256;

  • HMAC-ключ — при подписи оповещений по алгоритму HMAC-SHA512.

Выполните шаги:

  1. Откройте личный кабинет мерчанта.

  2. Перейдите в раздел API → Настройки Callback.

    • В открывшемся модальном окне внизу отображается строка: Текущий алгоритм: RSA или Текущий алгоритм: HMAC.

    • При текущем алгоритме RSA отображаются блоки Public Key и HMAC key. Для проверки подписи оповещений используйте Public Key.

    • При текущем алгоритме HMAC отображается блок HMAC key, блок Public Key не отображается.

  3. Сохраните ключ:

    • для RSA нажмите на иконку скачивания в блоке Public Key и сохраните файл в корень директории примера;

    • для HMAC сохраните секретный HMAC-ключ в момент генерации или обновления в блоке HMAC key.

  4. Убедитесь, что путь и имя файла соответствуют ожидаемым значениям в callback_processor.js (при необходимости измените настройки в скрипте).

При настроенном алгоритме RSA в блоке HMAC key доступна генерация ключа, если он не был сгенерирован ранее. Секретный HMAC-ключ доступен для скачивания только в момент генерации или обновления. После скачивания в разделе API → Настройки Callback отображается маскированное значение ключа; повторное скачивание недоступно, доступно только обновление ключа.

Если требуется сменить алгоритм подписи, обратитесь к вашему менеджеру HighHelp.

Описание формата подписи оповещений и алгоритмов проверки приведено разделах Подпись оповещений (RSA) и Подпись оповещений (HMAC).

Запуск обработчика

Запустите сервис обработки оповещений:

node callback_processor.js

Параметры сервиса:

  • порт: 8000;

  • endpoint: /callback/{status}.

Сервис принимает HTTP-запросы с оповещениями, валидирует цифровую подпись (RSA или HMAC в зависимости от конфигурации) и выводит результат проверки в терминал.

При корректной подписи выводится сообщение:

Signature is valid

Дополнительная информация