05.10 SUB MID

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

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

Этот документ описывает SUB MID.

SUB MID является merchant-scoped provider method configuration, через которую система выполняет transaction в provider.

SUB MID используется как candidate внутри SUB MID GROUP.

2. SUB MID ownership

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

SUB MID не является reusable между merchants.

Если нужна reusable provider configuration, используется:

SUB MID AGGREGATOR

SUB MID AGGREGATOR создается через Platform section и может переиспользоваться между merchants только platform users.

Product-level distinction:

SUB MID: aggregator = false
SUB MID AGGREGATOR: aggregator = true

Provider execution model у SUB MID и SUB MID AGGREGATOR одинаковая.

Merchant user не может создавать, редактировать или самостоятельно добавлять SUB MID AGGREGATOR.

3. Provider and provider method

При создании SUB MID user выбирает:

• provider;
• provider method.

Пример:

Provider: Interkassa
Provider method: Cards
SUB MID: Interkassa Cards Merchant A

SUB MID должен использоваться только в routing для compatible payment method.

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

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

4. Fields

Required fields SUB MID для MVP:

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

SUB MID нельзя создать без required credentials/config.

SUB MID нельзя сохранить как inactive, если required provider config / credentials fields не заполнены.

Если user не знает required credentials/config, SUB MID creation должен быть blocked validation error.

Technical/system fields:

• id;
• merchantId;
• created by;
• aggregator = false;
• created at;
• updated at.

Configurable settings SUB MID:

• method-specific secret/settings fields, если нужны;
• expiration time;
• email replacement setting;
• velocity limits;
• FX / conversion fee.

Configurable settings не обязательно должны быть заполнены при создании каждого SUB MID, но модель и UI должны поддерживать их настройку.

Это правило не относится к required provider credentials/config fields.

Required provider credentials/config fields обязательны при создании SUB MID.

Create flow requires:

• merchant;
• name;
• provider;
• provider method;
• status;
• required credentials/config.

Provider method is selected from code registry after provider selection.

If required config/credentials are missing, save must be blocked by validation error.

5. Кто может создавать SUB MID

В MVP основной flow: SUB MID обычно создает platform user в context конкретного merchant.

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

• platform user с permission в context конкретного merchant;
• merchant user с permission, если ему выдан provider access.

Provider access не является prerequisite для platform user.

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

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

6. Platform-created SUB MID

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

• SUB MID принадлежит merchant context;
• platform user может скрыть details от merchant users;
• merchant user не видит credentials/config;
• merchant user не видит provider-sensitive settings;
• merchant user может видеть только merchant-safe placeholder/high-level entity, если это нужно для routing visibility.

Platform-created SUB MID может использоваться внутри MASTER MID blueprint, который скрыт от merchant user.

7. Merchant-created SUB MID

Если SUB MID создает merchant user:

• merchant user должен иметь provider access;
• merchant user должен иметь permission создавать SUB MID;
• merchant user может указать credentials/config;
• merchant user может настраивать velocity limits;
• merchant user может настраивать FX / conversion fee;
• merchant user может настраивать expiration time;
• merchant user может видеть и редактировать credentials/config только для merchant-created SUB MID, если имеет provider access and permission.

Platform user с permission может видеть и управлять merchant-created SUB MID.

8. Status and fallback

SUB MID имеет status.

Если SUB MID inactive:

1. SUB MID не используется для provider request.
2. Timeline фиксирует skipped/inactive SUB MID.
3. Если fallback внутри SUB MID GROUP включен, система пробует следующий candidate.
4. Если fallback выключен или candidates закончились, SUB MID GROUP failed.

Если SUB MID переведен в DELETED:

• это soft-delete;
• реальные записи не удаляются из базы;
• SUB MID не используется для новых provider requests;
• historical transactions остаются доступными;
• transaction details должны показывать execution snapshot, который был использован на момент выполнения transaction.

Existing transactions continue processing after SUB MID is disabled or soft-deleted.

SUB MID details should include Linked MASTER MID tab showing where this SUB MID is used in MASTER MID / SUB MID GROUP routing.

9. Expiration time

Expiration time хранится на SUB MID.

Expiration time определяет, сколько transaction/payment session может находиться в non-final state для этого provider method execution.

Если transaction expired:

• transaction может перейти в CANCELED;
• timeline фиксирует expiration;
• merchant webhook отправляется, если status change требует webhook.

Exact expiration behavior должен соответствовать transaction lifecycle document.

10. Email replacement

Email replacement является настройкой на SUB MID.

Если email replacement включен:

• real customer email из transaction context заменяется перед provider request;
• provider получает replacement email;
• original customer email сохраняется в нашей системе;
• merchant-facing data не должна искажаться;
• timeline/platform view должны показывать, что email replacement был применен, если permission позволяет.

Эта настройка нужна, если provider integration требует скрыть или заменить real customer email.

11. Credentials/config visibility and editing

Secret fields при создании SUB MID показываются как обычные inputs.

После сохранения secret values шифруются и больше никогда не раскрываются.

Старые secret values не показываются при редактировании.

Secret можно только заменить новым введенным значением.

Non-secret config fields можно повторно открыть, увидеть и отредактировать, если user имеет permission и visibility access.

Platform user с permission может видеть non-secret config и менять secret values любого SUB MID в platform scope.

Merchant user может видеть non-secret config и менять secret values только у merchant-created SUB MID, если:

• SUB MID принадлежит merchant context, к которому user имеет access;
• merchant имеет provider access;
• user имеет permission смотреть / редактировать credentials/config.

Merchant user не видит credentials:

• platform-created SUB MID;
• SUB MID AGGREGATOR;
• hidden/internal provider configurations;
• provider configs, к которым ему не выдан access.

Credentials/config должны иметь version/history.

Historical transaction должна ссылаться на credentials/config version, которая использовалась во время provider execution.

Historical transaction не должна раскрывать secret values.

Rollback credentials/config к старой version в MVP не нужен.

OTP / 2FA confirmation для изменения SUB MID credentials/config в MVP не нужен.

Audit logs, exports и system logs не должны хранить old/new secret values ни в открытом, ни в masked, ни в encrypted виде.

12. Supported currencies / countries

Supported currencies / countries не нужно хранить на SUB MID в MVP.

Причина:

• provider conditions often change;
• договоренности могут меняться часто;
• хранение таких данных в конфигурации быстро устаревает;
• routing rules уже управляют country/currency/amount на уровне payment configuration.

Если в будущем потребуется формализовать provider capabilities, это должно быть отдельным requirement.

В MVP supported currencies/countries являются operational agreement и не являются structured field на SUB MID.

13. Timeline

Transaction timeline должна фиксировать SUB MID events:

• SUB MID selected;
• SUB MID skipped because inactive;
• SUB MID credentials/config loaded;
• SUB MID required attributes checked;
• email replacement applied;
• expiration time applied;
• velocity checked;
• FX/conversion fee calculated;
• provider request sent through SUB MID;
• SUB MID failed;
• fallback to next candidate.

Merchant-safe timeline должна скрывать provider-sensitive details.

14. Historical execution snapshot

При provider execution система должна сохранить snapshot использованной SUB MID configuration.

Snapshot нужен, чтобы historical transaction оставалась понятной даже если после этого:

• SUB MID был удален через soft-delete;
• credentials/config были изменены;
• SUB MID был отключен;
• SUB MID был удален из SUB MID GROUP;
• routing blueprint был переопубликован.

Snapshot должен включать merchant-safe и platform-safe данные отдельно.

Минимальный snapshot:

• SUB MID id;
• SUB MID name;
• aggregator = false;
• provider;
• provider method;
• method;
• version/config version used, если используется versioning;
• masked credentials/config reference;
• applied expiration time;
• applied email replacement flag;
• applied velocity limits reference;
• applied FX/conversion fee reference.

Merchant user не должен видеть provider-sensitive snapshot fields, если у него нет provider access and permission.

15. Audit log

Изменения SUB MID должны попадать в audit log.

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

• SUB MID created;
• SUB MID updated;
• SUB MID status changed;
• credentials/config updated;
• expiration time changed;
• email replacement setting changed;
• velocity limits changed;
• FX/conversion fee changed;
• SUB MID soft-deleted;
• actor;
• timestamp;
• merchant context.

provider и provider method не должны попадать в audit log как changed fields, потому что они immutable после создания.

16. Acceptance Criteria

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

• SUB MID всегда создается под конкретного merchant.
• SUB MID не reusable между merchants.
• SUB MID имеет aggregator = false.
• SUB MID и SUB MID AGGREGATOR используют одинаковую provider execution модель.
• SUB MID отличается от SUB MID AGGREGATOR ownership scope и aggregator = false.
• SUB MID required fields: name, provider, provider method, method, status, credentials/config, createdByType.
• SUB MID create flow requires merchant, name, provider, provider method, status and required credentials/config.
• Provider method is selected from code registry after provider selection.
• SUB MID нельзя создать без required credentials/config.
• Save is blocked if required credentials/config are missing.
• SUB MID нельзя сохранить inactive, если required credentials/config не заполнены.
• provider нельзя изменить после создания SUB MID.
• provider method нельзя изменить после создания SUB MID.
• Merchant user может создать SUB MID только если merchant имеет access к этому provider and user has permissions.
• SUB MID AGGREGATOR создается через Platform section.
• SUB MID AGGREGATOR имеет aggregator = true.
• SUB MID AGGREGATOR может переиспользоваться между merchants только platform users.
• SUB MID можно soft-delete даже если по нему есть transactions.
• Historical transactions показывают SUB MID execution snapshot, даже если SUB MID удален или credentials/config изменены.
• Merchant user не может самостоятельно добавлять SUB MID AGGREGATOR.
• SUB MID выбирает provider и provider method.
• SUB MID содержит name, provider, provider method, method, status, credentials/config, createdByType.
• SUB MID содержит expiration time.
• SUB MID содержит email replacement setting.
• SUB MID поддерживает velocity limits.
• SUB MID поддерживает FX / conversion fee.
• Platform user может создать SUB MID в context merchant и скрыть детали от merchant user.
• Provider access не обязателен для platform-created hidden SUB MID.
• Merchant user может создать SUB MID, если ему выдан provider access.
• Основной MVP flow: SUB MID создает platform user.
• Merchant-created SUB MID поддерживается в MVP, если merchant имеет provider access and user has permissions.
• Secret values шифруются и не раскрываются после сохранения.
• Secret можно только заменить новым введенным значением.
• Non-secret config fields можно повторно открыть после сохранения, если user имеет permission и visibility access.
• Merchant user может видеть non-secret config и менять secret values только у merchant-created SUB MID.
• Platform user с permission может видеть non-secret config и менять secret values любого SUB MID.
• Credentials/config имеют version/history.
• Historical transaction ссылается на credentials/config version used.
• Historical transaction не раскрывает secret values.
• Rollback credentials/config к старой version в MVP не нужен.
• OTP / 2FA confirmation для изменения SUB MID credentials/config не нужен.
• Audit log не хранит old/new secret values.
• Если SUB MID inactive, fallback внутри SUB MID GROUP пробует следующий candidate.
• Existing transactions continue processing after SUB MID disable.
• SUB MID details contains Linked MASTER MID tab.
• Expiration time хранится на SUB MID.
• Email replacement заменяет real customer email перед provider request.
• Merchant user видит credentials только у SUB MID, который сам создал и имеет permission видеть.
• Supported currencies/countries не хранятся на SUB MID в MVP.
• SUB MID changes пишутся в audit log.

17. Open Questions

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

Technical/design follow-up:

1. Определить exact status values for SUB MID.
2. Определить provider method config schema.
3. Определить credentials encryption/storage and UI placeholder strategy.
4. Определить email replacement generation/storage strategy.
5. Описать validation for SUB MID compatibility with payment method.