Payment Orchestrator

Тема

05.14 SUB MID Credentials And Config UX ​

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

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

Этот документ описывает UX и product rules для credentials/config у:

  • SUB MID;
  • SUB MID AGGREGATOR.

Важно: secret fields и non-secret config fields обрабатываются по-разному.

Все secret values должны быть зашифрованы и никогда не должны раскрываться в UI, API responses, audit logs, exports, system logs или transaction details после сохранения.

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

2. Core rule ​

При создании SUB MID / SUB MID AGGREGATOR secret fields показываются как обычные inputs, чтобы user мог ввести значение.

После сохранения secret value становится write-only:

  • сохраненное secret value нельзя повторно увидеть;
  • сохраненное secret value нельзя вернуть через API;
  • сохраненное secret value нельзя экспортировать;
  • в UI можно показать только placeholder/masked state, например configured;
  • изменить secret можно только вводом нового значения.

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

Если user хочет изменить secret:

  • старое secret value не показывается;
  • user вводит новое secret value;
  • после сохранения создается новая config version/history record.

Если user хочет изменить non-secret config field:

  • старое значение показывается;
  • user редактирует значение;
  • после сохранения создается новая config version/history record.

3. Field visibility ​

Все non-secret fields и настройки SUB MID / SUB MID AGGREGATOR должны быть доступны для просмотра и редактирования пользователю, если выполняются условия доступа.

Это относится к:

  • non-secret config fields;
  • provider account identifiers;
  • method-specific settings;
  • expiration time;
  • email replacement setting;
  • velocity limits;
  • FX / conversion fee.

Secret fields доступны только для ввода нового значения.

Исключение для non-secret fields: fields скрываются, если user не имеет permission или entity visibility не позволяет видеть эти данные.

4. SUB MID visibility ​

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

Merchant user может видеть non-secret config и изменять secret values только если:

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

Merchant user не видит credentials/config у platform-created hidden SUB MID.

5. SUB MID AGGREGATOR visibility ​

SUB MID AGGREGATOR является platform-only reusable configuration.

Credentials/config SUB MID AGGREGATOR может видеть/изменять только platform user с соответствующими permissions.

Даже platform user не может повторно увидеть сохраненные secret values.

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

6. Permissions ​

Для просмотра non-secret config и masked/placeholder state secret fields используются permissions:

text
can_view_sub_mid_credentials
can_view_sub_mid_aggregator_credentials

Для редактирования non-secret config и замены secret values используются permissions:

text
can_edit_sub_mid_credentials
can_edit_sub_mid_aggregator_credentials

Permission сама по себе недостаточна. Всегда также применяются:

  • user type;
  • merchant access;
  • provider access;
  • entity ownership/visibility rules.

7. Version history ​

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

Version history нужен, чтобы:

  • понимать, какая encrypted config version была использована в historical transaction;
  • расследовать проблемы после изменения credentials;
  • видеть, кто и когда изменил config;
  • корректно отображать execution snapshot.

При каждом изменении credentials/config система должна создать новую version/history record.

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

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

8. Rollback ​

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

Если user хочет вернуть старое secret value, он должен ввести его заново и сохранить новую version.

Система не должна раскрывать старую secret version для rollback.

9. OTP / 2FA confirmation ​

Дополнительный OTP / 2FA confirmation для изменения SUB MID credentials/config в MVP не нужен.

Достаточно:

  • authenticated session;
  • permission;
  • entity visibility access;
  • audit log.

OTP / 2FA confirmation остается обязательным для отдельных security-sensitive flows, например API key rotation/revoke, если это описано в соответствующем документе.

10. Audit log ​

Изменение credentials/config должно попадать в audit log.

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

  • entity type: SUB MID или SUB MID AGGREGATOR;
  • entity id;
  • action: credentials/config updated;
  • changed field names;
  • actor;
  • timestamp;
  • merchant context, если применимо;
  • config version before;
  • config version after.

Audit log не должен хранить old value или new value secret fields.

Для secret fields audit log должен показывать только:

text
field updated

Для non-secret fields audit log может показывать change metadata, если это безопасно и соответствует общим audit log rules.

11. Acceptance Criteria ​

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

  • Secret fields при создании показываются как обычные inputs.
  • Secret values шифруются.
  • После сохранения secret values нельзя повторно увидеть никому.
  • Secret values нельзя возвращать через API, exports, audit logs, system logs или transaction details.
  • Secret можно только заменить новым введенным значением.
  • Старое secret value не показывается при редактировании.
  • 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, если имеет provider access and permission.
  • Merchant user не видит credentials/config platform-created hidden SUB MID.
  • Merchant user не видит credentials/config SUB MID AGGREGATOR.
  • Platform user с permission может видеть non-secret config и менять secret values SUB MID AGGREGATOR.
  • 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 пишет факт изменения и field names.
  • Audit log не хранит old/new secret values.

12. Open Questions ​

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

Technical/design follow-up:

  1. Определить encryption/storage approach для credentials/config.
  2. Определить exact secret field schema format в provider adapter.
  3. Определить UI pattern для отображения secret fields.
  4. Определить config versioning model.