Payment Orchestrator

Тема

03.04 Transaction Lifecycle And Statuses ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ описывает жизненный цикл deposit transaction и единый словарь статусов для MVP.

Цель документа:

  • зафиксировать список статусов;
  • описать, кто и когда устанавливает каждый статус;
  • определить final statuses;
  • определить правила automatic transitions;
  • определить правила manual correction;
  • определить, какие статусы отправляются merchant через webhook;
  • определить, что видит hosted payment form;
  • определить, что сохраняется в transaction timeline.

2. MVP Status List ​

В MVP используются следующие transaction statuses:

  • CREATED
  • WAITING_CUSTOMER_DATA
  • PROCESSING
  • COMPLETED
  • FAILED
  • CANCELED
  • REJECTED

Статус FROZEN не входит в MVP.

3. Status Groups ​

Non-Final Statuses ​

Non-final statuses:

  • CREATED
  • WAITING_CUSTOMER_DATA
  • PROCESSING

Эти статусы означают, что transaction еще может продолжить движение по flow.

Final Statuses ​

Final statuses:

  • COMPLETED
  • FAILED
  • CANCELED
  • REJECTED

После final status transaction не должна автоматически менять статус.

Status может быть изменен вручную через manual transaction correction пользователем с соответствующей permission.

4. CREATED ​

CREATED ставится сразу после успешного создания transaction.

Условия:

  • merchant authentication прошел успешно;
  • все обязательные поля create deposit request переданы;
  • transactionId уникален;
  • brandId валиден;
  • paymentMethodId валиден;
  • transaction record создана.

После установки CREATED система начинает routing.

Transaction выходит из CREATED, когда routing started и система определяет следующий шаг:

  • перейти к WAITING_CUSTOMER_DATA;
  • перейти к REJECTED.

Отправка request в provider не должна сама по себе переводить transaction в PROCESSING. Это должно сохраняться как timeline event.

5. WAITING_CUSTOMER_DATA ​

WAITING_CUSTOMER_DATA ставится, когда выбранный routing path / SUB MID GROUP / SUB MID требует дополнительные customer attributes, которых merchant не передал при создании transaction.

Примеры:

  • provider method требует ip;
  • provider method требует address;
  • provider method требует city;
  • provider method требует другие canonical attributes.

Hosted payment form должна показать customer form и дособрать недостающие поля.

Transaction выходит из WAITING_CUSTOMER_DATA, когда:

  • customer заполнил обязательные поля, и система продолжает provider execution;
  • transaction expired и переходит в CANCELED.

6. PROCESSING ​

PROCESSING ставится только когда provider сообщил meaningful intermediate status, который означает, что payment находится в обработке, но финальное подтверждение еще не получено.

В текущей бизнес-семантике PROCESSING означает, что provider сообщил: платежное действие уже находится в процессе, но еще не завершено финально.

PROCESSING не должен ставиться просто потому, что:

  • система отправила request в provider;
  • система получила provider payment URL;
  • customer открыл hosted form;
  • routing начался;
  • customer открыл iframe/redirect.

Такие события должны сохраняться в transaction timeline, например:

  • PROVIDER_REQUEST_SENT;
  • PROVIDER_PAYMENT_URL_RECEIVED;
  • PROVIDER_IFRAME_OPENED;
  • PROVIDER_REDIRECT_USED.

Главное условие для PROCESSING: provider callback/status явно сообщает processing/in-progress состояние в бизнес-смысле.

7. COMPLETED ​

COMPLETED ставится в результате обработки provider webhook/callback.

Также COMPLETED может быть установлен вручную через transaction correction пользователем с соответствующей permission.

COMPLETED является final status.

8. FAILED ​

FAILED ставится:

  • в результате обработки provider webhook/callback;
  • внутренней системой, если provider timeout / provider execution failed и fallback больше невозможен;
  • вручную через transaction correction пользователем с соответствующей permission.

FAILED является final status.

9. CANCELED ​

CANCELED ставится:

  • в результате обработки provider webhook/callback;
  • если transaction expired на нашей стороне;
  • вручную через transaction correction пользователем с соответствующей permission.

Expiration может перевести transaction в CANCELED даже если transaction уже находится в PROCESSING и provider еще не прислал final callback.

CANCELED является final status.

10. REJECTED ​

REJECTED ставится из-за внутренних причин processing.

Примеры:

  • routing не найден;
  • payment method unavailable;
  • velocity rejected all routes;
  • unsupported configuration;
  • validation failed after transaction creation;
  • все возможные routing/fallback options закончились.

REJECTED является final status.

11. Provider Callback Handling ​

Система обрабатывает только provider callback statuses:

  • FAILED
  • COMPLETED
  • PROCESSING
  • CANCELED

Если provider прислал pending, система не должна учитывать этот status как отдельный transition.

Если provider прислал unknown status, система должна:

  • не менять transaction status;
  • сохранить событие в transaction timeline как ignored.

Если provider прислал callback после того, как transaction уже находится в final status, система должна:

  • не менять transaction status;
  • сохранить событие в transaction timeline как ignored.

12. Expiration ​

Expiration timer стартует с момента создания transaction.

Default expiration:

  • 30 минут.

Expiration time должен настраиваться через environment variables.

Также expiration может зависеть от SUB MID configuration, если такая настройка используется.

Если transaction expired, она переходит в:

text
CANCELED

Expiration может применяться даже к transaction в статусе PROCESSING, если provider еще не вернул final callback.

13. Merchant Webhooks ​

Merchant webhooks отправляются на PROCESSING, если PROCESSING пришел от provider как meaningful intermediate status.

Merchant webhooks также отправляются на final statuses:

  • COMPLETED
  • FAILED
  • CANCELED
  • REJECTED

Webhooks не отправляются на:

  • CREATED
  • WAITING_CUSTOMER_DATA

Важно: webhook на PROCESSING можно отправлять только когда PROCESSING пришел от provider как meaningful intermediate status, а не после факта отправки request в provider.

14. Hosted Payment Form Behavior ​

Customer не должен видеть technical transaction statuses.

Hosted payment form использует statuses для принятия действий:

  • CREATED -> loading / polling;
  • WAITING_CUSTOMER_DATA -> показать customer form для дополнительных fields;
  • PROCESSING -> loading / ожидание final provider result;
  • COMPLETED -> provider/merchant success behavior;
  • FAILED -> generic error;
  • CANCELED -> expired/canceled error;
  • REJECTED -> method unavailable или generic error.

Customer-facing UI не должен показывать raw status names.

15. Manual Transaction Correction ​

Transaction correction позволяет вручную изменить transaction status на любой допустимый transaction status.

Доступные statuses для correction:

  • PROCESSING
  • COMPLETED
  • FAILED
  • CANCELED
  • REJECTED

Manual correction может изменить любой status на любой другой допустимый status.

Пример:

text
COMPLETED -> FAILED

или:

text
REJECTED -> PROCESSING

Такое действие доступно только пользователю с соответствующей permission.

Correction status не ограничивается текущим статусом transaction.

Reason/comment обязателен.

Manual correction запрещена для migrated legacy transactions, которые marked as read-only.

16. Correction Webhook ​

При manual correction система должна всегда спросить user-а, нужно ли сделать resend callback / webhook merchant.

Если resend выбран:

  • система отправляет webhook с новым status;
  • webhook отправляется на все webhook URLs transaction;
  • webhook payload содержит corrected: true;
  • action сохраняется в transaction timeline;
  • action сохраняется в audit log.

Если resend не выбран:

  • status меняется;
  • webhook не отправляется;
  • decision сохраняется в transaction timeline;
  • decision сохраняется в audit log.

17. Status History And Timeline ​

Отдельная status history table не требуется для MVP.

Transaction timeline достаточно, если она сохраняет всю необходимую информацию о status changes.

Для каждого status change нужно сохранять:

  • previous status;
  • new status;
  • reason;
  • source;
  • actor, если status изменен вручную;
  • timestamp.

18. Status Change Source ​

Для каждого status change нужно хранить source.

Возможные sources:

  • merchant_api;
  • routing;
  • provider_callback;
  • expiration;
  • manual_correction;
  • system.

Source нужен для investigation, audit и support.

19. Automatic Transition Rules ​

Основные automatic transitions:

text
CREATED -> WAITING_CUSTOMER_DATA
CREATED -> REJECTED
CREATED -> PROCESSING
CREATED -> COMPLETED
CREATED -> FAILED
CREATED -> CANCELED

WAITING_CUSTOMER_DATA -> CANCELED

CREATED -> PROCESSING
WAITING_CUSTOMER_DATA -> PROCESSING
WAITING_CUSTOMER_DATA -> COMPLETED
WAITING_CUSTOMER_DATA -> FAILED
WAITING_CUSTOMER_DATA -> CANCELED
WAITING_CUSTOMER_DATA -> REJECTED
PROCESSING -> COMPLETED
PROCESSING -> FAILED
PROCESSING -> CANCELED
PROCESSING -> REJECTED

Переходы в PROCESSING возможны только по provider callback/status, который явно означает processing/in-progress.

Final statuses не меняются автоматически.

Final statuses могут быть изменены только через manual correction.

Manual correction также может изменить non-final status, если user имеет permission.

20. Timeline Requirements ​

Transaction timeline должна сохранять:

  • transaction created;
  • status changed;
  • routing started;
  • waiting customer data started;
  • dynamic customer data submitted;
  • provider request sent;
  • provider payment URL received;
  • provider iframe opened or redirect used;
  • provider callback received;
  • provider callback ignored;
  • unknown provider status ignored;
  • expiration triggered;
  • manual correction performed;
  • manual correction reason/comment saved;
  • correction webhook resent;
  • correction webhook skipped by user decision;
  • final status reached.

21. Acceptance Criteria ​

Transaction lifecycle считается реализованным для MVP, если:

  • CREATED ставится сразу после успешного создания transaction.
  • Routing начинается после CREATED.
  • WAITING_CUSTOMER_DATA ставится, если нужны дополнительные customer attributes.
  • PROCESSING ставится только по provider callback/status, который явно означает processing/in-progress.
  • COMPLETED ставится по provider callback или manual correction.
  • FAILED ставится по provider callback, internal failed execution без fallback или manual correction.
  • CANCELED ставится по provider callback, expiration или manual correction.
  • REJECTED ставится по internal processing reasons или manual correction.
  • Final statuses: COMPLETED, FAILED, CANCELED, REJECTED.
  • Final statuses не меняются автоматически.
  • Любой transaction status можно изменить через manual correction с permission.
  • Manual correction требует reason/comment.
  • Manual correction всегда спрашивает user-а, нужно ли resend webhook.
  • Correction webhook содержит corrected: true.
  • Manual correction запрещена для migrated legacy read-only transactions.
  • Merchant webhooks отправляются на PROCESSING, если он пришел от provider как meaningful intermediate status.
  • Merchant webhooks отправляются на final statuses.
  • Отправка request в provider сохраняется как timeline event и не меняет transaction status на PROCESSING.
  • Provider pending status не используется как transition.
  • Unknown provider status сохраняется в timeline как ignored.
  • Callback после final status сохраняется в timeline как ignored.
  • Expiration стартует с момента transaction created.
  • Expiration default 30 минут и настраивается через environment variables.
  • Expiration может перевести промежуточные статусы transaction в CANCELED.
  • Timeline содержит previous status, new status, reason, source, actor и timestamp.
  • Отдельная status history table не требуется для MVP.