Payment Orchestrator

Тема

08.05 Routing Rule Data Model ​

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

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

Этот документ описывает routing rule data model для MVP.

Routing rules используются на двух уровнях:

  • Payment Method / MID first-level routing;
  • MASTER MID second-level routing.

2. Routing levels ​

First-level routing ​

First-level routing находится внутри:

text
Payment Method / MID

Rule target:

text
MASTER MID GROUP

Fallback target:

text
MASTER MID GROUP

Second-level routing ​

Second-level routing находится внутри:

text
MASTER MID

Rule target:

text
SUB MID GROUP

Fallback target:

text
SUB MID GROUP

3. Routing Rule and Condition ​

В Back Office routing должен быть представлен как список Routing Rules.

Routing Rule - это маршрутная ветка, которая:

  • имеет order/sequence;
  • содержит один или несколько conditions;
  • ведет к одному target entity.

Condition - это одно условие внутри Routing Rule.

Если внутри Routing Rule несколько conditions, они работают через:

text
AND

Пример:

text
Rule #1
[
  customer.country in [LV, LT, EE]
  amount >= 100 EUR
]
-> MASTER MID GROUP #1

Это означает:

text
customer.country in [LV, LT, EE] AND amount >= 100 EUR

Если нужен OR, user создает несколько Routing Rules, которые могут вести к одному и тому же target.

4. Fallback route ​

Fallback больше не является отдельным Routing Rule без conditions.

Fallback route - это отдельная настройка routing blueprint level.

Fallback route:

  • хранится отдельно от ordered rules;
  • имеет один target;
  • используется только если ни один regular Routing Rule не matched;
  • может быть включен или не настроен;
  • не имеет conditions;
  • не участвует в drag-and-drop ordering regular rules.

На first-level routing fallback route указывает на:

text
MASTER MID GROUP

На MASTER MID routing fallback route указывает на:

text
SUB MID GROUP

5. Routing blueprint fields ​

Routing blueprint fields:

  • id;
  • routingLevel;
  • parentEntityId;
  • rules;
  • fallbackTargetType;
  • fallbackTargetId;
  • createdAt;
  • updatedAt.

Allowed routingLevel:

  • PAYMENT_METHOD;
  • MASTER_MID.

Если fallback не настроен:

text
fallbackTargetId = null

6. Routing Rule fields ​

Routing Rule fields:

  • id;
  • order;
  • conditions;
  • targetId;
  • targetType;
  • createdAt;
  • updatedAt.

Routing Rule не имеет:

  • status;
  • isFallback;

Routing Rule считается active, пока существует внутри active draft/published version.

Удаление Routing Rule должно быть soft/logical с audit log, если development team решит хранить deleted records.

7. Condition fields ​

Condition fields:

  • id;
  • attribute;
  • operator;
  • value;
  • createdAt;
  • updatedAt.

Condition не имеет отдельного target.

Target задается на уровне Routing Rule.

8. targetType ​

Allowed targetType depends on routing level.

For first-level routing:

text
MASTER_MID_GROUP

For second-level routing:

text
SUB_MID_GROUP

9. Conditions in MVP ​

MVP condition attributes:

  • customer.country;
  • amount;
  • currency.

Future condition attributes can be added later, for example:

  • card BIN / mask;
  • customer segment;
  • risk score;
  • provider capability;
  • merchant-specific attributes.

10. Amount condition ​

Amount condition compares amount in EUR base.

This means:

  • transaction original amount can be in any supported currency;
  • system calculates EUR equivalent;
  • amount routing condition uses EUR value.

Example:

text
Original amount: 20 USD
EUR base amount: 19.01 EUR
Condition: amount > 10 EUR
Result: matched

11. Currency condition ​

Currency condition compares original transaction currency.

Example:

text
Original currency: USD
Condition: currency in [USD, EUR]
Result: matched

12. Country condition ​

Country condition compares:

text
customer.country

This value comes from merchant deposit request.

If country is missing in merchant request, transaction should not be created because customer.country is a required request field.

13. Amount operators ​

Amount condition operators:

  • =;
  • >;
  • >=;
  • <;
  • <=;
  • between.

between should define inclusive/exclusive behavior in technical design.

Product recommendation:

text
between should be inclusive by default

14. Country/currency operators ​

Country and currency condition operators:

  • in;
  • not in.

Examples:

text
customer.country in [LV, LT, EE]
currency not in [USD]

15. Multiple conditions inside Routing Rule ​

One Routing Rule can have multiple conditions.

Example:

text
customer.country in [LV, LT]
AND amount >= 100 EUR
AND currency in [EUR, USD]

16. Routing Rule logic ​

Conditions inside one Routing Rule work as:

text
AND

All conditions must match for Routing Rule to match.

OR behavior can be represented by multiple Routing Rules.

Example:

text
Rule #1: country in [LV] -> target A
Rule #2: country in [LT] -> target A

17. Routing Rule evaluation order ​

Routing Rules execute by:

text
order

First matched Routing Rule wins.

If Rule #1 matches, system does not evaluate lower-priority rules for the same routing level.

Fallback route is evaluated only after all regular rules did not match.

18. No matched rule behavior ​

First-level routing ​

If no first-level Routing Rule matched and no fallback route exists:

text
Transaction -> REJECTED

Reason:

text
NO_MATCHING_ROUTING_RULE

or another error code from Error Dictionary.

MASTER MID routing ​

If no MASTER MID Routing Rule matched and no fallback route exists:

  • current MASTER MID is failed for this transaction;
  • system returns to MASTER MID GROUP;
  • if MASTER MID GROUP fallback is enabled, system tries next MASTER MID;
  • if no MASTER MID options remain, routing path is exhausted;
  • if no other routing paths exist, transaction becomes REJECTED.

19. Examples ​

Country Rule ​

json
{
  "order": 1,
  "conditions": [
    {
      "attribute": "customer.country",
      "operator": "in",
      "value": ["LV", "LT", "EE"]
    }
  ],
  "targetType": "MASTER_MID_GROUP",
  "targetId": "master-mid-group-1"
}

Amount Rule ​

json
{
  "order": 2,
  "conditions": [
    {
      "attribute": "amount",
      "operator": ">=",
      "value": {
        "amount": 100,
        "currency": "EUR"
      }
    }
  ],
  "targetType": "SUB_MID_GROUP",
  "targetId": "sub-mid-group-1"
}

Routing blueprint with fallback ​

json
{
  "routingLevel": "PAYMENT_METHOD",
  "rules": [
    {
      "order": 1,
      "conditions": [
        {
          "attribute": "customer.country",
          "operator": "in",
          "value": ["LV", "LT", "EE"]
        }
      ],
      "targetType": "MASTER_MID_GROUP",
      "targetId": "master-mid-group-1"
    },
    {
      "order": 2,
      "conditions": [
        {
          "attribute": "customer.country",
          "operator": "in",
          "value": ["FI"]
        }
      ],
      "targetType": "MASTER_MID_GROUP",
      "targetId": "master-mid-group-2"
    }
  ],
  "fallbackTargetType": "MASTER_MID_GROUP",
  "fallbackTargetId": "master-mid-group-fallback"
}

20. Validation rules ​

Routing validation:

  • regular Routing Rule must have at least one condition;
  • order required for each regular rule;
  • targetId required for each regular rule;
  • targetType required for each regular rule;
  • targetType must match routing level;
  • fallback target is optional;
  • if fallback target is configured, fallbackTargetType and fallbackTargetId are required;
  • fallback target type must match routing level;
  • fallback target entity must exist;
  • fallback route must not be stored as a regular rule;
  • condition attribute must be allowed for MVP;
  • condition operator must be allowed for attribute type;
  • amount condition must use EUR base;
  • currency condition uses original transaction currency;
  • country condition uses customer.country.

21. Blueprint UI behavior ​

Blueprint UI should show regular Routing Rules in order and fallback route as a separate block.

User should be able to:

  • add Routing Rule;
  • edit Routing Rule;
  • add conditions inside Routing Rule;
  • edit conditions inside Routing Rule;
  • reorder regular Routing Rules;
  • delete Routing Rule;
  • configure fallback route separately;
  • change fallback target;
  • clear fallback target;
  • see target entity;
  • see validation errors.

Fallback route should be visually separated from ordered Routing Rules.

Recommended UI concept:

text
Rules
  Rule #1 [conditions] -> target
  Rule #2 [conditions] -> target

Fallback
  If no rules matched -> fallback target

22. Audit log ​

Routing changes must be written to audit log.

Audit log should capture:

  • Routing Rule created;
  • Routing Rule updated;
  • Routing Rule deleted;
  • Routing Rule order changed;
  • condition inside Routing Rule changed;
  • target changed;
  • fallback target changed;
  • fallback target cleared;
  • actor;
  • timestamp;
  • routing level;
  • parent entity.

23. Acceptance Criteria ​

Routing Rule Data Model считается согласованной для MVP, если:

  • Routing Rules support two levels: Payment Method / MID and MASTER MID.
  • First-level routing rule targets MASTER MID GROUP.
  • First-level routing fallback target is MASTER MID GROUP.
  • Second-level routing rule targets SUB MID GROUP.
  • Second-level routing fallback target is SUB MID GROUP.
  • Routing blueprint fields include id, routingLevel, parentEntityId, rules, fallbackTargetType, fallbackTargetId, createdAt, updatedAt.
  • Routing Rule fields include id, order, conditions, targetId, targetType, createdAt, updatedAt.
  • Routing Rule has no status.
  • Routing Rule has no isFallback flag.
  • Condition fields include id, attribute, operator, value, createdAt, updatedAt.
  • MVP condition attributes include customer.country, amount, currency.
  • Amount condition compares EUR base amount.
  • Currency condition compares original transaction currency.
  • Country condition compares customer.country from merchant request.
  • Amount operators include =, >, >=, <, <=, between.
  • Country/currency operators include in, not in.
  • Routing Rule can have multiple conditions.
  • Conditions inside one Routing Rule work as AND.
  • Routing Rules execute by order.
  • First matched Routing Rule wins.
  • Fallback is a separate routing-level target, not a regular rule.
  • If no first-level Routing Rule matched and no fallback exists, transaction becomes REJECTED.
  • If no MASTER MID Routing Rule matched and no fallback exists, current MASTER MID failed and system returns to MASTER MID GROUP fallback.
  • Routing Rule and fallback target changes are written to audit log.

24. Open Questions ​

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

Technical/design follow-up:

  1. Определить exact Routing Rule / Condition JSON schema.
  2. Определить inclusive/exclusive behavior for between.
  3. Определить UI for Routing Rule reorder.
  4. Определить how deleted Routing Rules are stored.
  5. Определить validation error messages for blueprint UI.