Интеграция по API (H2H)

В этом разделе дается обзор интеграции по схеме H2H (host-to-host) для работы с API платежного шлюза HighHelp.

Подробнее о базовых терминах см. в разделе Основные понятия. Механизм аутентификации и подписи описан в разделе Аутентификация и подпись.

Что такое H2H-интеграция

Интеграция по API (H2H) — это сценарий, при котором:

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

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

  • HighHelp обрабатывает заявку и возвращает результат в ответе и через оповещения.

В отличие от виджета (H2C):

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

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

Когда использовать H2H

H2H-интеграция используется в следующих случаях:

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

  • есть существующая платежная форма или платежный модуль, который нужно подключить к HighHelp;

  • необходимо гибко управлять маршрутизацией заявок, логированием и обработкой ошибок на стороне мерчанта;

  • использование виджета (H2C) невозможно по техническим или юридическим ограничениям.

Если цель — как можно быстрее запустить прием платежей, рекомендуем сначала пройти сценарий Быстрый старт, а затем возвращаться к H2H-интеграции.

Общая схема взаимодействия

При H2H-интеграции используются следующие компоненты:

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

  • API платежного шлюза HighHelp (https://api.hh-processing.com).

  • Внешние платежные провайдеры и банки на стороне HighHelp.

  • HTTP-эндпоинты мерчанта для приема оповещений (колбеков).

Базовый поток для операций payin и payout:

  1. Бэкенд мерчанта формирует тело запроса с блоками general, payment и дополнительными блоками (sender, receiver, customer и т.п.).

  2. Формируются заголовки аутентификации (x-access-timestamp, x-access-merchant-id, x-access-token, x-access-signature).

  3. Запрос отправляется в API HighHelp по H2H-методу (например, /api/v1/payment/p2p/payin или /api/v1/payment/ecom/payin).

  4. HighHelp выполняет проверки и возвращает первичный ответ со статусом (status, sub_status, request_id, payment_id).

  5. При изменении статуса заявки HighHelp отправляет оповещения на URL, указанные в полях merchant_callback_url, merchant_success_callback_url и merchant_decline_callback_url.

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

Список возможных статусов и подстатусов приведен в разделе Коды статусов.

Типы платежей и методы H2H

Поддерживаемые типы платежей описаны в разделе Типы платежей. Поддерживаемые методы для H2H-интеграции перечислены в разделе Методы оплаты (H2H).

Основные группы сценариев H2H:

  • P2P-переводы (card-p2p, sbp-p2p, international-p2p, account-number и др.).

  • Интернет-платежи (ECOM) по карте (card-ecom) — оплата в одну стадию, см. Одностадийная оплата.

  • Дополнительные операции и сервисные методы, описанные в разделе Сервисные методы API.

Выбор типа (payin или payout) и метода (payment.method) определяется бизнес-сценарием и доступными гео.

Структура запросов и ответов

Общие принципы структуры запросов:

  • Блок general — информация по заявке:

    • project_id — идентификатор кассы (проекта);

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

    • URL для оповещений (merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url).

  • Блок payment — параметры платежа:

    • method — код метода оплаты или выплаты;

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

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

    • дополнительные поля, зависящие от метода.

  • Блоки sender / receiver — реквизиты отправителя и получателя (карта, счет и т.п.).

  • Блок customer — данные о клиенте (идентификатор, IP-адрес, страна, контактные данные, информация о браузере и устройстве).

Актуальные требования к полям для конкретного метода приводятся в профильных разделах:

Ответы API H2H:

  • всегда содержат агрегированный статус (status, sub_status, status_description);

  • содержат идентификаторы request_id, project_id, payment_id;

  • могут включать дополнительные блоки (payment_info, card, customer, asc_info, redirect_info и др.) в зависимости от метода и статуса.

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

Аутентификация и безопасность

Все H2H-запросы должны быть:

Кратко:

  • x-access-timestamp — метка времени запроса (Unix Timestamp, UTC).

  • x-access-merchant-id — идентификатор кассы (project_id).

  • x-access-token — публичный ключ кассы, закодированный в Base64Url.

  • x-access-signature — подпись сообщения sha256(base64url(body) + timestamp) приватным RSA-ключом.

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

  • не логировать приватные ключи и значения заголовка x-access-signature;

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

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

Оповещения и идемпотентность

Для всех H2H-сценариев действуют общие принципы работы с оповещениями:

  • HighHelp отправляет HTTP POST-запросы на URL, указанные в merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url.

  • Каждый callback содержит:

    • project_id и блок general с payment_id и request_id;

    • блок status с status, sub_status, status_description;

    • блоки payment_info, card, customer и др. в зависимости от статуса и типа операции.

  • Callback подписывается цифровой подписью HighHelp.

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

  • проверять подпись callback’ов по тому же алгоритму, что используется при отправке запросов, см. Аутентификация и подпись;

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

  • при недоступности callback-эндпойнта использовать методы …​/info для получения актуального статуса заявки.

Этапы внедрения H2H-интеграции

Рекомендуемая последовательность работ:

  1. Ознакомиться с разделами Перед началом работы и Основные понятия.

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

  3. Создать кассу, сгенерировать пару ключей и настроить подпись запросов по разделу Аутентификация и подпись.

  4. Реализовать H2H-запросы для основного сценария:

  5. Реализовать обработку оповещений и идемпотентность на стороне бэкенда мерчанта.

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

  7. После завершения тестирования согласовать переход на продуктивное окружение.

Для первого запуска и проверки рабочего контура можно ориентироваться на сценарий Быстрый старт.