Статусы сделок

Статус — единственное поле, по которому определяется, что произошло со сделкой. Оно приходит и в ответах API (status), и в каждом webhook-уведомлении. Эта страница — канонический перечень: остальные разделы ссылаются на неё, а не повторяют её.

Все статусы

Статус	Pay-In	Pay-Out	Финальный	Что означает
pending	—	✓	нет	Выплата принята и ждёт исполнителя
active	✓	✓	нет	Pay-In: реквизиты выданы, ждём оплату. Pay-Out: выплата в работе
checking	✓	—	нет	Идёт автоматическая сверка поступившего платежа
checking_manually	✓	—	нет	Платёж проверяется вручную
manual_review	—	✓	нет	Выплата поставлена на ручное подтверждение
dispute	✓	✓	нет	По сделке открыт спор
success	✓	✓	да	Операция завершена на исходную сумму
success_changed	✓	✓	да	Операция завершена, сумма пересчитана по факту
canceled	✓	✓	да	Операция отменена, причина — в dispute.cancelReason

Осторожно

Финальных статусов три: success, success_changed и canceled. Отгружать товар, зачислять средства клиенту и закрывать заказ можно только на них. Все остальные — промежуточные, и сделка ещё может уйти в другую сторону.

Жизненный цикл Pay-In

                       ┌──────────────────────────────┐
                       ▼                              │
  создание ──► active ──► checking ──► checking_manually
                  │           │                │
                  │           └────────┬───────┘
                  │                    ▼
                  │            success / success_changed
                  │
                  ├──► dispute ──► success / success_changed / canceled
                  │
                  └──► canceled

active — сделка создана, клиенту выданы реквизиты. С этого момента идёт отсчёт paymentLifetime.

checking и checking_manually — платёж поступил и сверяется: автоматически либо, если автоматика не сошлась, вручную. Эти состояния вы можете увидеть в ответе GET-запроса по сделке. Отдельного уведомления о входе в них не отправляется — следующий webhook придёт уже с результатом сверки.

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

success — платёж подтверждён на ту сумму, которая была в сделке. Средства зачислены на баланс.

success_changed — платёж подтверждён, но фактическая сумма отличалась от заявленной, и итог пересчитан. Поле amount в уведомлении содержит уже пересчитанное значение — сверяйтесь с ним, а не с суммой, которую отправляли при создании.

canceled — оплата не состоялась. Чаще всего истёк paymentLifetime.

Жизненный цикл Pay-Out

                   ┌──────────────┐
                   ▼              │
  создание ──► pending ──► active ──► success / success_changed
                   │          │
                   │          ├──► manual_review ──► success / canceled
                   │          │
                   │          └──► dispute ──► success / canceled
                   │
                   └──► canceled

pending — стартовое состояние: заявка принята, проверена и поставлена в очередь на исполнение.

active — выплата взята в работу, идёт проверка реквизитов и перевод средств.

manual_review — выплата остановлена для ручного подтверждения. Дальше она либо закрывается как success, либо отменяется.

success — средства отправлены по указанным реквизитам, действий с вашей стороны не требуется.

canceled — выплата не состоялась: неверные реквизиты, невозможность зачисления или отмена с вашей стороны.

Заметка

Возврат из active в pending. Если исполнителя пришлось переназначить, выплата возвращается в очередь. Это штатное поведение, а не ошибка: вы получите уведомление со статусом pending по сделке, которая уже была active. Не считайте это откатом и не создавайте выплату заново.

Причины отмены

Когда сделка уходит в canceled, причина приходит в dispute.cancelReason.

Значение	Когда возникает
TIMEOUT	Истекло время на оплату Pay-In сделки
USER_CANCELED	Отмену инициировали вы — через API или через платёжную страницу
MERCHANT_CANCELED	Сделку отменила сторона, обслуживающая платёж
WRONG_REQUISITE	Выплата невозможна по переданным реквизитам
NONE	Отмена по решению поддержки: ручная проверка не пройдена либо изменение суммы не подтверждено

Осторожно

Не выводите значение cancelReason конечному клиенту как есть. USER_CANCELED приходит в том числе на отмену по вашему собственному запросу к API, а NONE не означает «причины нет» — это отмена оператором. Сопоставляйте значения со своими формулировками.

Статусы в matching-уведомлениях

Matching-заявка — не сделка, но её состояние приходит в том же формате. Отличить такое уведомление можно по полю category:

Поле	Уведомление о сделке	Уведомление о matching
category	trade	matching
id	ID сделки	ID matching-заявки
status	статус сделки	состояние заявки в терминах статусов сделки
crypto, rate, fee	фактические значения	всегда 0
factFiatAmount	—	сумма, фактически закрытая входящими платежами
tradeIdsAll / tradeIdsSuccess	—	ID всех и только успешных связанных сделок

Состояние заявки отображается в статусы так:

Состояние заявки	Приходит как
Открыта или частично наполнена	active
Закрыта полностью на исходную сумму	success
Закрыта, но фактическая сумма отличается от заявленной	success_changed
Отменена	canceled

Подробнее — в разделе Matching.

Как работать со статусами

• Статус одной сделки меняется несколько раз; ориентируйтесь на текущее значение, а не на последовательность полученных уведомлений — они могут прийти не по порядку.
• Не пишите логику «если пришёл checking, значит дальше будет success»: сверка может закончиться и спором, и отменой.
• Ветку success_changed обрабатывайте наравне с success, иначе часть успешных платежей у вас зависнет.
• Всё, что не входит в список финальных, считайте «ещё не решено».

Полный контракт уведомления и правила его обработки — в разделах Webhook и Надёжность интеграции.