Обзор интернет-платежей через виджет

В этом разделе описан сценарий интернет-платежей (ECOM) через платежный виджет HighHelp. Виджет используется по схеме H2C (host-to-client): платежная форма отрисовывается на стороне HighHelp, а на стороне мерчанта реализуется встраивание виджета и обработка результатов.

Определения основных сущностей (мерчант, плательщик, получатель, касса, виджет) см. в разделе Глоссарий. Общий обзор виджета приведен в разделе Обзор виджета. Краткое сравнение схем H2H и H2C описано в разделе Обзор ECOM H2H.

Когда использовать виджет для ECOM

Интернет-платежи через виджет рекомендуется использовать в следующих случаях:

  • Требуется принимать платежи за товары и услуги в веб-приложении или мобильном веб-интерфейсе.

  • Нужна платежная форма с готовой логикой ввода реквизитов, локализацией и обработкой ошибок.

  • Мерчант не хочет обрабатывать и хранить платежные реквизиты на своей стороне.

  • Требуется сократить объем интеграции на бэкенде и сосредоточиться на бизнес-логике.

Виджет подходит для сценариев:

  • одноэтапная оплата (списание средств при создании заявки);

  • последующая обработка результата по оповещениям и через запросы к API.

Типы платежей payin и payout описаны в разделе Типы платежей. Поддерживаемые методы для виджета приведены в разделе Методы виджета.

Архитектура и роли

В сценарии интернет-платежей через виджет участвуют:

  • Браузер плательщика.

  • Фронтенд мерчанта (страница или SPA, в которую встраивается виджет).

  • Бэкенд мерчанта.

  • Платежный шлюз HighHelp (виджет и API).

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

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

  • Фронтенд мерчанта встраивает виджет (например, через <script> и контейнер для iframe или встроенного компонента).

  • Плательщик вводит данные на платежной странице (виджете HighHelp).

  • HighHelp обрабатывает платеж, при необходимости выполняет 3-D Secure или другие сценарии аутентификации.

  • HighHelp отправляет оповещения на бэкенд мерчанта и возвращает результат в интерфейс плательщика.

Аутентификация запросов от бэкенда мерчанта к API HighHelp описана в разделе Аутентификация и подпись.

Процесс обработки интернет-платежа через виджет

Ниже приведен упрощенный процесс обработки интернет-платежа через виджет. Конкретные поля и статусы зависят от метода и настроек кассы.

  1. Бэкенд мерчанта создает заявку через API.

    • Запрос выполняется от имени кассы мерчанта.

    • В запросе указывается сумма, валюта, метод платежа, идентификатор платежа и URL-адреса для оповещений.

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

  2. Бэкенд получает от API данные для инициализации виджета.

    • В ответе может возвращаться идентификатор сессии, токен или параметры конфигурации для фронтенда.

    • Эти значения передаются на фронтенд (например, через JSON-ответ из бэкенда мерчанта).

  3. Фронтенд инициализирует виджет.

    • На странице мерчанта подключается скрипт HighHelp.

    • В коде фронтенда вызывается функция инициализации виджета с параметрами, полученными от бэкенда.

    • Виджет отображает платежную форму для плательщика.

  4. Плательщик заполняет платежные данные.

    • Вводит реквизиты карты или выбирает другой метод оплаты.

    • При необходимости проходит дополнительную аутентификацию (например, 3-D Secure).

  5. HighHelp обрабатывает платеж.

    • Выполняет проверки и взаимодействует с платежными провайдерами.

    • Формирует финальный статус (success, decline, error) и промежуточные статусы (processing:*).

  6. HighHelp отправляет оповещения на бэкенд мерчанта.

    • Информативные оповещения отправляются на merchant_callback_url.

    • Успешные оповещения отправляются на merchant_success_callback_url.

    • Неуспешные оповещения отправляются на merchant_decline_callback_url.

    • Формат оповещений описан в разделе оповещения H2H. Для виджета используется тот же формат.

  7. Бэкенд мерчанта фиксирует результат операции.

    • Обновляет статус заказа или услуги.

    • Отвечает фронтенду (например, через API или веб-сокеты), чтобы отобразить результат пользователю.

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

Схема обработки интернет-платежа через виджет

flowchart TD
  U[Пользователь]
  M[Страница мерчанта с виджетом]
  W[Виджет HighHelp]
  S[Выбор метода оплаты]
  D[Ввод реквизитов и подтверждение]
  C{Требуется 3-D Secure?}
  B1[Перенаправление на страницу банка]
  B2[Прохождение аутентификации]
  B3[Возврат в виджет]
  H[Обработка заявки в API HighHelp]
  RS{Результат обработки}
  OK[Страница успешной оплаты у мерчанта]
  FAIL[Страница отказа в оплате у мерчанта]

  U --> M
  M --> W
  W --> S
  S --> D
  D --> C

  C -- Нет --> H
  C -- Да --> B1
  B1 --> B2
  B2 --> B3
  B3 --> H

  H --> RS
  RS -->|success| OK
  RS -->|decline| FAIL

Формат заявки

Состав и формат полей зависят от конкретного метода виджета и географии. В общем случае используются следующие блоки:

  • general — общая информация о заявке.

    • project_id — идентификатор кассы.

    • payment_id — идентификатор платежа в системе мерчанта.

    • merchant_callback_url — URL для информативных оповещений.

    • merchant_success_callback_url — URL для успешных оповещений.

    • merchant_decline_callback_url — URL для неуспешных оповещений.

  • payment — параметры платежа.

    • method — код метода оплаты для виджета. Список значений приведен в разделе Методы виджета.

    • amount — сумма в дробных единицах валюты.

    • currency — код валюты в формате ISO 4217 alpha-3. См. раздел Коды валют.

  • customer — информация о плательщике.

    • id — идентификатор пользователя в системе мерчанта.

    • дополнительные поля (страна, язык, контактные данные) зависят от конкретной настройки кассы и географии.

Подробный список полей и ограничения (тип, длина, обязательность) описаны в разделе Интернет-платежи через виджет.

Обработка статусов и ошибок

При работе с интернет-платежами через виджет необходимо:

  • обрабатывать финальные статусы success, decline, error;

  • учитывать промежуточные статусы (processing:*), особенно при сценариях с 3-D Secure и редиректами;

  • использовать поле status_description для диагностики ошибок и причин отказа.

Перечень статусов и подстатусов приведен в разделе Коды статусов.

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

  • реализовать логику идемпотентной обработки оповещений на бэкенде;

  • логировать все входящие оповещения и ключевые поля (project_id, payment_id, status, sub_status);

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

Требования к фронтенду

При интеграции виджета на фронтенде следует учитывать:

  • Страница должна загружаться по HTTPS.

  • Должна быть возможность выполнить JavaScript-код и вставить контейнер для виджета.

  • Необходимо обрабатывать:

    • успешное завершение платежа;

    • отказ или ошибку;

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

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

  • использовать отдельные маршруты фронтенда для страницы с виджетом и для страницы результата;

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

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

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

Для полноценной интеграции интернет-платежей через виджет: