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

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

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

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

Требования

  • Python версии 3.10 и выше

  • pip

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

Установка

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

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

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

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

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

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

pip install -r requirements.txt

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

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

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

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

    import os
base_dir = os.path.dirname(os.path.abspath(__file__))

# Конфигурация примера. Замените значения `project_id` и `callback_url` на параметры вашей интеграции.
private_key_file_path = os.path.join(base_dir, './private_key_for_api.pem')  # Путь к приватному ключу для подписи запросов в API.
public_key_file_path = os.path.join(base_dir, './public_key_for_callbacks.pem')  # Путь к публичному ключу для проверки подписи callback-запросов.
base_url = 'https://api.hh-processing.com'  # Базовый URL HighHelp API.

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

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

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

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

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

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

Если для вашей кассы включен режим HMAC, реализуйте подпись по правилам из раздела Аутентификация и подпись запросов (HMAC).

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

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

  • requirements.txt — зависимости Python;

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

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

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

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

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

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

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

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

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

  • создание подписи запроса (по RSA-SHA256);

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

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

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

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

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

python banks_get.py
python payment_create.py

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

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

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

  • HTTP-код ответа;

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

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

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

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

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

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

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

В примере реализована проверка подписи по алгоритму RSA-SHA256.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

python callback_processor.py

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

  • порт: 8000;

  • endpoint: /callback.

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

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

Signature is valid

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