Матрица статусов оплаты, холда и возврата в отеле

Матрица платёжных статусов нужна отелю, чтобы одно событие провайдера всегда приводило к одному понятному действию: подтвердить оплату, выдать доступ, дождаться результата, отменить холд, оформить возврат или передать исключение сотруднику. Надпись «операция принята» ещё не означает, что деньги списаны или вернулись гостю.

Ниже — практический способ связать платёж, обеспечительный холд, возврат и самостоятельное заселение без ложных подтверждений. Названия статусов у провайдеров различаются, поэтому матрицу нужно настраивать по официальному API конкретного эквайера, а не копировать как универсальный словарь.

Короткая матрица: статус → действие

Почему одного поля «оплачено» недостаточно

В платёжном маршруте живут как минимум четыре разные сущности: бронь, платёж, авторизация и возврат. У каждой есть свой идентификатор, сумма, время создания и источник истины. Если свести их к одному флагу, сотрудник не отличит заблокированные средства от списанных, отмену холда от возврата и принятый запрос от завершённой операции.

В документации ЮKassa двухстадийный платёж проходит через waiting_for_capture, а затем становится succeeded после списания или canceled после отмены либо истечения срока. У Т‑Банка отмена авторизации и возврат уже подтверждённого платежа также ведут к разным состояниям: например, REVERSED и REFUNDED. Эти словари похожи по смыслу, но не взаимозаменяемы посимвольно.

Пять полей, которые сохраняют контекст

• локальный идентификатор обязательства, связанный с бронью;
• идентификатор операции у провайдера;
• тип операции: платёж, холд, capture, cancel или refund;
• текущий статус, сумма, валюта и время последней проверенной смены;
• дедлайн авторизации и основание ручного решения, если оно потребовалось.

Ключ идемпотентности относится к конкретному намерению. Повтор технически того же запроса использует тот же ключ; новый частичный возврат или новое обязательство получает отдельную устойчивую идентичность. Так система может безопасно пережить повтор webhook, перезапуск процесса или неопределённый сетевой ответ.

Как связать матрицу с самостоятельным заселением

До заезда

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

Перед выдачей доступа

Цифровой ключ, PIN-код или инструкция выдаются только при разрешённой комбинации фактов: бронь активна, обязательные данные заполнены, платёж или холд находится в нужном финальном состоянии, номер готов. Подробнее вся связка разобрана в руководстве по самостоятельному заселению.

После отмены или выезда

Система различает отмену ещё не списанного холда и возврат уже списанного платежа. Для спорного или частичного списания решение подтверждает уполномоченный сотрудник; автоматизация сохраняет основание, сумму, идентификаторы и уведомление гостю.

Webhook, API-ответ и реестр: три разных доказательства

ЮKassa рекомендует получать статус уведомлением или запросом к API, а успешные платежи и возвраты ежедневно сверять по реестрам. Adyen отдельно подчёркивает, что для асинхронных сценариев бизнес-логика должна учитывать webhook, а события нужно проверять и обрабатывать идемпотентно.

Что делать при timeout и pending

1. Не создавать вторую операцию. Сначала найдите исходную по локальному и внешнему идентификатору.
2. Проверьте журнал событий. Возможно, webhook уже доставлен, но ещё не применён к брони.
3. Запросите статус у провайдера. Делайте это по существующему ID, а не повторяйте денежное действие.
4. Сверьте сумму и тип операции. Частичный возврат нельзя путать с новым полным возвратом.
5. Оставьте маршрут закрытым при неизвестном исходе. Доступ, повторное списание и сообщение «деньги возвращены» ждут финального доказательства.

Это особенно важно для возвратов: официальная справка ЮKassa прямо предупреждает не повторять частичный возврат, пока его статус не обновился, иначе при достаточном балансе возврат может пройти дважды.

Проверка на передаче смены

Связь с гостем тоже должна отражать состояние, а не обещание. Для pending это «проверяем результат», для успешного возврата — подтверждение операции и её ID, для ошибки — следующий безопасный шаг. Канальную схему можно сверить с материалом о каскадной доставке сообщений.

Как спроектировать локальную модель состояний

Копировать все технические статусы провайдера прямо в CJM неудобно: интеграция меняется, а операционные решения отеля остаются теми же. Практичнее хранить исходный ответ отдельно, а для маршрута переводить его в небольшой нормализованный набор состояний. Такой слой не скрывает детали — сотрудник по-прежнему может открыть внешний ID и исходный статус, — но не заставляет каждый сценарий знать словарь конкретного банка.

Например, два разных провайдера могут сообщить succeeded и CONFIRMED. В локальной модели оба состояния означают «платёж завершён», но исходные значения сохраняются для диагностики. Напротив, waiting_for_capture и AUTHORIZED нельзя автоматически приравнять к окончательной оплате: для них ещё нужно выбрать списание или отмену.

Переходы должны быть монотонными

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

Исключения тоже являются состояниями. Вместо общего «ошибка» полезно различать как минимум: нужна повторная проверка статуса, не совпала сумма, истекает авторизация, возврат отклонён, отсутствует связь с бронью и требуется решение сотрудника. Это позволяет назначить владельца и дедлайн, а не оставлять неопределённость в комментарии.

Минимальный пилот перед production

Матрицу нельзя считать готовой после демонстрационного успешного платежа. До подключения реальных гостей проведите тестовый набор с минимальными суммами в разрешённом контуре провайдера и сохраните доказательства каждого перехода.

1. Обычный успешный платёж. Проверить создание, подтверждение webhook, запись внешнего ID и однократный запуск следующего шага.
2. Отказ и незавершённая форма. Убедиться, что доступ не выдаётся и гость получает понятное повторное действие без бесконечной рассылки.
3. Полный холд. Проверить авторизацию, сохранение фактического дедлайна, capture и cancel как разные ветки.
4. Частичная операция. Проверить сумму частичного capture или refund, остаток и запрет повторного запроса.
5. Timeout. Искусственно разорвать ожидание ответа и доказать, что система сначала сверяет существующий внешний ID.
6. Повтор webhook. Доставить событие дважды и подтвердить, что зависимый шаг выполняется один раз.
7. Позднее событие. Отправить старый статус после финального и проверить, что состояние не откатывается.
8. Ежедневная сверка. Сопоставить локальные суммы и количество операций с реестром провайдера.

Для каждого теста фиксируют ожидаемый статус, фактический статус, действие CJM, сообщение гостю и запись в журнале сотрудника. Production-разрешение даётся только после проверки полного маршрута: платёж сам по себе не доказывает, что бронь, коммуникация и доступ отреагировали правильно.

Метрики без выдуманного «среднего эффекта»

На пилоте полезно считать долю операций без ручного вмешательства, число неизвестных статусов, повторных денежных запросов, расхождений сверки и случаев выдачи доступа до финального подтверждения. Базу собирают на конкретном объекте. Нулевой показатель преждевременной выдачи доступа и двойных операций — стоп-условие безопасности, а не обещание рыночного процента экономии.

Подтверждено сегодня, roadmap и гипотеза

• Подтверждено 22 августа 2026 года: официальные документы ЮKassa и Т‑Банка разводят авторизацию, списание, отмену и возврат; webhook и запрос статуса используются как источники состояния, а реестры — для сверки.
• Roadmap конкретного объекта: сопоставить фактические статусы выбранного провайдера с CJM, проверить чеки, роли сотрудников, дедлайны и все переходы на тестовых операциях. Наличие общего платёжного модуля не доказывает готовность каждого провайдера и сценария.
• Гипотеза для пилота: матрица уменьшит ручные ошибки и повторные операции. Это измеряют на журнале исключений до и после запуска; универсального процента улучшения нет.

FAQ

Можно ли выдать доступ при статусе pending?

Только если правила объекта вообще не требуют оплаты или депозита до заселения. Если платёж обязателен, pending не является подтверждением и должен блокировать автоматический доступ.

Чем отмена холда отличается от возврата?

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

Достаточно ли webhook?

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

Когда сообщать гостю, что возврат завершён?

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

Можно ли использовать эту матрицу с любым эквайером?

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

Источники

• ЮKassa: процесс платежа и статусы.
• ЮKassa: полные и частичные возвраты.
• ЮKassa: входящие уведомления.
• ЮKassa: реестры платежей и возвратов.
• Т‑Банк: отмена и возврат платежа.
• Adyen: обработка webhook.