Payment Orchestrator

Тема

08.02 Status Dictionary ​

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

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

Этот документ описывает statuses для MVP.

Status dictionary нужен, чтобы:

  • одинаково понимать lifecycle сущностей;
  • избежать разных названий одного и того же состояния;
  • согласовать final/non-final transaction statuses;
  • определить soft-delete поведение;
  • дать development/design team единый reference.

2. Общие принципы ​

Statuses должны быть:

  • явными;
  • ограниченными;
  • одинаково используемыми в API, Back Office и internal processing;
  • документированными;
  • не зависящими от provider-specific терминологии.

Provider statuses не используются напрямую как system statuses.

Provider statuses мапятся в internal statuses через provider adapter / error mapping / callback processing.

3. Transaction statuses ​

Transaction statuses:

text
CREATED
WAITING_CUSTOMER_DATA
PROCESSING
COMPLETED
FAILED
CANCELED
REJECTED

CREATED ​

Transaction создана в системе.

Routing начинается после создания transaction.

CREATED не означает, что request уже был отправлен provider-у.

WAITING_CUSTOMER_DATA ​

Transaction ожидает дополнительные customer attributes на hosted payment form.

Этот status используется, если:

  • transaction уже создана;
  • routing выбрал execution path / SUB MID GROUP;
  • для выбранных execution candidates нужны дополнительные customer attributes;
  • hosted form должна дособрать missing data.

PROCESSING ​

PROCESSING используется только когда provider callback/status означает, что payment operation находится в provider-side processing state.

Важно:

  • PROCESSING не ставится просто потому, что мы отправили request provider-у;
  • PROCESSING не ставится просто потому, что provider вернул payment URL;
  • PROCESSING сохраняет старый смысл: provider сообщил meaningful processing state.

Этот status может быть отправлен merchant-у webhook-ом.

COMPLETED ​

Transaction успешно завершена.

Обычно устанавливается по provider callback или manual correction.

FAILED ​

Transaction завершилась неуспешно.

Обычно устанавливается по provider callback, internal execution failure без fallback options, или manual correction.

CANCELED ​

Transaction была отменена.

Может быть установлена:

  • provider callback;
  • expiration logic;
  • manual correction.

REJECTED ​

Transaction была отклонена внутренней системой до успешного provider execution.

Примеры:

  • no routing path;
  • all fallback paths exhausted;
  • velocity rejected all paths;
  • payment method unavailable after creation;
  • internal business validation rejected transaction.

4. Transaction final statuses ​

Final statuses:

text
COMPLETED
FAILED
CANCELED
REJECTED

Final status не должен меняться автоматически.

Final status может быть изменен только manual correction user-ом с permission.

5. Merchant statuses ​

Merchant statuses:

text
ACTIVE
INACTIVE
DELETED

ACTIVE ​

Merchant доступен для нормальной работы.

INACTIVE ​

Merchant отключен.

Deposit requests для inactive merchant не должны обрабатываться.

Если merchant INACTIVE, для processing автоматически недоступны:

  • brands merchant-а;
  • payment methods merchant-а;
  • merchant API keys;
  • создание новых deposit transactions.

Это не обязательно означает автоматическое изменение status у связанных Brand / Payment Method / API Key records. Это runtime processing restriction на уровне merchant.

DELETED ​

Merchant soft-deleted из Back Office.

Физическая запись не удаляется.

DELETED используется для UI/business removal, сохраняя history, audit и linked records.

6. Brand statuses ​

Brand statuses:

text
ACTIVE
INACTIVE
DELETED

Если brand inactive/deleted:

  • новый deposit request с этим brandId не должен создавать transaction;
  • historical transactions должны оставаться доступными.

7. Payment Method / MID statuses ​

Payment Method / MID statuses:

text
ACTIVE
INACTIVE
DELETED

Если Payment Method / MID inactive/deleted:

  • deposit request с этим paymentMethodId rejected без создания transaction.
  • historical transactions остаются доступными для просмотра и расследования.

Payment Method / MID можно перевести в DELETED, даже если по нему уже есть transactions.

8. MASTER MID statuses ​

MASTER MID statuses:

text
ACTIVE
INACTIVE
DELETED

Если MASTER MID inactive/deleted:

  • routing должен пропустить его через MASTER MID GROUP fallback;
  • если fallback options закончились, transaction может стать REJECTED.
  • historical transactions остаются доступными для просмотра и расследования.

DELETED является soft-delete state.

MASTER MID можно перевести в DELETED, даже если по нему уже есть transactions.

9. SUB MID statuses ​

SUB MID statuses:

text
ACTIVE
INACTIVE
DELETED

Если SUB MID inactive/deleted:

  • provider request через него не выполняется;
  • fallback внутри SUB MID GROUP пробует следующий candidate.

DELETED является soft-delete state.

SUB MID можно перевести в DELETED, даже если по нему уже есть transactions.

Historical transactions должны оставаться доступными и показывать saved execution snapshot.

10. SUB MID AGGREGATOR statuses ​

SUB MID AGGREGATOR statuses:

text
ACTIVE
INACTIVE
DELETED

Если SUB MID AGGREGATOR inactive/deleted:

  • provider request через него не выполняется;
  • fallback внутри SUB MID GROUP пробует следующий candidate.

DELETED является soft-delete state.

SUB MID AGGREGATOR можно перевести в DELETED, даже если по нему уже есть transactions.

Historical transactions должны оставаться доступными и показывать saved execution snapshot.

11. API Key statuses ​

API Key statuses:

text
ACTIVE
REVOKED
EXPIRED

ACTIVE ​

API key может использоваться для request signing.

REVOKED ​

API key был revoked и перестает работать сразу.

EXPIRED ​

API key expired.

В MVP обычный active API key не имеет planned expiration date.

Но при rotation старый key после выбранного grace period автоматически становится EXPIRED.

12. User statuses ​

User statuses:

text
INVITED
ACTIVE
DISABLED
LOCKED
DELETED

INVITED ​

User создан/invited, но еще не завершил activation.

ACTIVE ​

User активен и может использовать Back Office.

DISABLED ​

User отключен admin-ом и не может login.

При переводе user-а в DISABLED система должна автоматически завершить все active sessions этого user-а.

User в status DISABLED можно вернуть обратно в ACTIVE, если admin имеет соответствующую permission.

LOCKED ​

User временно или вручную заблокирован из-за security reasons.

Примеры:

  • слишком много failed login attempts;
  • слишком много failed 2FA attempts;
  • suspicious activity;
  • manual lock by platform admin.

DELETED ​

User soft-deleted.

Физическая запись не удаляется.

При переводе user-а в DELETED система должна автоматически завершить все active sessions этого user-а.

User в status DELETED нельзя восстановить обратно в ACTIVE.

13. Invite statuses ​

Invite statuses:

text
PENDING
ACCEPTED
EXPIRED

PENDING ​

Invite создан и еще может быть использован.

ACCEPTED ​

User принял invite и завершил activation.

EXPIRED ​

Invite expired.

Expired invite можно отправить повторно через resend invite action, если actor имеет permission.

Отдельный invite status CANCELED в MVP не нужен.

14. Merchant Group statuses ​

Merchant Group не имеет status в MVP.

Причина:

  • Merchant Group используется для grouping/access;
  • один merchant может входить только в одну Merchant Group;
  • отключение processing должно происходить на уровне Merchant;
  • удаление group можно реализовать как soft-delete/archived record без отдельного runtime status;
  • status Merchant Group не влияет напрямую на transaction processing.

Если development team технически нужна отметка soft-delete, она не должна рассматриваться как product/runtime status для MVP.

15. Role statuses ​

Role statuses:

text
ACTIVE
INACTIVE
DELETED

ACTIVE ​

Role может быть назначена и использоваться.

INACTIVE ​

Role отключена.

Нельзя назначать inactive role новым users.

Если role переводится в INACTIVE, эта role должна быть удалена у users, которым она была назначена.

DELETED ​

Role soft-deleted.

Физическая запись не удаляется.

Если role переводится в DELETED, эта role должна быть удалена у users, которым она была назначена.

16. Soft-delete ​

Все удаления в Back Office должны быть soft-delete.

Физические записи не удаляются обычными Back Office actions.

DELETED status можно использовать для:

  • Merchant;
  • Brand;
  • Role;
  • Payment Method / MID;
  • MASTER MID;
  • SUB MID;
  • SUB MID AGGREGATOR;
  • User.

DELETED означает:

  • entity скрыта из normal active lists;
  • entity остается в database;
  • audit/history сохраняются;
  • historical transactions продолжают ссылаться на entity;
  • entity не должна использоваться для новых operations.

17. Status visibility ​

Status должен быть виден в Back Office там, где это помогает user-у понять availability entity.

Минимально status должен быть виден для:

  • Merchant;
  • Brand;
  • Payment Method / MID;
  • MASTER MID;
  • SUB MID;
  • SUB MID AGGREGATOR;
  • API Key;
  • User;
  • Role;
  • Transaction.

18. Acceptance Criteria ​

Status Dictionary считается согласованным для MVP, если:

  • Transaction statuses: CREATED, WAITING_CUSTOMER_DATA, PROCESSING, COMPLETED, FAILED, CANCELED, REJECTED.
  • Final transaction statuses: COMPLETED, FAILED, CANCELED, REJECTED.
  • PROCESSING используется только при meaningful provider processing status.
  • Merchant statuses: ACTIVE, INACTIVE, DELETED.
  • Brand statuses: ACTIVE, INACTIVE, DELETED.
  • Payment Method / MID statuses: ACTIVE, INACTIVE, DELETED.
  • MASTER MID statuses: ACTIVE, INACTIVE, DELETED.
  • SUB MID statuses: ACTIVE, INACTIVE, DELETED.
  • SUB MID AGGREGATOR statuses: ACTIVE, INACTIVE, DELETED.
  • API Key statuses: ACTIVE, REVOKED, EXPIRED.
  • User statuses: INVITED, ACTIVE, DISABLED, LOCKED, DELETED.
  • Invite statuses: PENDING, ACCEPTED, EXPIRED.
  • Merchant Group не имеет product/runtime status в MVP.
  • Role statuses: ACTIVE, INACTIVE, DELETED.
  • Все удаления в Back Office являются soft-delete.
  • DELETED используется как soft-delete status там, где применимо.

19. Open Questions ​

Product open questions отсутствуют.

Technical/design follow-up:

  1. Определить exact status transition rules для non-transaction entities.
  2. Определить UI behavior для DELETED entities.
  3. Определить UI behavior для role removal после INACTIVE/DELETED role.
  4. Определить lock/unlock flow для User status LOCKED.
  5. Определить whether Merchant Group needs technical deleted flag outside product status.