Порядок интеграции виджета

В этом разделе описан типовой порядок интеграции платежного виджета HighHelp (H2C) на стороне мерчанта.

Общие сведения о виджете и его назначении приведены в разделе Обзор виджета. Интернет-платежи через виджет описаны в разделе Интернет-платежи через виджет. Аутентификация запросов к API описана в разделе Аутентификация и подпись.

Краткий порядок интеграции

Типовая интеграция виджета включает следующие шаги:

  1. Настроить доступ и тестовое окружение.

  2. Выбрать сценарии использования виджета и поддерживаемые методы.

  3. Реализовать на бэкенде создание заявок для виджета.

  4. Реализовать обработку оповещений от HighHelp.

  5. Встроить виджет во фронтенд (страницы мерчанта).

  6. Проверить сценарии в тестовом окружении.

  7. Перенести интеграцию в продуктивное окружение.

В следующих разделах каждый шаг описан подробнее.

Шаг 1. Подготовка доступа и окружения

Перед интеграцией виджета необходимо:

  • получить доступ в кабинет мерчанта и создать кассу;

  • сгенерировать пару ключей RSA для подписи запросов (private/public);

  • настроить тестовое окружение;

  • убедиться, что бэкенд мерчанта может отправлять HTTPS-запросы к API HighHelp.

Рекомендуется последовательно выполнить инструкции из разделов:

Для выполнения первого тестового платежа можно использовать раздел Быстрый старт.

Шаг 2. Выбор сценариев и методов

На этом шаге определяется, какие сценарии будут реализованы через виджет:

  • Интернет-платежи за товары и услуги (ECOM).

  • P2P-переводы через виджет (при наличии соответствующих продуктов и географий).

  • Дополнительные сценарии, если они поддерживаются настройками кассы.

Рекомендуется:

  • ознакомиться с поддерживаемыми методами платежной страницы в разделе Методы виджета;

  • проверить коды валют и стран, которые планируется использовать:

  • уточнить, какие методы и географии доступны для вашей кассы в кабинете мерчанта.

Интернет-платежи через виджет описаны в разделе Интернет-платежи через виджет. Дополнительные требования могут быть указаны в продуктовых разделах, например, для P2P через виджет по отдельным странам.

Шаг 3. Реализация создания заявок на бэкенде

Бэкенд мерчанта отвечает за создание платежных заявок, которые обрабатываются через виджет.

Общий подход:

  1. Бэкенд принимает запрос от фронтенда (например, от страницы оформления заказа).

  2. Бэкенд формирует запрос в API HighHelp от имени кассы.

  3. HighHelp создает заявку и возвращает данные, необходимые для инициализации виджета или отслеживания статуса.

  4. Бэкенд возвращает фронтенду идентификаторы и параметры, которые будут использованы при запуске виджета.

Основные требования:

  • Все запросы к API HighHelp должны быть аутентифицированы согласно разделу Аутентификация и подпись.

  • В блоке general обязательно указывать project_id и payment_id.

  • В блоке payment указывать сумму, валюту и метод платежной страницы (widget_method), поддерживаемый виджетом.

  • Для корректной обработки оповещений указывать merchant_callback_url, merchant_success_callback_url и merchant_decline_callback_url.

Подробный формат запросов для интернет-платежей через виджет приведен в разделе Интернет-платежи через виджет.

Шаг 4. Обработка оповещений на бэкенде

HighHelp отправляет HTTP-оповещения при изменении статуса заявки. Бэкенд мерчанта должен уметь:

  • принимать HTTP-запросы POST с телом JSON;

  • проверять цифровую подпись оповещений;

  • обрабатывать повторные оповещения;

  • обновлять состояние заказа в собственной системе.

Рекомендуется:

  • предусмотреть отдельные URL для:

    • информативных оповещений (merchant_callback_url), если они используются в выбранном сценарии;

    • успешных оповещений (merchant_success_callback_url);

    • неуспешных оповещений (merchant_decline_callback_url);

  • использовать ключ идемпотентности вида {project_id}:{payment_id}:{status}:{sub_status} для защиты от повторной обработки;

  • логировать все входящие оповещения.

Структура оповещений и примеры JSON описаны в разделе Оповещения виджета. Общие принципы обработки оповещений и статусов также рассматриваются в разделе Оповещения (H2H). Коды статусов и подстатусов приведены в разделе Коды статусов.

Шаг 5. Встраивание виджета во фронтенд

Фронтенд мерчанта отвечает за отображение платежной формы (виджета) плательщику.

Типовая схема:

  1. Страница фронтенда отправляет запрос к бэкенду для создания заявки.

  2. Бэкенд создает заявку в API HighHelp и возвращает фронтенду идентификаторы и параметры для инициализации виджета.

  3. Фронтенд загружает скрипт виджета (по инструкции из кабинета или из примера).

  4. Фронтенд вызывает функцию инициализации виджета, передавая параметры (идентификатор заявки, токен или другие данные).

  5. Виджет отображает платежную форму и управляет вводом реквизитов.

  6. По завершении операции виджет отображает результат плательщику (успех, отказ, ошибка), а бэкенд получает оповещение.

Рекомендуется:

  • размещать виджет на странице, доступной по HTTPS;

  • предусмотреть контейнер для виджета (например, отдельный блок с фиксированной шириной);

  • отображать состояние загрузки, если виджет инициализируется асинхронно;

  • обрабатывать сценарий, когда виджет не может быть загружен (ошибка сети, блокировка скриптов и т.п.).

Конкретный пример JavaScript-кода для подключения и инициализации виджета доступен в примерах интеграции.

Шаг 6. Тестирование в тестовом окружении

После реализации бэкенда и фронтенда необходимо протестировать интеграцию в тестовом окружении.

Рекомендуется:

  • использовать тестовые URL и реквизиты;

  • проверить следующие сценарии:

    • успешный платеж через виджет;

    • отказ по инициативе клиента;

    • отказ по причине ошибки или антифрода (если предоставлены тестовые сценарии);

    • корректная обработка информативных оповещений;

    • корректная обработка успешных и неуспешных оповещений;

  • сравнивать статусы и подстатусы из ответов и оповещений с описаниями в разделе Коды статусов.

При необходимости можно использовать методы …​/info для явной проверки статуса заявки, описанные в профильных разделах по продуктам.

Шаг 7. Перенос интеграции в продуктивное окружение

После успешного тестирования:

  • переключите базовые URL API и виджета на продуктивное окружение;

  • используйте ключи и кассу, предназначенные для продуктивной среды;

  • убедитесь, что оповещения отправляются на продуктивные URL merchant_callback_url, merchant_success_callback_url и merchant_decline_callback_url;

  • включите в системе мониторинг ошибок и логирование запросов к API и оповещений.

Рекомендуется дополнительно:

  • настроить алерты по ключевым ошибкам и отказам;

  • документировать внутренний процесс обработки статусов success и decline для команды разработки и поддержки.

Следующие шаги

Для углубления интеграции и настройки отдельных сценариев: