Статусы операций и коды ошибок

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

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

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

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

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

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

Полный список значений status и sub_status, а также типовые значения status_description описаны в разделе Коды статусов.

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

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

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

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

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

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

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

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

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

  • processing:new — заявка принята и ожидает обработки.

  • processing:requisites — выполняется проверка реквизитов или подбор провайдера.

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

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

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

  • dispute:incorrect_requisites — получены некорректные реквизиты и требуется уточнение.

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

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

Точный набор промежуточных статусов зависит от типа операции и продукта. Актуальный список приведен в разделе Коды статусов.

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

Тип операции задается полем type (например, payin или payout) и описан в разделе Типы платежей.

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

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

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

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

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

Ошибки и коды ошибок

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

  • Поля status и sub_status фиксируют общий тип состояния (например, decline или error).

  • Поле status_description содержит текстовое описание причины (например, Canceled by client, Declined by anti-fraud, Requisites not found).

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

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

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

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

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

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

  • Обрабатывать status и sub_status как основную машинно-читаемую модель состояния.

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

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

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

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

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