Пример интеграции на 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.

    // Конфигурация примера. Замените значения `projectId` и `callbackUrl` на параметры вашей интеграции.
export const privateKeyFilePath = './private_key_for_api.pem'; // Путь к приватному ключу для подписи запросов в API.
export const publicKeyFilePath = './public_key_for_callbacks.pem'; // Путь к публичному ключу для проверки подписи callback-запросов.
export const baseUrl = 'https://api.hh-processing.com'; // Базовый URL HighHelp API.

export const projectId = '<PROJECT_ID>'; // Идентификатор кассы.
export const callbackUrl = 'https://example.com'; // Базовый URL callback-эндпоинтов мерчанта.

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

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

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

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

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

В примере присутствует модуль helper_hmac.js, реализующий подпись запросов по алгоритму HMAC-SHA512. Если для вашей кассы включен режим HMAC, реализуйте подпись по правилам из раздела Аутентификация и подпись запросов (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.

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

  4. В зависимости от настроенного алгоритма:

    • для RSA отображается блок Public Key;

    • для HMAC отображается блок HMAC key.

  5. Нажмите на иконку скачивания и сохраните файл с ключом в корень директории примера.

  6. Убедитесь, что путь и имя файла соответствуют ожидаемым значениям в 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

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