03.03 Routing Execution

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

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

Этот документ описывает routing execution для deposit transaction.

Routing должен объяснять:

когда начинается routing;
какие уровни routing существуют;
как выбирается MASTER MID GROUP;
как выбирается MASTER MID;
как внутри MASTER MID выбирается SUB MID GROUP;
как внутри SUB MID GROUP выбирается SUB MID / SUB MID AGGREGATOR;
когда срабатывает fallback;
какие данные нужно сохранить в transaction timeline;
какую часть routing может видеть merchant user.

2. Главный принцип

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

Система должна быть event-oriented:

Merchant отправляет request на создание deposit.
Если все обязательные поля переданы, transaction создается.
Merchant получает hosted payment session URL.
Hosted payment form начинает polling transaction data.
Параллельно система обрабатывает transaction через routing flow.
Как только routing определил следующий action, hosted form получает это через polling и выполняет нужное действие.

Customer не должен видеть технический routing process. Для customer это выглядит как loading, форма для доп. данных или provider payment flow.

3. Routing Hierarchy

Целевая routing hierarchy:

text

Transaction
-> Payment Method configuration
-> first-level routing rules
-> MASTER MID GROUP
-> MASTER MID selection
-> MASTER MID blueprint rules
-> SUB MID GROUP
-> SUB MID / SUB MID AGGREGATOR selection
-> Provider execution

4. Payment Method Configuration

Transaction определяет, какая payment method configuration используется, через paymentMethodId.

После этого система загружает все данные, связанные с этой configuration:

first-level routing rules;
MASTER MID GROUP;
MASTER MID;
MASTER MID selection settings;
second-level routing rules внутри MASTER MID;
SUB MID GROUP;
SUB MID;
SUB MID AGGREGATOR;
fallback settings;
velocity limits;
provider method required attributes.

Routing использует только published versions configurations.

В transaction timeline нужно сохранить, какие configuration versions были фактически использованы.

5. First-Level Routing

First-level routing находится на уровне merchant payment method configuration.

В UI и product discussions это может называться rule, но для реализации и Back Office editor используется модель:

text

Routing Rule -> Conditions

Routing Rule ведет к одному target MASTER MID GROUP.

Conditions внутри одного Routing Rule работают через AND.

MVP rule attributes:

currency;
country;
amount.

В будущем rules могут отличаться в зависимости от payment method. Например, для card method можно будет добавить rule по card mask / BIN / bank identification.

Routing Rule Result

Один Routing Rule может направить transaction только на один MASTER MID GROUP.

Несколько Routing Rules могут направляться на один и тот же MASTER MID GROUP.

Routing Rule Evaluation

Routing Rules выполняются по sequence.

Если несколько Routing Rules подходят одновременно, выбирается первый Routing Rule по sequence.

Fallback Route

Fallback route настраивается отдельно от списка Routing Rules.

Fallback route указывает на MASTER MID GROUP и применяется, если ни один regular Routing Rule не matched.

Fallback route:

не является Rule без conditions;
не участвует в order/drag-and-drop regular rules;
может быть настроен или отсутствовать.

No Matching Rule

Если ни один Routing Rule не подошел и fallback route отсутствует:

transaction получает статус REJECTED;
hosted form должна показать customer-facing сообщение, что данный метод недоступен;
transaction timeline должна сохранить reason.

6. First-Level Routing Example

Пример first-level routing:

Rule #1: если customer country LV, LT, EE, направить на MASTER MID GROUP #1.
Rule #2: если customer country FI, направить на MASTER MID GROUP #2.
Fallback route: если ни один Rule не matched, направить на MASTER MID GROUP #3.

Если merchant передал в request customer.country = LV, transaction направляется на MASTER MID GROUP #1.

7. MASTER MID GROUP

MASTER MID GROUP может быть пустой.

MASTER MID GROUP может содержать один или несколько MASTER MID.

MASTER MID GROUP отвечает за выбор MASTER MID.

В MASTER MID GROUP можно настроить selection type:

sequence;
weight.

Fallback внутри MASTER MID GROUP должен быть поддержан.

Для MVP нужно поддержать оба selection types: sequence и weight.

Fallback включен по default, но его можно выключить.

При weight selection weights могут быть любыми положительными числами. Сумма weights не обязана быть 100, система считает распределение пропорционально.

Если MASTER MID GROUP пустая, group считается exhausted.

Если это возможно, routing продолжает fallback flow. Если fallback path недоступен, transaction становится REJECTED.

Если выбранный MASTER MID не смог успешно обработать transaction через свой internal routing, система может попробовать следующий MASTER MID в группе, если fallback включен.

8. MASTER MID

MASTER MID является merchant-scoped сущностью.

MASTER MID создается для конкретного merchant и конкретного payment method.

MASTER MID может быть создан:

platform user с permission в context конкретного merchant;
merchant user с permission, если ему выдан provider access и он может создавать provider-related configuration.

MASTER MID не является global/reusable сущностью.

Поля / настройки MASTER MID в MVP:

name;
payment method, например Cards, Sofort Uber, Apple Pay, Google Pay, BLIK;
status;
routing blueprint;
processing fee, planned/future configuration.

Processing fee на MASTER MID нужно учесть в модели, но конкретная детализация fee может быть описана отдельно в financial model.

MASTER MID Visibility

Если MASTER MID был создан platform user, внутреннее устройство этого MASTER MID не должно быть доступно merchant user.

Merchant user может видеть:

MASTER MID GROUP;
MASTER MID names;
настройки MASTER MID GROUP, которые разрешены для merchant visibility.

Merchant user не может видеть:

internal blueprint MASTER MID, если нет доступа;
SUB MID GROUP;
SUB MID;
SUB MID AGGREGATOR;
provider execution details.

9. MASTER MID GROUP Selection Example

Пример:

MASTER MID GROUP #1 содержит:

MASTER MID #1;
MASTER MID #2.

Разница между MASTER MID может быть, например, в Processing Fee.

В MASTER MID GROUP #1 настроен selection type sequence.

MASTER MID #1 находится первым в sequence.

Система выбирает MASTER MID #1.

Если дальше MASTER MID #1 не смог выполнить transaction и fallback включен, система может попробовать MASTER MID #2.

10. MASTER MID Blueprint

Внутри MASTER MID есть routing blueprint.

Routing Rules внутри MASTER MID направляют transaction на SUB MID GROUP.

Conditions внутри одного Routing Rule работают через AND.

Fallback route внутри MASTER MID настраивается отдельно от Routing Rules и указывает на SUB MID GROUP.

MVP rule attributes:

currency;
country;
amount.

Amount rules должны считаться через EUR base amount.

В будущем rules могут отличаться по payment method.

Например, для card method можно будет добавить rule, который смотрит на card mask / BIN и определяет банк.

MASTER MID Blueprint Example

Пример:

Rule #1: если amount <= 10 EUR, направить на SUB MID GROUP #1.
Fallback route: если ни один Routing Rule не подошел, направить на SUB MID GROUP #2.

Если transaction пришла на 20 USD, система конвертирует / сравнивает amount в base currency.

Например:

text

20 USD = 19.01 EUR

Так как 19.01 EUR больше 10 EUR, Rule #1 не подходит.

Fallback route направляет transaction на SUB MID GROUP #2.

11. SUB MID GROUP

SUB MID GROUP может быть пустой.

SUB MID GROUP может содержать:

SUB MID;
SUB MID AGGREGATOR.

SUB MID GROUP отвечает за выбор конкретной execution configuration.

Selection types внутри SUB MID GROUP:

sequence, то же самое что priority;
weight.

Fallback внутри SUB MID GROUP должен быть включен по умолчанию.

Для MVP нужно поддержать оба selection types: sequence и weight.

Fallback внутри SUB MID GROUP можно выключить.

Если SUB MID GROUP пустая, group считается exhausted.

Если это возможно, routing продолжает fallback flow. Если fallback path недоступен, transaction становится REJECTED.

12. SUB MID / SUB MID AGGREGATOR Selection

Пример:

SUB MID GROUP #2 содержит:

SUB MID #1;
SUB MID #2.

В настройках SUB MID GROUP #2 выбран selection type weight.

Вес:

SUB MID #1: 50%;
SUB MID #2: 50%.

Система случайно выбирает один SUB MID согласно весам.

Если выбранный SUB MID не может быть использован, система пробует следующий SUB MID / SUB MID AGGREGATOR согласно fallback logic.

13. Dynamic Attributes And Race Condition

Если выбранному SUB MID недостаточно attributes, система должна дособрать данные на hosted payment form.

Но есть потенциальная race condition:

Пока customer вводит недостающие данные, velocity limits или другие checks могут измениться, и выбранный SUB MID может перестать подходить.

Чтобы уменьшить риск этой проблемы, при выборе SUB MID GROUP система должна определить required attributes для всех SUB MID / SUB MID AGGREGATOR внутри этой SUB MID GROUP.

Hosted form должна дособрать у customer все attributes, которые могут понадобиться любому SUB MID / SUB MID AGGREGATOR внутри выбранной SUB MID GROUP.

После этого:

Customer отправляет все недостающие attributes.
Система повторно продолжает execution.
Если один SUB MID не проходит velocity limits или другую проверку, система может попробовать следующий SUB MID в этой же SUB MID GROUP без повторного запроса данных у customer.

14. Fallback Triggers

Fallback должен срабатывать при:

provider error;
provider timeout;
velocity exceeded;
SUB MID inactive;
SUB MID AGGREGATOR inactive.

Fallback должен быть включен по умолчанию на уровне SUB MID GROUP.

Fallback на уровне MASTER MID GROUP также должен поддерживаться, если MASTER MID не смог выполнить transaction через свой internal routing.

Если SUB MID / SUB MID AGGREGATOR был выключен после создания transaction, но до provider request, система должна пропустить этот candidate и продолжить fallback flow.

Если provider request уже был отправлен, transaction продолжает обрабатываться по уже начатому provider flow.

15. Fallback Flow

Если SUB MID failed и fallback включен:

Customer остается на той же hosted form.
Customer не должен знать, что конкретный provider ответил ошибкой.
Hosted form продолжает polling transaction data.
Система пробует следующий SUB MID / SUB MID AGGREGATOR.
Customer видит только loading или следующий provider/customer action.

Если все SUB MID / SUB MID AGGREGATOR в SUB MID GROUP не подошли:

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

16. Merchant Visibility

В Merchant section -> Payment Method / MID merchant user видит routing на уровне payment method.

Merchant user может видеть:

rules первого уровня;
MASTER MID GROUP, в которые направляют rules;
MASTER MID внутри MASTER MID GROUP;
MASTER MID names;
настройки MASTER MID GROUP;
selection type MASTER MID GROUP;
веса;
sequence;
fallback enabled/disabled.

Merchant user с соответствующей permission может менять:

first-level payment method rules;
selection type MASTER MID GROUP;
weights;
sequence;
fallback enabled/disabled.

Merchant user может редактировать second-level MASTER MID rules только если у него есть доступ создавать MASTER MID под конкретного provider/acquirer.

Merchant user не видит внутреннее устройство MASTER MID, если MASTER MID был создан platform user и merchant не имеет специального доступа.

Merchant user не видит:

internal MASTER MID blueprint;
SUB MID GROUP;
SUB MID;
SUB MID AGGREGATOR;
provider raw details;
provider errors.

17. Future Merchant-Created MASTER MID

В будущем возможен сценарий:

Merchant получает доступ к определенным providers.
Merchant user с нужными permissions может создать MASTER MID самостоятельно.
Внутри такого MASTER MID merchant user может создавать SUB MID GROUP и SUB MID, если у него есть доступ к provider.

Это не нужно полностью раскрывать в MVP, но архитектурно это нужно учитывать.

18. Timeline Requirements

Transaction timeline должна сохранять routing information для investigation.

Обязательно сохранять:

routing started;
payment method configuration selected;
payment method configuration version used;
first-level rule matched;
first-level routing version used;
selected MASTER MID GROUP;
MASTER MID GROUP version used;
selected MASTER MID;
MASTER MID version used;
MASTER MID selection strategy;
MASTER MID blueprint rule matched;
MASTER MID blueprint version used;
selected SUB MID GROUP;
SUB MID GROUP version used;
selected SUB MID / SUB MID AGGREGATOR;
selected SUB MID / SUB MID AGGREGATOR version used;
selected SUB MID / SUB MID AGGREGATOR execution snapshot;
SUB MID GROUP selection strategy;
fallback attempts;
fallback reasons;
velocity exceeded events;
provider error / timeout events;
route rejected reasons;
final routing failure reason.

Visibility In Timeline

Platform users с нужными permissions могут видеть полный routing trace.

Merchant users видят только тот уровень routing, который им разрешен.

Если MASTER MID создан platform user, merchant user не должен видеть:

какие SUB MID были выбраны;
какие SUB MID GROUP были выбраны;
какие internal provider settings применились;
какие provider errors произошли.

Merchant-facing timeline должна скрывать internal provider routing details, но все равно должна показывать понятное merchant-facing explanation.

Если routing failed из-за скрытой provider/internal причины, merchant user не должен видеть internal details. В таком случае merchant-facing UI должен предложить связаться с platform support.

19. Acceptance Criteria

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

Routing начинается сразу после создания transaction.
Hosted form получает routing result через polling.
First-level Routing Rules поддерживают currency, country, amount как condition attributes.
Conditions внутри одного Routing Rule работают через AND.
Routing Rules выполняются по sequence.
Один Routing Rule направляет transaction только на один MASTER MID GROUP.
Несколько Routing Rules могут направлять на один MASTER MID GROUP.
Fallback route на first-level routing настраивается отдельно и указывает на MASTER MID GROUP.
Если no matching Routing Rule and no fallback route, transaction становится REJECTED.
Если no matching Routing Rule and no fallback route, hosted form показывает customer-facing message, что метод недоступен.
MASTER MID GROUP выбирает MASTER MID по sequence или weight.
Weight selection поддерживается на уровне MASTER MID GROUP в MVP.
Weight values считаются пропорционально и не обязаны суммироваться до 100.
MASTER MID GROUP может быть пустой.
Empty MASTER MID GROUP считается exhausted at runtime.
MASTER MID содержит routing blueprint.
MASTER MID blueprint Routing Rules направляют transaction на SUB MID GROUP.
MASTER MID blueprint fallback route настраивается отдельно и указывает на SUB MID GROUP.
SUB MID GROUP выбирает SUB MID / SUB MID AGGREGATOR по sequence или weight.
Weight selection поддерживается на уровне SUB MID GROUP в MVP.
Weight values на SUB MID GROUP считаются пропорционально и не обязаны суммироваться до 100.
Fallback внутри SUB MID GROUP включен по умолчанию.
Fallback внутри SUB MID GROUP можно выключить.
SUB MID GROUP может быть пустой.
Empty SUB MID GROUP считается exhausted at runtime.
Fallback срабатывает на provider error, timeout, velocity exceeded, inactive SUB MID / SUB MID AGGREGATOR.
Если SUB MID / SUB MID AGGREGATOR стал inactive до provider request, routing пропускает этот candidate.
Если SUB MID GROUP failed полностью, текущий MASTER MID считается failed, и система возвращается на уровень MASTER MID GROUP fallback.
Hosted form не раскрывает customer provider errors.
Merchant user видит только разрешенный routing level.
Platform users с permissions видят полный routing trace.
Transaction timeline содержит matched rules, selected groups, selected MIDs, fallback attempts и rejection reasons.
Transaction timeline содержит фактически использованные configuration versions.
Amount rules считаются через EUR base amount.
Merchant user с permission может редактировать first-level payment method rules.
Merchant user может редактировать second-level MASTER MID rules только если у него есть доступ создавать MASTER MID под provider/acquirer.
Merchant-facing UI не раскрывает hidden provider/internal failure reason и предлагает обратиться в support.

03.03 Routing Execution ​

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

2. Главный принцип ​

3. Routing Hierarchy ​

4. Payment Method Configuration ​

5. First-Level Routing ​

Routing Rule Result ​

Routing Rule Evaluation ​

Fallback Route ​

No Matching Rule ​

6. First-Level Routing Example ​

7. MASTER MID GROUP ​

8. MASTER MID ​

MASTER MID Visibility ​

9. MASTER MID GROUP Selection Example ​

10. MASTER MID Blueprint ​

MASTER MID Blueprint Example ​

11. SUB MID GROUP ​

12. SUB MID / SUB MID AGGREGATOR Selection ​

13. Dynamic Attributes And Race Condition ​

14. Fallback Triggers ​

15. Fallback Flow ​

16. Merchant Visibility ​

17. Future Merchant-Created MASTER MID ​

18. Timeline Requirements ​

Visibility In Timeline ​

19. Acceptance Criteria ​

03.03 Routing Execution

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

2. Главный принцип

3. Routing Hierarchy

4. Payment Method Configuration

5. First-Level Routing

Routing Rule Result

Routing Rule Evaluation

Fallback Route

No Matching Rule

6. First-Level Routing Example

7. MASTER MID GROUP

8. MASTER MID

MASTER MID Visibility

9. MASTER MID GROUP Selection Example

10. MASTER MID Blueprint

MASTER MID Blueprint Example

11. SUB MID GROUP

12. SUB MID / SUB MID AGGREGATOR Selection

13. Dynamic Attributes And Race Condition

14. Fallback Triggers

15. Fallback Flow

16. Merchant Visibility

17. Future Merchant-Created MASTER MID

18. Timeline Requirements

Visibility In Timeline

19. Acceptance Criteria