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

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

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

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

Требования

  • PHP версии 8.4.1 и выше

  • Composer версии 2.8.3 и выше

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

Установка

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

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

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

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

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

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

composer install

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

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

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

  • callback_url — URL для оповещений вашего сервиса.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • callback_processor.php — обработчик оповещений.

Каждый скрипт содержит:

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

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

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

  • обработку ответа.

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

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

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

php banks_get.php
php payment_create.php

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

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

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

  • тело запроса;

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

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

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

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

Для проверки подписи оповещений от платежного шлюза используются:

  • публичный 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.php (при необходимости измените настройки в скрипте).

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

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

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

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

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

php -S localhost:8000 callback_processor.php

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

  • порт: 8000;

  • endpoint: /callback/{status}.

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

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

Signature is valid (via OpenSSL)

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