Payment Orchestrator

Тема

03.13 Merchant, Brand And Payment Method Setup ​

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

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

Этот документ описывает setup journey, через который platform user или merchant user подготавливает merchant к приему deposits.

Цель journey: создать merchant, brand и Payment Method / MID configuration так, чтобы merchant мог отправить deposit request в Merchant API.

2. Actors ​

Platform user ​

Может создавать и настраивать merchants, brands, payment methods and routing, если имеет permissions.

Merchant user ​

Может создавать и настраивать merchant-scoped entities, если имеет доступ к merchant и нужные permissions.

3. High-level setup flow ​

Базовый setup flow:

  1. Создать merchant.
  2. Создать brand под merchant.
  3. Создать Payment Method / MID под merchant.
  4. Создать или подключить MASTER MID / MASTER MID GROUP.
  5. Настроить first-level routing blueprint.
  6. Publish Payment Method / MID configuration.
  7. Создать API key для merchant.
  8. Merchant может отправлять deposit request с paymentMethodId and brandId.

Готовность определяется фактической валидностью нужных entities and configurations.

4. Merchant creation ​

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

Required fields для MVP:

  • legal name;
  • trade name.
  • status;

Merchant создается сразу в status:

text
ACTIVE

Если platform user хочет временно остановить merchant processing, он может позже изменить status, если имеет permission.

5. Brand creation ​

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

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

Required fields для Brand MVP:

  • name;
  • status;
  • domain;

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

Deposit без brand невозможен.

Если merchant не создал brand, он не сможет создать валидный deposit request.

6. Payment Method / MID creation ​

Payment Method / MID создается вручную под merchant.

Required fields для MVP:

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

name видят platform users и merchant users с доступом.

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

createdByType хранит, кто создал configuration:

  • platform;
  • merchant.

method определяет business payment method, например:

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

Generic APM не используется как method. Для alternative payment methods нужно указывать конкретный method name.

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

После создания Payment Method / MID может иметь пустой draft blueprint.

Это позволяет создать configuration заранее и позже настроить routing.

7. Empty blueprint behavior ​

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

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

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

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

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

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

Иными словами:

text
empty draft allowed
empty published blueprint not allowed
empty MASTER MID GROUP allowed

8. Publishing validation ​

Перед publish система должна валидировать Payment Method / MID.

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

Если Payment Method / MID опубликован, но routing runtime не может найти подходящий route, transaction будет rejected по стандартному routing behavior.

В MVP не нужен отдельный warning/checklist на merchant details, который заранее говорит, что payment method “не готов”.

9. Status management ​

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

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

Если Payment Method / MID inactive:

  • deposit request с этим paymentMethodId rejected;
  • transaction не создается;
  • hosted payment URL не возвращается.

Если Payment Method / MID deleted:

  • deposit request с этим paymentMethodId rejected;
  • transaction не создается;
  • historical transactions остаются доступны для просмотра и расследования.

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

10. API key dependency ​

Для Merchant API deposit request merchant должен иметь active API key.

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

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

11. Acceptance Criteria ​

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

  • Merchant создается вручную.
  • Merchant required fields: name, status, legal name.
  • Merchant создается сразу ACTIVE.
  • Brand создается вручную отдельно.
  • Первый Brand не создается автоматически.
  • Brand required fields: name, status, domain.
  • brandId всегда обязателен в deposit request.
  • Deposit без brand невозможен.
  • Payment Method / MID создается вручную под merchant.
  • Payment Method / MID required fields: name, method, status, createdByType.
  • Customer не видит Payment Method / MID name.
  • Method нельзя менять после создания.
  • Payment Method / MID может быть soft-deleted, даже если по нему есть transactions.
  • Generic APM не является допустимым method value.
  • Payment Method / MID draft blueprint может быть пустым.
  • Payment Method / MID нельзя publish без structurally valid routing.
  • Payment Method / MID нельзя активировать для processing без valid published routing.
  • Empty MASTER MID GROUP не блокирует publish.
  • Payment Method / MID status могут менять platform user and merchant user с permission.
  • Deleted Payment Method / MID сохраняет доступность historical transactions.
  • Табличные metrics вроде transactions count / success rate не входят в MVP.
  • Merchant details checklist “ready / not ready” не входит в MVP.