Основные понятия

В этом разделе собраны базовые термины и сущности, которые используются в документации платежного шлюза HighHelp. Раздел ориентирован на разработчиков, которые настраивают интеграцию по API (H2H) и/или через платежный виджет HighHelp.

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

Участники и основные сущности

Платежный шлюз HighHelp

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

Мерчант

Компания или сервис, который интегрируется с HighHelp по API и/или через платежный виджет HighHelp, чтобы принимать платежи или выполнять переводы.

Плательщик

Конечный пользователь (клиент мерчанта), который инициирует платеж или перевод.

Получатель

Пользователь, на реквизиты которого фактически зачисляются средства. В P2P-сценариях получателем является адресат перевода.

Касса (project / merchant cashbox)

Внутренний расчетный счет мерчанта в платежном шлюзе. У кассы есть идентификатор project_id. Через кассу проходят зачисления, списания и выплаты.

Баланс кассы

Текущий остаток средств на кассе в разрезе валют. Доступные поля баланса описаны в разделе Баланс кассы.

Замороженный баланс

Часть баланса кассы, зарезервированная под незавершенные операции, например, до завершения выплаты или подтверждения списания.

Проект

Логическая единица интеграции мерчанта (интернет-магазин, сервис, приложение), привязанная к кассе. Для проекта настраиваются методы оплаты, URL для оповещений (merchant_*_callback_url) и параметры маршрутизации.

Платеж, операция и типы платежей

Платеж

Бизнес-сценарий перемещения средств, например, оплата заказа или P2P-перевод. Идентифицируется полем payment_id в рамках конкретной кассы.

Операция

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

Типы платежей

В документации используются следующие типы:

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

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

Список типов платежей описан в разделе Типы платежей.

Продукты: P2P и ECOM

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

P2P

Сценарии переводов между пользователями, например, перевод с карты на карту. Для таких операций используются методы вида card-p2p, sbp-p2p и др. Перечень методов H2H-интеграции приведен в разделе Методы оплаты (H2H).

ECOM

Сценарии интернет-платежей за товары и услуги (e-commerce). Для ECOM используются методы вида card-ecom и связанные с ними payout-сценарии. Пример одностадийной оплаты по ECOM описан в разделе Одностадийная оплата.

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

Варианты интеграции: H2H и виджет

Интеграция с HighHelp возможна в двух сценариях.

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

Бэкенд мерчанта напрямую вызывает API платежного шлюза. Форма оплаты и пользовательский интерфейс реализуются на стороне мерчанта. Мерчант передает реквизиты платежного средства и данные клиента в теле запроса, получает статусы и обрабатывает оповещения.

Интеграция через платежный виджет HighHelp

Платежная форма размещается на стороне HighHelp (платежный виджет HighHelp) и встраивается в сайт или приложение мерчанта, например, через iframe или JavaScript-виджет. Плательщик вводит платежные данные на платежной странице виджета. Платежный шлюз принимает и обрабатывает данные, а мерчант получает результат через API и оповещения.

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

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

В типичном запросе к API HighHelp используются несколько логических блоков.

general

Обязательный блок с общей информацией по заявке. Как правило, содержит:

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

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

  • динамические URL для оповещений (merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url) для конкретной заявки.

payment

Блок с параметрами платежа:

  • method — код метода оплаты или выплаты. Список методов приведен в Методы оплаты (H2H) и Методы виджета.

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

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

sender / receiver

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

card

Блок с реквизитами карты в явном виде, если они передаются через H2H-интеграцию. Содержит номер карты, срок действия, имя держателя и CVV.

customer

Блок с информацией о клиенте мерчанта:

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

  • ip_address — IP-адрес клиента.

  • country — код страны в формате ISO 3166-1 alpha-2. Список стран приведен в Коды стран.

  • дополнительные атрибуты (язык интерфейса, браузер, user agent и т.п.).

Ответы API содержат:

  • технические поля (request_id, project_id, payment_id);

  • поля со статусом (status, sub_status, status_description);

  • блоки payment_info, card, customer и дополнительные данные для аутентификации или редиректа.

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

Идентификаторы и статусы

В заявках и оповещениях используются следующие ключевые идентификаторы.

project_id

Идентификатор кассы мерчанта в системе HighHelp. Передается в каждом запросе и оповещении.

payment_id

Идентификатор платежа в системе мерчанта. Должен быть уникальным в рамках одной кассы. По нему мерчант связывает запросы, ответы и оповещения.

request_id

Идентификатор заявки в системе HighHelp. Генерируется при создании заявки и возвращается в ответах и оповещениях.

Для описания состояния платежа используются:

status

Основной статус обработки, например, processing, success, decline, error.

sub_status

Подстатус, который уточняет состояние внутри основного статуса, например, new, awaiting_3ds_result, payout_process.

status_description

Текстовое описание причины отказа или особого состояния, например, коды ошибок антифрода.

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

Оповещения

Для информирования мерчанта об изменении статуса заявки используются HTTP-оповещения на адреса, указанные в блоке general:

  • merchant_callback_url — информативные оповещения по промежуточным статусам.

  • merchant_success_callback_url — оповещения об успешном завершении.

  • merchant_decline_callback_url — оповещения о неуспешном завершении.

Оповещения содержат те же идентификаторы (project_id, payment_id, request_id) и поля статуса (status, sub_status, status_description), что и ответы API.

Каждое оповещение подписывается цифровой подписью, формируемой по тому же алгоритму, что и подпись запросов к API. Порядок формирования подписи описан в разделе Аутентификация и подпись.

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

Справочные разделы