Модель статусов и обработка

В этом разделе описана модель статусов в платежном шлюзе HighHelp и принципы их обработки на стороне интеграции. Полный перечень значений status, sub_status и типовых status_description приведен в разделе Коды статусов.

Поля статуса в ответах API и оповещениях

В ответах API и во всех оповещениях используются следующие поля статуса:

  • status — основное состояние заявки или операции.

  • sub_status — уточняющее состояние внутри основного статуса. Поле может быть пустым (null).

  • status_description — текстовое описание статуса или причины ошибки. Поле заполняется для отказов, ошибок и ситуаций, когда требуется действие со стороны мерчанта.

Для интерпретации конкретных значений используйте раздел Коды статусов.

Промежуточные и финальные статусы

Статусы разделяются на две группы:

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

  • Финальные — обработка завершена, результат больше не изменится.

К финальным статусам относятся:

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

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

К промежуточным статусам относятся:

  • группа processing — заявка проходит обработку, подтверждение или маршрутизацию;

  • группа dispute — по заявке требуется разбор проблемной ситуации;

  • статус error — запрос отклонен из-за ошибки параметров или ошибки обработки до завершения бизнес-сценария.

Точный набор промежуточных статусов зависит от типа операции и продукта. Полный перечень приведен в разделе Коды статусов. Сценарии, специфичные для конкретных продуктов, например 3-D Secure, перенаправление или OTP, описаны в профильных разделах документации.

Связь статусов с типами платежей

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

Один и тот же статус может использоваться для разных типов операций. Например:

  • success используется и для оплат (payin), и для выплат (payout).

  • processing:new используется при создании любой заявки.

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

Особенности жизненного цикла оплат и выплат по API H2H описаны в разделе Типы операций и статусы (H2H).

Поле status_description

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

  • Поля status и sub_status фиксируют общий тип состояния.

  • Поле status_description содержит текстовое описание причины.

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

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

  • использовать status_description для логирования и отображения в интерфейсе поддержки;

  • не строить бизнес-логику только на тексте status_description, если решение можно принять по status и sub_status.

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

Рекомендации по обработке статусов

При интеграции по API рекомендуется придерживаться следующих правил:

  • При обработке статуса заявки используйте поля status и sub_status.

  • Считать статусами, завершающими жизненный цикл заявки, значения success и decline.

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

  • Вести журнал всех изменений статуса по payment_id и request_id для последующей диагностики.

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

Дополнительные рекомендации по обработке статусов в контексте H2H-интеграции приведены в разделе Типы операций и статусы (H2H).