Payment Orchestrator

Тема

05.01 Merchant, Brand And Merchant Group ​

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

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

Этот документ описывает базовые business entities:

  • Merchant;
  • Brand;
  • Merchant Group;

а также их связь с:

  • payment method configurations;
  • merchant API keys;
  • deposit request;
  • hosted payment form;
  • migration;
  • user access.

2. Merchant ​

Merchant является основной бизнес-сущностью, под которой создаются payment configurations и через которую merchant отправляет transactions.

Все основные payment-related configurations создаются в контексте merchant.

К merchant относятся:

  • brands;
  • payment method configurations;
  • API keys;
  • merchant users access;
  • transactions;
  • webhooks через transaction request;
  • audit logs;
  • migration targets.

3. Merchant fields ​

Минимальные поля Merchant для MVP:

  • id;
  • name;
  • status;
  • legal name;
  • merchant group;
  • created at;
  • updated at.

name является единственным display/business name Merchant в MVP.

Отдельный displayName для Merchant не нужен, потому что он дублирует name.

Required fields при создании Merchant:

  • name;
  • legal name;
  • status.

Дополнительные обязательные поля для Merchant в MVP не нужны.

Отдельный merchant-level externalId / code в MVP не нужен.

Отдельные поля на Merchant не нужны:

  • default currency;
  • country;
  • website/domain;
  • public name for hosted payment form.

Hosted payment form в MVP не показывает merchant public name.

Status должен позволять отключить merchant от активного processing.

Если Merchant находится в status INACTIVE, для processing автоматически недоступны:

  • brands этого merchant;
  • payment method configurations этого merchant;
  • merchant API keys;
  • создание новых deposit transactions.

Historical transactions остаются доступными для просмотра.

Existing transactions continue processing after merchant is disabled:

  • provider callbacks for already created transactions continue to be accepted/processed;
  • merchant webhook retries for already created transactions continue to be processed;
  • transaction details remain visible according to permissions.

При создании Merchant в MVP status по умолчанию:

text
ACTIVE

Точные status values нужно описать отдельно в domain dictionary.

4. Brand ​

Brand принадлежит одному merchant.

Один merchant может иметь много brands.

Brand создается вручную.

Система не должна автоматически создавать первый Brand при создании Merchant.

Brand используется в deposit request через:

text
brandId

Brand не является владельцем payment method configurations.

Payment method configurations создаются под merchant, а brandId в transaction request показывает, к какому brand относится конкретная transaction.

В будущем brandId будет использоваться для customization hosted payment form.

В MVP brand нужен, чтобы:

  • transaction была связана с конкретным brand;
  • merchant/platform users могли фильтровать transactions по brand;
  • hosted form могла понимать brand context;
  • migration могла переносить historical transactions на конкретный brand.

5. Brand fields ​

Минимальные поля Brand для MVP:

  • id;
  • merchant id;
  • name;
  • status;
  • domain;
  • created at;
  • updated at.

name является единственным display/business name Brand в MVP.

Отдельный displayName для Brand не нужен, потому что он дублирует name.

Required fields при создании Brand:

  • name;
  • domain;
  • status.

Дополнительные обязательные поля для Brand в MVP не нужны.

Один merchant может иметь несколько brands с одинаковым domain.

В MVP не нужно обязательно реализовывать полную style customization.

В будущем Brand может быть расширен полями:

  • logo;
  • primary color;
  • secondary color;
  • support email;
  • hosted form theme;
  • allowed domains;
  • localized names.

6. Payment configurations and Brand ​

Payment configurations создаются под merchant.

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

  • Payment Method / MID;
  • routing rules;
  • MASTER MID usage in merchant routing;
  • merchant-created SUB MID;
  • provider access in merchant context.

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

Brand не имеет собственного provider access.

Merchant group не имеет собственного provider access.

Brand не выбирает отдельную configuration напрямую.

Deposit request содержит:

  • merchant context through API key;
  • paymentMethodId;
  • brandId.

Система определяет payment configuration по merchant + paymentMethodId, а brandId сохраняется в transaction и используется для brand context.

7. brandId in deposit request ​

brandId обязателен в deposit request.

Если brandId не передан:

  • transaction не создается;
  • merchant получает validation error.

Если brandId не принадлежит merchant:

  • transaction не создается;
  • merchant получает validation error.

8. API keys ​

Merchant API keys создаются на уровне merchant.

API key не создается на brand.

Один merchant API key может использоваться для transactions по разным brands этого merchant-а.

При создании deposit request система должна проверить:

  • API key valid;
  • API key belongs to merchant;
  • brandId belongs to same merchant;
  • paymentMethodId belongs to same merchant context;
  • user/API key has required permissions, если такая модель будет применима.

9. Merchant Group ​

Merchant Group остается отдельной сущностью.

Merchant Group нужна для:

  • группировки merchants;
  • выдачи user access на группу merchants;
  • transaction filtering;
  • simplified access management.

Merchant Group в MVP не используется для:

  • общих processing settings;
  • общих routing settings;
  • fee settings;
  • shared payment configurations;
  • отдельного runtime status.

Merchant Group является grouping/access entity.

Один merchant может входить только в одну Merchant Group.

Merchant Group может создавать только platform user с соответствующей permission.

Добавлять merchant в Merchant Group и удалять merchant из Merchant Group может только platform user с соответствующей permission.

Один user может получить доступ:

  • к конкретному merchant;
  • к merchant group.

Если user имеет доступ к merchant group, он получает доступ к merchants внутри этой group согласно назначенной роли и permissions.

Если merchant добавили в Merchant Group или удалили из Merchant Group:

  • users с group access должны сразу получить или потерять доступ к этому merchant;
  • это автоматическое изменение access должно быть отражено в audit log.

10. Merchant Group fields ​

Минимальные поля Merchant Group для MVP:

  • id;
  • name;
  • description, если нужно;
  • created at;
  • updated at.

Merchant Group должна иметь связи:

  • group -> merchants;
  • group -> user access;
  • group -> access scope.

11. Brand visibility through Merchant Group ​

Если merchant user имеет доступ к merchant group, он видит brands всех merchants внутри этой group according to effective access model and permissions.

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

  • brand list может быть filtered by merchant;
  • transactions можно фильтровать по brands внутри доступных merchants;
  • user не видит brands merchants, к которым у него нет доступа.

12. Migration ​

При migration historical transactions нужно явно указывать target brand.

Система не должна автоматически создавать default brand для migrated transactions.

Migration input должен содержать:

  • source old merchantId / merchantConfigId;
  • target merchant;
  • target brandId;
  • target paymentMethodId.

Если target brandId не указан или невалиден:

  • migration не должна выполняться;
  • migration report должен показать validation error.

13. Audit log ​

Все изменения Merchant / Brand / Merchant Group должны попадать в audit log.

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

  • create;
  • update;
  • status change;
  • access assignment;
  • access removal;
  • merchant added to group;
  • merchant removed from group;
  • automatic access recalculation caused by merchant group membership change;
  • brand created;
  • brand updated;
  • brand disabled/enabled.

Audit visibility должна учитывать permissions и merchant / merchant group access.

14. Acceptance Criteria ​

Merchant / Brand / Merchant Group model считается согласованной для MVP, если:

  • Merchant является основной business entity.
  • Payment configurations создаются под merchant.
  • Merchant имеет fields: name, status, legal name.
  • Merchant не имеет отдельного displayName в MVP.
  • Дополнительные обязательные fields для Merchant в MVP не нужны.
  • Merchant-level externalId/code в MVP не нужен.
  • Merchant создается сразу ACTIVE.
  • INACTIVE Merchant автоматически отключает processing для его brands, payment methods, API keys и новых deposits.
  • Brand принадлежит одному merchant.
  • Merchant может иметь много brands.
  • Merchant может иметь несколько brands с одинаковым domain.
  • Brand создается вручную.
  • Первый Brand не создается автоматически.
  • Brand имеет fields: name, status, domain.
  • Brand не имеет отдельного displayName в MVP.
  • Дополнительные обязательные fields для Brand в MVP не нужны.
  • Brand не владеет payment method configurations.
  • brandId обязателен в deposit request.
  • brandId сохраняется в transaction.
  • brandId используется для hosted form brand context.
  • API keys создаются на merchant, не на brand.
  • Merchant API key может использоваться для всех brands merchant-а.
  • Merchant Group остается сущностью.
  • Merchant Group используется для grouping/access.
  • Один merchant может входить только в одну Merchant Group.
  • Merchant Group создают только platform users.
  • Merchants в Merchant Group добавляют/удаляют только platform users.
  • Изменение состава Merchant Group сразу влияет на group-based user access.
  • Автоматическое изменение user access из-за изменения состава Merchant Group пишется в audit log.
  • User с доступом к Merchant Group видит brands merchants внутри group, если permissions позволяют.
  • Migration требует явного target brandId.
  • Migration не создает default brand автоматически.
  • Все изменения пишутся в audit log.

15. Open Questions ​

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

Technical/design follow-up:

  1. Определить UI для merchant selector с brand filter.
  2. Определить migration input format и validation report.