Типы операций и статусы (H2H)

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

Общие сведения о типах платежей приведены в разделе Типы платежей. Полный перечень статусов описан в разделе Коды статусов.

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

В платежном шлюзе HighHelp используются следующие сущности:

  • Платеж — бизнес-сценарий перемещения средств, например, оплата заказа или выплата пользователю. Платеж идентифицируется payment_id.

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

  • Тип платежа (type) — направление движения средств. Основные значения описаны в разделе Типы платежей:

    • payin — оплата (счет пользователя → касса мерчанта);

    • payout — выплата (касса мерчанта → счет пользователя).

Во всех API-методах состояние заявки описывается полями status, sub_status и status_description. Модель этих полей приведена в разделе Статусы операций и коды ошибок.

Жизненный цикл оплаты (payin)

Жизненный цикл оплаты по H2H включает следующие этапы:

  1. Создание заявки.

    Мерчант вызывает метод создания оплаты (например, /api/v1/payment/p2p/payin или /api/v1/payment/ecom/payin), указывая type=payin, реквизиты и сумму. В ответе возвращается статус:

    • status=processing, sub_status=new.

  2. Проверка параметров и реквизитов.

    Платежный шлюз проверяет корректность переданных данных и доступность провайдеров. В этот этап могут использоваться промежуточные статусы, например:

    • processing:requisites.

  3. Дополнительная аутентификация (если требуется).

    Для некоторых сценариев оплаты может потребоваться 3-D Secure или аутентификация на стороне эмитента. В этом случае используются статусы:

    • processing:awaiting_3ds_result — ожидается результат 3-D Secure аутентификации;

    • processing:awaiting_redirect_result — ожидается результат аутентификации при перенаправлении.

      Подробный порядок работы 3-D Secure описан инструкциях для H2H (например, Одностадийная оплата).

  4. Финальное решение по оплате.

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

    • success — средства успешно списаны и зачислены;

    • decline — операция отклонена (по бизнес-причине или по решению антифрода);

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

Во всех финальных статусах (success, decline, error) операция считается завершенной. Дополнительные попытки списания по той же заявке не выполняются.

Краткое описание состояний:

  • new — заявка принята в обработку.

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

  • awaiting_3ds_result — ожидается результат аутентификации через 3-D Secure.

  • awaiting_redirect_result — ожидается результат аутентификации на стороне эмитента после перенаправления.

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

  • success — оплата завершена, средства зачислены.

  • decline — оплата отклонена. Причину можно уточнить по полям status_description и коду ошибки.

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

Жизненный цикл выплаты (payout)

Жизненный цикл выплаты включает:

  1. Создание заявки.

    Мерчант вызывает метод создания выплаты (например, /api/v1/payment/p2p/payout или /api/v1/payment/ecom/payout), указывая type=payout, реквизиты получателя и сумму. В ответе возвращается:

    • status=processing, sub_status=new.

  2. Проверка баланса и реквизитов.

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

    • processing:requisites.

  3. Исполнение выплаты.

    После успешной проверки заявка переходит в статус:

    • processing:payout_process — выполняется перечисление средств на указанные реквизиты.

  4. Разбор проблемных ситуаций (dispute).

    Если платеж не может быть исполнен, используются статусы группы dispute, например:

    • dispute:incorrect_requisites — указаны некорректные реквизиты;

    • dispute:payout_failed — выплата не исполнена провайдером;

    • dispute:payout_timeout — выплата не исполнена до истечения времени жизни заявки.

      В этих статусах требуется дополнительная обработка и решение на стороне мерчанта и/или поддержки.

  5. Финальное решение по выплате.

    Завершение жизненного цикла выплаты фиксируется статусами:

    • success — выплата выполнена;

    • decline — выплата отклонена;

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

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

Краткое описание ключевых состояний:

  • new — заявка на выплату принята в обработку.

  • requisites — проверяются реквизиты получателя и выполняется маршрутизация.

  • payout_process — выполняется перечисление средств.

  • success — выплата выполнена.

  • decline — выплата отклонена без открытия спора.

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

  • dispute:incorrect_requisites — открыт спор из-за некорректных реквизитов.

  • dispute:payout_failed — спор по причине неуспешного исполнения выплаты.

  • dispute:payout_timeout — спор по причине истечения времени обработки выплаты.

Статусы споров (dispute)

Спор (dispute) описывает разбирательство по конкретной операции оплаты или выплаты. Ниже приведен обобщенный жизненный цикл спора.

stateDiagram-v2
[*] --> opened
opened --> in_progress
in_progress --> resolved
in_progress --> declined
resolved --> [*]
declined --> [*]

Описание состояний:

  • opened — спор создан.

  • in_progress — спор рассматривается.

  • resolved — спор закрыт с зафиксированным решением в пользу одной из сторон.

  • declined — спор закрыт без изменения результата операции.

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

Соответствие статусов и действий мерчанта

В таблице ниже приведены общие рекомендации по обработке статусов на стороне мерчанта.

Группа статусов Примеры значений Рекомендации

Принятие и обработка

processing:new, processing:requisites

Фиксировать создание заявки. Отображать состояние в обработке. Не изменять бизнес-статус заказа и не выполнять финансовых действий.

Ожидание действия пользователя

processing:awaiting_3ds_result, processing:awaiting_redirect_result

Ожидать завершения аутентификации. При необходимости перенаправлять пользователя на страницу эмитента или 3-D Secure. Не списывать или возвращать средства самостоятельно.

Исполнение выплаты

processing:payout_process

Отображать состояние выплата в процессе. Не дублировать выплаты до получения финального статуса.

Разбор проблемной ситуации

dispute:*

Зафиксировать детали и передавать информацию оператору поддержки. Не выполнять повторные списания или выплаты до уточнения причины.

Успешное завершение

success

Обновить статус заказа на оплачен или выплата выполнена. Отобразить результат пользователю. Не выполнять повторных финансовых действий по этому payment_id.

Неуспешное завершение

decline, error

Обновить статус заказа на отклонен или аналогичный. Разрешить пользователю повторить оплату или запросить новую выплату с новым payment_id.

Дополнительные примеры жизненного цикла статусов приведены в разделах P2P и ECOM и в Статусы операций и коды ошибок