Обзор ECOM H2H

В этом разделе описана интеграция интернет-платежей по банковским картам в формате H2H (host-to-host). При таком варианте интеграции форма оплаты и сбор реквизитов выполняются на стороне мерчанта, а платеж создается и обрабатывается через API HighHelp.

Назначение ECOM H2H

ECOM H2H используется для интернет-платежей по банковским картам, когда:

  • форма оплаты размещена на сайте или в приложении мерчанта;

  • реквизиты карты поступают на бэкенд мерчанта и передаются в платежный шлюз по API;

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

  • допустима работа с карточными данными на стороне мерчанта (требования PCI DSS).

Для ECOM H2H применяются типы платежей payin и payout. Определения типов платежей приведены в разделе Типы платежей. Список поддерживаемых методов оплаты для H2H (в том числе card-ecom) приведен в разделе Методы оплаты (H2H).

Все запросы ECOM H2H используют единый механизм аутентификации и подписи, описанный в разделе Аутентификация и подпись.

Сравнение с виджетом (H2C)

ECOM H2H отличается от интеграции через виджет (H2C) следующим:

  • При H2H:

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

    • мерчант принимает и обрабатывает данные карты;

    • запросы в платежный шлюз выполняются с бэкенда мерчанта.

  • При H2C:

    • форма оплаты отрисовывается виджетом HighHelp;

    • реквизиты карты отправляются напрямую в платежный шлюз;

    • бэкенд мерчанта получает только результат обработки.

Интеграция через виджет описана в разделе Интернет-платежи через виджет.

Поддерживаемые сценарии

В рамках ECOM H2H поддерживаются следующие базовые сценарии:

  • Оплата по карте (тип payin). Клиент вводит реквизиты карты на стороне мерчанта, мерчант создает заявку card-ecom и получает результат обработки. Средства списываются с карты клиента и зачисляются на кассу мерчанта.

  • Выплата на карту (тип payout). Мерчант создает заявку card-ecom на выплату. Средства списываются с кассы мерчанта и зачисляются на карту получателя.

Поддерживаемые валюты и особенности указания суммы в дробных единицах описаны в разделе Коды валют.

Перечень статусов и подстатусов заявок, а также соответствующие коды ошибок приведены в разделе Коды статусов.

Общий процесс обработки ECOM H2H

Общий процесс обработки ECOM H2H-платежа включает следующие этапы:

  1. Формирование запроса на стороне мерчанта.

    1. Мерчант собирает данные клиента и реквизиты карты.

    2. На бэкенде формируется тело запроса к API HighHelp с блоками general, payment, card и customer (для payin) либо receiver и payment (для payout).

    3. Формируются заголовки аутентификации x-access-timestamp, x-access-merchant-id, x-access-token, x-access-signature по правилам из Аутентификация и подпись.

  2. Отправка HTTP-запроса в API HighHelp.

    1. Для ECOM payin используется endpoint payment/ecom/payin.

    2. Для ECOM payout используется endpoint payment/ecom/payout.

  3. Первичная обработка заявки.

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

    2. Заявке присваивается статус processing:new или ошибка. Описание статусов см. в разделе Коды статусов.

  4. Дополнительная аутентификация (3-D Secure или redirect) при необходимости.

    1. Эмитент может потребовать прохождение 3-D Secure или другой формы аутентификации клиента.

    2. В этом случае заявка переходит в один из промежуточных статусов (processing:awaiting_3ds_result или processing:awaiting_redirect_result).

    3. Данные для аутентификации передаются мерчанту в теле оповещения. Порядок работы с 3-D Secure описан в разделе Одностадийная оплата.

  5. Завершение заявки.

    1. После выполнения всех проверок заявка переходит в один из финальных статусов:

      • success — операция выполнена успешно.

      • decline — операция отклонена.

      • error — ошибка при обработке запроса или выполнении операции.

    2. Информация о результате передается мерчанту в виде оповещения .

  6. Запрос статуса заявки по API при необходимости.

    1. Мерчант может запросить актуальный статус заявки через методы …​/payin/info и …​/payout/info.

    2. Формат ответа и набор полей совпадает с данными, которые приходят в оповещениях.

Требования к интеграции

При интеграции ECOM H2H следует учитывать:

  • Обработка карточных данных.

    • Реквизиты карты проходят через инфраструктуру мерчанта.

    • Требуется обеспечить соответствие требованиям безопасности (например, PCI DSS) на стороне мерчанта.

  • Корректность указания сумм и валют.

    • Сумма передается в дробных единицах валюты без разделителей.

    • Информация по количеству дробных разрядов приведена в разделе Коды валют.

  • Использование корректных методов оплаты.

  • Обработка статусов и оповещений.

    • Необходимо обрабатывать финальные и промежуточные статусы, описанные в Коды статусов.

    • Рекомендуется реализовать защиту от повторной обработки дубликатов оповещений (ключ идемпотентности можно строить, например, как {project_id}:{payment_id}:{status}:{sub_status}).

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