Общие требования для P2P H2H

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

Определения основных терминов (мерчант, плательщик, получатель, P2P, касса) приведены в разделе Глоссарий. Общие сведения о H2H-интеграции см. в разделе Обзор H2H-интеграции.

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

P2P H2H используется для переводов между физическими лицами, когда:

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

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

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

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

Типы платежей payin и payout, используемые в P2P-сценариях, описаны в разделе Типы платежей.

Список поддерживаемых методов для P2P H2H (например, card-p2p, sbp-p2p, international-p2p, account-number) приведен в разделе Методы оплаты (H2H).

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

Сравнение P2P H2H и P2P через виджет

P2P можно реализовать:

Различия:

  • При P2P H2H:

    • формы и сценарии взаимодействия с пользователем разрабатываются на стороне мерчанта.

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

    • ответственность за обработку и хранение реквизитов лежит на стороне мерчанта.

  • При P2P через виджет:

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

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

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

Сценарии P2P через виджет описаны в разделах:

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

В рамках P2P H2H возможны следующие сценарии (конкретный список зависит от настроек кассы и подключенных провайдеров):

  • P2P-перевод по карте (тип payin). Пользователь переводит средства на карту получателя. Метод оплаты выбирается из Методы оплаты (H2H).

  • P2P-перевод по номеру телефона. Используется для переводов через национальные системы быстрых платежей, если они доступны в выбранной стране.

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

  • P2P-выплаты (тип payout). При наличии соответствующих настроек возможны исходящие переводы в пользу клиентов или партнеров, например, вывод средств.

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

География и профили интеграции

Для P2P H2H используются отдельные профили интеграции по странам. Каждый профиль описывает:

  • поддерживаемые методы оплаты;

  • ограничения по суммам и валютам;

  • особенности KYC и проверки получателя;

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

Описание профилей находится в следующих разделах:

Рекомендуется начинать интеграцию с чтения обзора по нужной стране, а затем переходить к реализации запросов и обработке ответов.

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

Ниже описан обобщенный процесс обработки P2P-платежа по схеме H2H.

Конкретные поля запросов и ответов зависят от страны и метода.

  1. Мерчант формирует и отправляет запрос на создание заявки.

    • В запросе указываются:

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

      • идентификатор платежа payment_id (уникален в рамках кассы мерчанта).

      • параметры платежа (сумма, валюта, метод, тип платежа).

      • данные отправителя и получателя.

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

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

  2. HighHelp принимает запрос и выполняет первичную проверку.

    • Проверяются:

      • корректность структуры запроса и обязательных полей.

      • доступность метода и валюты для кассы.

      • ограничения по суммам и географии.

    • При успешной проверке создается заявка и присваивается статус, например processing:new. Статусы и подстатусы описаны в разделе Коды статусов.

  3. Заявка проходит дальнейшую обработку.

    • Выполняются проверки антифрода и комплаенса.

    • Подбираются провайдеры или трейдеры для исполнения операции.

    • Статус заявки может изменяться (например, processing:requisites, processing:payout_process и др.).

  4. HighHelp отправляет оповещения при изменении статуса.

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

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

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

    • Формат оповещений описан в разделе Оповещения H2H .

  5. Мерчант фиксирует результат и выполняет бизнес-логику.

    • Для финальных статусов success, decline или error обновляется состояние заказа или перевода на стороне мерчанта.

    • При необходимости логируются промежуточные статусы.

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

    • Для P2P предусмотрены методы …​/payin/info и, при наличии, методы для получения статуса выплат.

    • Ответ включает текущие значения status, sub_status, а также параметры платежа. Формат описан в профильных разделах по странам.

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

При интеграции P2P H2H рекомендуется учитывать следующие требования:

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

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

    • Количество дробных разрядов для каждой валюты описано в Коды валют.

  • Корректность указания страны и гео.

    • Код страны указывается в формате ISO 3166-1 alpha-2.

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

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

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

    • Логика обработки должна учитывать финальные и промежуточные статусы из Коды статусов.

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

  • Безопасность и хранение данных.

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

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

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

Для реализации P2P H2H-интеграции изучите: