Payment Orchestrator

Тема

05.07 Payment Method / MID Configuration ​

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

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

Этот документ описывает Payment Method / MID configuration.

Payment Method / MID является merchant-level configuration, которую merchant использует в deposit request через:

text
paymentMethodId

Цель:

  • уйти от provider-centric модели;
  • сделать payment method business-centric;
  • дать merchant/platform users понятную настройку routing;
  • связать deposit request с конкретной merchant configuration.

2. Business method ​

Payment Method / MID создается под merchant и выбирает business method.

MVP business methods:

  • Cards;
  • Apple Pay;
  • Google Pay;
  • Sofort Uber;
  • BLIK;
  • Skrill;
  • Quick Checkout.

Generic APM не должен использоваться как отдельный business method.

Если метод относится к alternative payment methods, он все равно должен быть создан конкретным названием:

  • Skrill;
  • Quick Checkout;
  • другой конкретный method name.

В будущем список methods может расширяться.

3. paymentMethodId ​

Каждый Payment Method / MID имеет свой UUID:

text
paymentMethodId

Merchant передает paymentMethodId в:

text
POST /api/v2/deposit

Система использует paymentMethodId, чтобы найти merchant-level payment configuration и запустить routing.

4. Multiple configs per method ​

Один merchant может иметь несколько Payment Method / MID configurations для одного business method.

Пример:

text
Merchant A
- Cards EU
- Cards High Risk
- Cards VIP

Каждая configuration имеет отдельный paymentMethodId.

Merchant сам выбирает нужный paymentMethodId в deposit request.

5. Fields ​

Минимальные fields Payment Method / MID:

  • id / paymentMethodId;
  • merchantId;
  • name;
  • method;
  • status;
  • createdByType;
  • created at;
  • updated at.

name является единственным названием Payment Method / MID в MVP.

Отдельный displayName для Payment Method / MID в MVP не нужен.

name видят:

  • platform users с доступом;
  • merchant users с доступом.

Customer на hosted payment form не должен видеть name Payment Method / MID.

createdByType нужен, чтобы понимать, кто создал configuration:

  • platform;
  • merchant.

Method example values:

text
cards
apple_pay
google_pay
sofort_uber
blik
skrill
quick_checkout

apm не является допустимым value для method.

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

Если нужен другой method, нужно создать новую Payment Method / MID configuration.

Routing rules не являются простым field внутри Payment Method / MID.

Routing rules должны быть отдельной сущностью/таблицей, связанной с Payment Method / MID.

При создании Payment Method / MID routing blueprint может быть пустым draft.

Пустой draft нужен, чтобы user мог сначала создать configuration, а затем настроить routing.

Create flow requires:

  • merchant;
  • name;
  • method;
  • status.

List page shows Payment Method / MID configurations for all merchants available to user.

If user does not filter by merchant, the table shows all accessible merchants with pagination.

merchant name should always be shown in list table.

After successful creation, user should be redirected to Payment Method / MID details.

Publish Payment Method / MID без valid routing запрещен.

Payment Method / MID можно создать без routing blueprint.

Но Payment Method / MID нельзя активировать для processing, если routing blueprint пустой или не published.

UI must not allow status ACTIVE if Payment Method / MID has no valid published routing.

Если Payment Method / MID находится в active status, он должен иметь valid published routing blueprint.

6. Кто может создавать Payment Method / MID ​

Payment Method / MID может создавать:

  • platform user с permission;
  • merchant user с permission.

Platform user also creates Payment Method / MID from Merchant section, selecting merchant in create flow.

Merchant user может создавать configuration только в context merchant / merchant group, где у него есть соответствующий доступ.

Merchant user с permission может создать Payment Method / MID самостоятельно без участия platform user.

Platform user с permission может редактировать Payment Method / MID, созданный merchant user-ом.

Merchant user с permission может редактировать Payment Method / MID, созданный platform user-ом, с учетом visibility rules и доступных ему actions.

7. Blueprint / graph ​

При открытии Payment Method / MID user должен видеть routing blueprint / graph.

Blueprint должен показывать:

  • first-level routing rules;
  • MASTER MID GROUP targets;
  • MASTER MID внутри MASTER MID GROUP;
  • selection strategy MASTER MID GROUP;
  • fallback settings на доступном уровне;
  • status элементов;
  • merchant-visible configuration.

Если часть routing structure hidden/platform-created, merchant user не должен видеть internal details.

8. First-level routing ​

Первый уровень routing внутри Payment Method / MID состоит из rules.

Rules ведут на:

text
MASTER MID GROUP

MASTER MID GROUP содержит:

text
MASTER MID

MASTER MID GROUP is created inside Payment Method / MID routing blueprint.

MASTER MID GROUP does not require user-defined name in MVP.

UI can show system labels such as:

text
Group #1
Group #2

These labels are presentation labels, not business names.

Rule может быть:

  • country-based;
  • currency-based;
  • amount-based;
  • fallback/default rule.

Точный rule model описан в routing execution document.

9. Merchant editing rights ​

Merchant user с permission может:

  • видеть first-level routing rules;
  • создавать first-level routing rules;
  • редактировать first-level routing rules;
  • менять порядок rules;
  • подключать доступные MASTER MID GROUP / MASTER MID;
  • менять allowed selection/fallback settings, если permission позволяет.

Merchant user может подключать только те MASTER MID / MASTER MID GROUP, которые доступны этому merchant.

10. Platform editing rights ​

Platform user с permission может:

  • создавать Payment Method / MID для merchant;
  • редактировать Payment Method / MID;
  • управлять first-level routing;
  • подключать MASTER MID / MASTER MID GROUP;
  • видеть full configuration в рамках permissions;
  • управлять hidden/platform-created internals.

11. MASTER MID availability ​

Merchant user может подключить только те MASTER MID, которые доступны этому merchant.

Availability зависит от:

  • merchant context;
  • platform configuration;
  • permissions;
  • provider access, если применимо;
  • hidden/internal visibility rules.

Если MASTER MID создан platform user и доступен merchant-у только как high-level entity, merchant user может видеть его name/status и использовать в routing, но не видеть internal blueprint.

12. Inactive Payment Method / MID ​

Если Payment Method / MID inactive/deleted, deposit request с этим paymentMethodId должен быть rejected до создания transaction.

Это значит:

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

Причина:

  • payment method configuration недоступна еще до transaction lifecycle;
  • нет смысла создавать transaction, если requested payment method inactive.

Status Payment Method / MID могут менять:

  • platform user с permission;
  • merchant user с permission.

Если Payment Method / MID находится в status DELETED, historical transactions должны оставаться доступными для просмотра и расследования.

Payment Method / MID можно перевести в DELETED, даже если по нему уже есть transactions. Это soft-delete.

13. Publish validation ​

Payment Method / MID draft может быть пустым.

Published Payment Method / MID должен иметь structurally valid routing.

Empty routing blueprint нельзя publish как active routing.

Если user хочет сохранить незавершенную настройку, она должна оставаться draft / inactive configuration.

Нельзя publish Payment Method / MID, если:

  • нет ни одного valid Routing Rule;
  • нет fallback route;
  • Routing Rules не ведут к valid MASTER MID GROUP.

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

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

Validation errors должны быть показаны user-у на blueprint до publish.

14. Audit log ​

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

На странице Payment Method / MID должна быть вкладка Audit Logs.

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

  • created;
  • updated;
  • status changed;
  • soft-deleted;
  • first-level rule created;
  • first-level rule updated;
  • first-level rule deleted;
  • rule order changed;
  • MASTER MID GROUP connected/disconnected;
  • fallback settings changed;
  • actor;
  • timestamp;
  • merchant context.

15. Acceptance Criteria ​

Payment Method / MID Configuration считается согласованной для MVP, если:

  • Payment Method / MID создается под merchant.
  • Payment Method / MID выбирает business method: Cards, Apple Pay, Google Pay, Sofort Uber, BLIK, Skrill, Quick Checkout или другой конкретный method name.
  • Generic APM не является допустимым business method.
  • Payment Method / MID имеет UUID paymentMethodId.
  • Merchant передает paymentMethodId в /api/v2/deposit.
  • Один merchant может иметь несколько configs для одного business method.
  • Минимальные fields: merchantId, name, method, status, createdByType.
  • Create flow requires merchant, name, method and status.
  • List page shows all accessible merchants by default with pagination.
  • Merchant name is always shown in Payment Method / MID list.
  • After create user is redirected to Payment Method / MID details.
  • Отдельный displayName для Payment Method / MID в MVP не нужен.
  • Name видят platform users и merchant users с доступом.
  • Customer не видит Payment Method / MID name.
  • Method нельзя менять после создания.
  • CreatedByType хранит, кто создал configuration: platform или merchant.
  • Routing rules являются отдельной сущностью/таблицей, связанной с Payment Method / MID.
  • Payment Method / MID может быть создан с пустым draft blueprint.
  • Payment Method / MID нельзя publish без structurally valid routing.
  • UI must not allow status ACTIVE without valid published routing.
  • Payment Method / MID может создавать platform user с permission.
  • Payment Method / MID может создавать merchant user с permission.
  • Platform user creates Payment Method / MID from Merchant section and selects merchant in create flow.
  • Merchant user с permission может создать Payment Method / MID самостоятельно без участия platform user.
  • Platform user может редактировать merchant-created Payment Method / MID.
  • Merchant user может редактировать platform-created Payment Method / MID, если есть permission и visibility rules позволяют.
  • При открытии Payment Method / MID показывается blueprint/graph.
  • First-level routing rules ведут на MASTER MID GROUP.
  • MASTER MID GROUP is created inside Payment Method / MID blueprint.
  • MASTER MID GROUP does not require user-defined name.
  • MASTER MID GROUP может быть пустой.
  • Empty MASTER MID GROUP не блокирует publish.
  • Merchant user с permission может видеть и редактировать first-level rules.
  • Merchant user может подключать только доступные MASTER MID.
  • Если Payment Method / MID inactive/deleted, deposit request rejected без создания transaction.
  • Если Payment Method / MID deleted, historical transactions остаются доступными.
  • Payment Method / MID можно soft-delete, даже если по нему есть transactions.
  • Status Payment Method / MID могут менять platform user and merchant user с permission.
  • Payment Method / MID имеет Audit Logs tab.
  • Табличные metrics вроде transactions count / success rate не входят в MVP.
  • Изменения пишутся в audit log.

16. Open Questions ​

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

Technical/design follow-up:

  1. Определить exact method enum.
  2. Определить status values для Payment Method / MID.
  3. Описать validation для compatible MASTER MID / payment method.
  4. Определить exact publish validation messages.