03.14 MASTER MID And SUB MID Setup

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

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

Этот документ описывает setup journey для MASTER MID, SUB MID GROUP, SUB MID и SUB MID AGGREGATOR.

Цель journey: подготовить execution layer, чтобы Payment Method / MID routing мог привести transaction к реальному provider execution.

2. Основной MVP подход

В MVP основной flow является platform-operated.

Обычно platform user создает:

• MASTER MID под merchant;
• MASTER MID blueprint;
• SUB MID GROUP внутри MASTER MID;
• SUB MID под merchant;
• подключение SUB MID / SUB MID AGGREGATOR в SUB MID GROUP.

Merchant self-service creation of MASTER MID должен быть доступен, если merchant имеет provider access and user has permissions.

Merchant user сможет создавать provider-related configuration, если:

• merchant получил provider access;
• user имеет нужные permissions;
• configuration не является platform-hidden.

3. Provider access

Provider access не является обязательным prerequisite для platform user.

Platform user может создать hidden SUB MID под merchant даже если merchant не имеет provider access.

Provider access нужен для merchant self-service сценариев:

• merchant user видит provider details;
• merchant user может создать SUB MID;
• merchant user может управлять credentials/config;
• merchant user может видеть больше provider-related information.

Provider access выдается на уровне merchant к конкретному provider.

Если merchant получил access к provider, merchant user с нужными permissions видит все provider methods этого provider при создании SUB MID.

Provider access не выдается отдельно на brand, merchant group, user или provider method.

Provider access можно revoke.

После revoke:

• уже созданные SUB MID этого provider остаются active;
• merchant user больше не видит provider details по этим SUB MID;
• merchant user больше не может создать новый SUB MID этого provider;
• routing не отключается автоматически.

Provider access grant/revoke должен попадать в audit log.

Provider access управляется на странице merchant details.

В Merchant section отдельная страница Provider Access не нужна.

Если provider access не выдан, merchant user видит blackbox / placeholder там, где это требуется для high-level routing visibility.

4. Setup order

Строгий порядок создания MASTER MID и SUB MID не важен.

Возможные варианты:

1. Сначала создать SUB MID / SUB MID AGGREGATOR, потом создать MASTER MID и подключить candidates.
2. Сначала создать MASTER MID, потом внутри него создать SUB MID GROUP и подключить candidates.

Но MASTER MID не имеет практического смысла, если в его routing нет SUB MID GROUP.

Publish MASTER MID routing требует structurally valid path to SUB MID GROUP.

SUB MID GROUP может быть пустой и это не блокирует publish.

Если runtime routing попадет в пустую SUB MID GROUP, group считается exhausted и transaction продолжит fallback flow или станет REJECTED, если fallback path недоступен.

5. MASTER MID creation

MASTER MID создается под конкретного merchant.

Required fields для MVP:

• name;
• method;
• status;
• createdByType.

MASTER MID всегда привязан к одному method.

method нельзя изменить после создания MASTER MID.

MASTER MID также содержит / поддерживает:

• processing fee configuration;
• routing blueprint;
• owner type: platform-created / merchant-created;
• visibility rules.

Processing fee относится к MASTER MID.

Processing fee может быть пустой.

Если processing fee настроена, все transactions, которые проходят через этот MASTER MID, должны получить processing fee according to its configuration.

Processing fee оплачивает merchant.

6. MASTER MID blueprint

MASTER MID blueprint может быть создан как draft.

MASTER MID может быть создан без published routing blueprint.

Внутри MASTER MID blueprint можно создать:

• Routing Rules;
• Conditions внутри Routing Rule;
• SUB MID GROUP targets.

SUB MID GROUP создается на странице MASTER MID под merchant.

В SUB MID GROUP можно добавить:

• SUB MID;
• SUB MID AGGREGATOR;
• SUB MID and SUB MID AGGREGATOR одновременно.

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

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

У SUB MID GROUP нет обязательного name в MVP.

Required settings SUB MID GROUP:

• selectionStrategy;
• fallbackEnabled.

SUB MID GROUP поддерживает selectionStrategy:

• sequence;
• weight.

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

Для weight strategy weights могут быть любыми положительными числами и считаются пропорционально.

7. SUB MID creation

SUB MID создается отдельно в Merchant section -> SUB MID.

После создания SUB MID можно подключить в SUB MID GROUP внутри MASTER MID blueprint.

Required fields для SUB MID MVP:

• name;
• provider;
• provider method;
• method;
• status;
• credentials/config;
• createdByType.

provider и provider method нельзя изменить после создания SUB MID.

Если нужно использовать другой provider или другой provider method, user должен создать новый SUB MID.

SUB MID также поддерживает дополнительные настройки:

• currency conversion / FX;
• conversion fee;
• velocity limits;
• expiration time;
• email replacement / fake email generation;
• method-specific secret/settings fields, если provider method этого требует.

Эти настройки не являются отдельными mandatory fields для создания каждого SUB MID, но должны быть поддержаны моделью и UI.

Credentials/config SUB MID:

• показываются как обычные inputs при создании;
• secret values шифруются после сохранения;
• secret values нельзя повторно увидеть после сохранения;
• secret можно только заменить новым введенным значением;
• non-secret config fields могут быть повторно открыты после сохранения user-ом с permission и visibility access;
• non-secret config fields показывают старые значения при редактировании;
• имеют version/history;
• не требуют OTP / 2FA confirmation при изменении;
• не поддерживают rollback к старой version в MVP.

Audit log должен фиксировать факт изменения credentials/config и changed field names, но не должен хранить old/new secret values.

8. Required attributes

Required and optional attributes для provider method задаются в коде provider adapter.

Они не настраиваются вручную в Back Office в MVP.

Обязательные поля для создания deposit задаются отдельно на уровне Merchant Deposit API DTO.

Provider adapter не должен дублировать deposit DTO required fields как отдельную merchant-required модель.

Если provider method требует дополнительные customer attributes, система должна:

1. определить missing attributes через provider adapter;
2. перевести provider-specific field names в canonical attribute names;
3. дособрать missing attributes через hosted payment form;
4. сохранить collected attributes в transaction customer context;
5. продолжить provider execution.

Provider adapter также должен описывать config fields, которые Back Office показывает при создании SUB MID / SUB MID AGGREGATOR:

• secret required;
• secret optional;
• non-secret required;
• non-secret optional;
• boolean;
• enum/select;
• string/text;
• number;
• URL.

9. Platform-created hidden configuration

Если SUB MID создан platform user:

• merchant user может видеть только placeholder / blackbox, если это нужно для high-level routing visibility;
• merchant user не видит provider credentials;
• merchant user не видит provider-sensitive settings;
• merchant user не видит internal routing details;
• platform user с permission видит full configuration.

Platform-created hidden SUB MID может использоваться внутри hidden MASTER MID blueprint.

10. Merchant-created SUB MID self-service scenario

Merchant user может создать SUB MID только если:

• merchant имеет access к этому provider;
• user имеет permission создавать SUB MID;
• user имеет permission видеть/управлять provider configuration;
• provider self-service включен для этого сценария.

SUB MID self-service должен быть поддержан в MVP, даже если основной operational flow на старте будет platform-operated.

11. SUB MID AGGREGATOR

SUB MID AGGREGATOR является platform-level/global execution configuration.

SUB MID AGGREGATOR:

• создается только platform user-ом;
• может переиспользоваться между merchants;
• может быть подключен только platform user-ом;
• использует ту же provider execution модель, что SUB MID;
• отличается от SUB MID атрибутом aggregator = true и ownership scope.

Required fields для SUB MID AGGREGATOR такие же, как для SUB MID:

• name;
• provider;
• provider method;
• method;
• status;
• credentials/config;
• createdByType.

provider и provider method нельзя изменить после создания SUB MID AGGREGATOR.

Credentials/config SUB MID AGGREGATOR:

• показываются как обычные inputs при создании;
• secret values шифруются после сохранения;
• secret values нельзя повторно увидеть после сохранения;
• secret можно только заменить новым введенным значением;
• non-secret config fields могут быть повторно открыты после сохранения platform user-ом с permission;
• non-secret config fields показывают старые значения при редактировании;
• имеют version/history;
• не требуют OTP / 2FA confirmation при изменении;
• не поддерживают rollback к старой version в MVP.

Merchant user не видит credentials/config SUB MID AGGREGATOR.

12. Soft-delete and historical transactions

SUB MID и SUB MID AGGREGATOR можно soft-delete, даже если по ним есть transactions.

Soft-deleted execution configuration:

• не используется для новых provider requests;
• пропускается через fallback, если routing до нее дошел;
• остается доступной в historical transaction details через saved execution snapshot.

Historical transaction должна показывать execution snapshot, который был использован на момент выполнения transaction, даже если SUB MID / SUB MID AGGREGATOR позже был удален или credentials/config изменились.

Provider-sensitive snapshot fields должны быть скрыты от merchant users без provider access and permission.

13. Acceptance Criteria

MASTER MID / SUB MID setup считается согласованным для MVP, если:

• Основной MVP flow: platform user создает provider-related configuration.
• MASTER MID может создать platform user с permission.
• MASTER MID может создать merchant user с permission, если merchant имеет provider access.
• Provider access не обязателен для platform-created hidden SUB MID.
• Provider access выдается на уровне merchant к конкретному provider.
• Если merchant получил provider access, он видит все provider methods этого provider.
• Provider access можно revoke.
• После revoke существующие SUB MID остаются active, но provider details скрываются от merchant users.
• Provider access grant/revoke пишется в audit log.
• Platform user может создать hidden SUB MID под merchant.
• Strict creation order MASTER MID / SUB MID не важен.
• MASTER MID required fields: name, method, status, createdByType.
• MASTER MID всегда привязан к одному method.
• Method нельзя менять после создания MASTER MID.
• MASTER MID поддерживает processing fee configuration.
• Processing fee на MASTER MID может быть пустой.
• MASTER MID может быть создан без published routing blueprint.
• MASTER MID publish требует structurally valid path to SUB MID GROUP.
• SUB MID GROUP создается внутри MASTER MID blueprint.
• SUB MID GROUP может быть пустой и published пустой.
• SUB MID GROUP required settings: selectionStrategy, fallbackEnabled.
• SUB MID GROUP поддерживает sequence и weight.
• SUB MID GROUP fallback включен по default и может быть выключен.
• SUB MID GROUP weights считаются пропорционально и не обязаны суммироваться до 100.
• Один SUB MID может быть добавлен в несколько SUB MID GROUP внутри одного merchant.
• SUB MID создается отдельно в Merchant section -> SUB MID.
• SUB MID подключается в SUB MID GROUP внутри MASTER MID blueprint.
• SUB MID required fields: name, provider, provider method, method, status, credentials/config, createdByType.
• SUB MID provider нельзя менять после создания.
• SUB MID provider method нельзя менять после создания.
• SUB MID поддерживает FX / conversion fee.
• SUB MID поддерживает email replacement / fake email generation.
• Secret values SUB MID шифруются и не раскрываются после сохранения.
• Secret SUB MID можно только заменить новым введенным значением.
• Non-secret config fields SUB MID можно повторно открыть после сохранения, если user имеет permission и visibility access.
• Merchant user может видеть non-secret config и менять secret values только у merchant-created SUB MID.
• SUB MID credentials/config имеют version/history.
• Provider-specific required customer attributes задаются в коде provider adapter.
• Merchant user может создать SUB MID только если merchant имеет provider access and user has permissions.
• Platform-created SUB MID отображается merchant user-у как placeholder/blackbox.
• SUB MID AGGREGATOR создается только platform user-ом.
• SUB MID AGGREGATOR всегда global/reusable.
• SUB MID AGGREGATOR использует ту же provider execution модель, что SUB MID.
• SUB MID AGGREGATOR required fields: name, provider, provider method, method, status, credentials/config, createdByType.
• SUB MID AGGREGATOR provider нельзя менять после создания.
• SUB MID AGGREGATOR provider method нельзя менять после создания.
• Secret values SUB MID AGGREGATOR шифруются и не раскрываются после сохранения.
• Secret SUB MID AGGREGATOR можно только заменить новым введенным значением.
• Non-secret config fields SUB MID AGGREGATOR можно повторно открыть после сохранения platform user-ом с permission.
• SUB MID AGGREGATOR credentials/config имеют version/history.
• Rollback credentials/config к старой version в MVP не нужен.
• OTP / 2FA confirmation для изменения credentials/config не нужен.
• Audit log не хранит old/new secret values.
• SUB MID и SUB MID AGGREGATOR можно soft-delete даже если по ним есть transactions.
• Historical transactions показывают execution snapshot, даже если SUB MID / SUB MID AGGREGATOR удален или credentials/config изменены.
• Deleted MASTER MID сохраняет historical transactions доступными.