Пример интеграции на 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 для оповещений вашего сервиса.

    <?php
// Конфигурация примера. Замените значения `$project_id` и `$callback_url` на параметры вашей интеграции.
$private_key_file_path = './private_key_for_api.pem';       // Путь к приватному ключу для подписи запросов в API.
$public_key_file_path = './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 в корне директории примера.

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

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

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

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

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

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

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

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