Payment Orchestrator

Тема

03.08 Velocity Limits ​

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

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

Этот документ описывает, как в новой системе должны работать velocity limits для deposit transactions.

Velocity limits нужны, чтобы ограничивать количество или сумму transactions / attempts по заданным условиям и не отправлять transaction в provider configuration, если она нарушает установленные лимиты.

Velocity limits являются частью routing execution и могут влиять на fallback.

2. Где настраиваются velocity limits ​

Velocity limits настраиваются на уровне:

  • SUB MID;
  • SUB MID AGGREGATOR.

Velocity limits не настраиваются напрямую на уровне Payment Method / MID или MASTER MID.

3. Кто может настраивать velocity limits ​

Velocity limits может настраивать:

  • platform user с соответствующей permission;
  • merchant user с соответствующей permission, если он сам создал соответствующий SUB MID.

Если SUB MID / SUB MID AGGREGATOR создан platform user и скрыт от merchant, merchant user не может настраивать его velocity limits.

SUB MID AGGREGATOR является platform-level configuration. Его может создавать и настраивать только platform user с permission.

4. Что можно ограничивать ​

Система должна поддерживать следующие типы velocity rules:

  • count successful transactions;
  • count failed transactions;
  • sum successful amount;
  • sum failed amount;
  • count all attempts.

Под successful transactions понимаются transactions со статусом:

text
COMPLETED

Под failed transactions для velocity purposes нужно учитывать transactions, которые завершились неуспешно.

Минимально:

text
FAILED
REJECTED
CANCELED

Точное соответствие transaction statuses и velocity counters должно быть подтверждено в technical design.

5. Dimensions ​

Velocity limits считаются на уровне:

  • SUB MID / SUB MID AGGREGATOR;
  • customer.

Customer-level velocity должен использовать данные customer из transaction context.

Минимально customer identity должна поддерживать:

  • customer user ID;
  • customer email;
  • customer IP;
  • customer country.

Для MVP продуктово фиксируем, что velocity считается по customer. Точный technical key для customer-level aggregation должен быть описан разработчиками, чтобы избежать разного поведения для разных providers.

6. Amount currency ​

Для amount-based velocity rules сумма должна приводиться к EUR base.

Это значит, что если transaction создана в другой валюте, система должна использовать EUR equivalent для проверки velocity limits.

Пример:

text
Transaction amount: 20 USD
EUR equivalent: 19.01 EUR
Velocity rule: max successful amount 2000 EUR / 1 day
System checks 19.01 EUR against this rule.

7. Time windows ​

Velocity time window должен быть custom.

Platform user или merchant user с permission должен иметь возможность задать period, например:

  • 1 hour;
  • 1 day;
  • 7 days;
  • 30 days;
  • другое custom значение, если UI и backend это поддерживают.

Time window должен быть rolling window, если техническая команда не предложит другой подход и он будет согласован.

8. Как velocity участвует в routing ​

Velocity check выполняется после того, как routing выбрал candidate SUB MID / SUB MID AGGREGATOR, но до отправки request в provider.

Если selected SUB MID / SUB MID AGGREGATOR не проходит velocity check:

  1. Система записывает velocity rejection в transaction timeline.
  2. Система проверяет, включен ли fallback на уровне SUB MID GROUP.
  3. Если fallback включен, система пробует следующий available SUB MID / SUB MID AGGREGATOR в этой SUB MID GROUP.
  4. Если fallback выключен, текущий routing path считается failed.

9. Если все SUB MID в группе отбиты velocity ​

Если все SUB MID / SUB MID AGGREGATOR внутри SUB MID GROUP были rejected из-за velocity:

  1. Текущий MASTER MID считается failed для этой transaction.
  2. Система возвращается на уровень MASTER MID GROUP.
  3. Система проверяет, включен ли fallback на уровне MASTER MID GROUP.
  4. Если fallback включен и есть другой available MASTER MID, система пробует следующий MASTER MID.
  5. Если fallback выключен или подходящих MASTER MID больше нет, routing path считается exhausted.
  6. Если больше нет доступных routing paths, transaction получает статус:
text
REJECTED

Это поведение должно быть consistent с общим routing fallback flow.

10. Visibility для merchant users ​

Merchant user может видеть, что transaction была rejected из-за velocity, если у него есть permission смотреть transaction details / timeline.

Merchant user видит:

  • status;
  • internal error code;
  • human-readable description;
  • merchant-safe timeline event о velocity rejection.

Merchant user не должен видеть подробную internal/provider-sensitive информацию, если она относится к скрытому SUB MID / SUB MID AGGREGATOR или platform-created routing internals.

Пример merchant-safe description:

text
Transaction was rejected because velocity limit was exceeded.

11. Visibility для platform users ​

Platform user с permission должен видеть подробности velocity rejection.

Platform view должна показывать:

  • какой SUB MID / SUB MID AGGREGATOR проверялся;
  • какая velocity rule сработала;
  • какой counter был рассчитан;
  • какой threshold был установлен;
  • какой time window применялся;
  • какие transaction attributes использовались для проверки;
  • было ли fallback continuation;
  • какой следующий routing path был выбран.

12. Velocity usage / counters в Back Office ​

Back Office должен показывать velocity usage / current counters.

Это нужно, чтобы support и admins могли понять:

  • почему transaction была rejected;
  • насколько близко customer / SUB MID находится к лимиту;
  • какие limits реально влияют на traffic;
  • нужно ли изменить configuration.

Минимально UI должен показывать:

  • active velocity rules;
  • current usage for selected rule;
  • threshold;
  • remaining allowance, если это возможно;
  • time window;
  • reset / window boundary information, если это применимо к выбранной модели расчета.

13. Timeline events ​

Transaction timeline должна фиксировать velocity-related events:

  • velocity check started;
  • velocity rule evaluated;
  • velocity passed;
  • velocity rejected;
  • fallback after velocity rejection;
  • all candidates rejected by velocity;
  • transaction rejected because no available routing path remained.

Merchant-safe timeline может показывать simplified events.

Platform timeline должна показывать full details.

14. Error mapping ​

Если transaction rejected из-за velocity, merchant должен получить unified error code и human-readable description.

Provider raw error в этом случае отсутствует, потому что request к provider не отправляется.

Пример:

text
errorCode: VELOCITY_LIMIT_EXCEEDED
description: Transaction was rejected because velocity limit was exceeded.

Точный code dictionary должен быть описан отдельно в Error Mapping document.

15. Audit log ​

Любые изменения velocity configuration должны попадать в audit log.

Audit log должен фиксировать:

  • кто изменил velocity rule;
  • когда изменил;
  • какую сущность изменил;
  • old value;
  • new value;
  • context: platform / merchant;
  • affected SUB MID / SUB MID AGGREGATOR.

Если merchant user изменяет velocity rule на своем SUB MID, это также должно быть видно platform users с permission.

16. Acceptance Criteria ​

Velocity limits считаются реализованными для MVP, если:

  • Velocity limits можно настроить на SUB MID.
  • Velocity limits можно настроить на SUB MID AGGREGATOR.
  • Platform user с permission может настраивать velocity limits.
  • Merchant user с permission может настраивать velocity limits только на SUB MID, который он сам создал.
  • SUB MID AGGREGATOR настраивается только platform users с permission.
  • Система поддерживает count successful transactions.
  • Система поддерживает count failed transactions.
  • Система поддерживает sum successful amount.
  • Система поддерживает sum failed amount.
  • Система поддерживает count all attempts.
  • Amount-based checks считаются в EUR base.
  • Time window можно настроить custom.
  • Velocity check выполняется до provider request.
  • Если velocity exceeded, система пробует fallback внутри SUB MID GROUP, если fallback включен.
  • Если вся SUB MID GROUP отбита, система возвращается на уровень MASTER MID GROUP и пробует следующий MASTER MID, если fallback включен.
  • Если доступных routing paths больше нет, transaction становится REJECTED.
  • Timeline фиксирует velocity checks and rejections.
  • Merchant user видит, что rejection произошел из-за velocity, но без скрытых provider/internal details.
  • Platform user видит detailed velocity rejection reason.
  • Back Office показывает velocity usage / current counters.
  • Изменения velocity configuration пишутся в audit log.