Payment Orchestrator MVP Product Docs

Статус: рабочий пакет product documentation для обсуждения

1. Назначение папки

Эта папка содержит русскоязычные product documents для новой версии Payment Orchestrator.

Документы нужны, чтобы:

зафиксировать product decisions;
описать user journeys;
описать domain model;
подготовить основу для дизайна;
подготовить основу для technical design и будущей декомпозиции задач.

Этот пакет не является:

финальным backlog;
готовой нарезкой tickets;
финальным technical design;
оценкой сроков разработки;
инструкцией по delivery process.

Сейчас основная задача пакета - объяснить команде, какой продукт мы делаем, какие flows должны работать, какие сущности есть в системе и какие product decisions уже приняты.

Сначала все документы пишутся на русском. Английская версия будет подготовлена отдельно после стабилизации содержания.

2. Как использовать этот пакет

Команде нужно использовать этот пакет как основу для product validation:

проверить, что scope MVP понятен одинаково всем;
проверить terminology и naming;
пройтись по основным user journeys;
найти противоречия в routing, statuses, webhooks, permissions, visibility rules;
выписать open questions, которые нужно закрыть до technical design;
после согласования использовать документы как входные данные для design, technical design и tickets.

Обязательный review от команды

Каждый участник команды должен пройтись по всей спецификации и оставить feedback по каждой странице / главе.

Feedback нужно оставлять в этом Google Doc:

Payment Orchestrator MVP Specification Review

По каждой странице / главе нужно оставить сообщение в одном из двух форматов:

Reviewed / Approved - если страница просмотрена и вопросов или замечаний нет;
Reviewed / Questions - если есть вопросы, замечания, несогласие, missing cases или предложения.

Если есть вопросы или замечания, их нужно писать рядом с названием соответствующей страницы / главы, чтобы Product Owner мог пройтись по ним и обновить спецификацию.

3. Рекомендуемые маршруты чтения

Product Owner / Business / Management

Development / Tech Lead

Design / UX

QA

DevOps / Operations

4. Быстрый глоссарий

Merchant - клиент платформы, который создает deposits через Merchant API и работает с Back Office.
Brand - бренд внутри Merchant. В deposit request brandId обязателен.
Merchant Group - группировка merchants для access model и операционного управления.
Payment Method / MID - merchant-level конфигурация платежного метода, например Cards, Apple Pay, Google Pay, Sofort Uber, BLIK.
MASTER MID GROUP - группа MASTER MID, в которой выбирается MASTER MID по sequence/weight.
MASTER MID - финансово-бизнесовый уровень execution, на котором применяется processing fee и настраивается second-level routing.
SUB MID GROUP - группа execution-конфигураций, из которой выбирается SUB MID или SUB MID AGGREGATOR.
SUB MID - provider configuration под конкретного merchant.
SUB MID AGGREGATOR - reusable provider configuration, созданная platform user и доступная для использования платформой между merchants.
Provider - реальный платежный провайдер. Merchant users не должны видеть реальные названия provider без специального access.
Provider Access - доступ merchant к конкретному provider, который выдает platform user.
Routing Rule - правило рутинга с набором Conditions, которые работают через AND.
Condition - одно условие внутри Routing Rule, например country, amount или currency.
Fallback route - отдельная fallback-настройка blueprint, которая используется, если ни один Routing Rule не подошел.
Hosted Payment Page - наша страница оплаты, которая открывается customer по hosted payment URL.
Transaction Timeline - история событий transaction для investigation.
API Key - merchant secret для подписи API requests.
Webhook - callback, который система отправляет merchant на URLs, переданные при создании transaction.

5. Полный порядок чтения

Step 1. Общий контекст

Начать отсюда:

Эти документы объясняют:

почему нужна новая версия;
какие проблемы есть в текущей системе;
что входит в MVP;
кто основные users/actors;
как работает access model на верхнем уровне.

Step 2. Deposit user journeys

Дальше читать use cases:

Эти документы описывают полный transaction flow:

platform/merchant user настраивает merchant, brand and payment method;
platform user настраивает MASTER MID / SUB MID execution layer;
merchant создает deposit;
customer открывает hosted payment form;
routing выбирает execution path;
provider callback меняет status;
user с permission может выполнить manual transaction correction;
merchant получает webhook;
support/platform/merchant расследуют transaction через timeline.

Step 3. Functional use cases

После основных flow читать:

Эти документы описывают:

velocity limits;
FX / conversion fee / processing fee;
unified error mapping;
migration old transactions;
draft / publish / versioning lifecycle для configurations;
MVP release and merchant transition.

Step 4. Back Office

Back Office structure:

Документ описывает:

общий Back Office для platform users и merchant users;
left menu;
Platform section;
Merchant section;
merchant selector/filter;
основные MVP pages;
visual routing blueprint editor;
Routing Rule / Conditions UX;
draft / publish / version panel UX для routing.
page-by-page requirements;
table columns, filters, actions and tabs;
empty states and confirmation dialogs.

Step 5. Domain model

Domain documents:

Эти документы описывают основные сущности системы:

Merchant;
Brand;
Merchant Group;
API Key;
User/Auth/Session;
Role/Permission;
Audit Log;
Provider integration;
Payment Method / MID;
MASTER MID;
MASTER MID GROUP;
SUB MID GROUP;
SUB MID;
SUB MID AGGREGATOR;
Test Provider / Sandbox.

Step 6. Observability

Monitoring and operations:

06-observability-and-operations/01-monitoring-metrics-alerts.md

Документ описывает:

Prometheus metrics;
alerts;
success rate monitoring;
webhook failures;
suspicious provider callbacks;
internal ops scope.

Step 7. API contracts

Public API contracts:

Документ описывает:

POST /api/v2/deposit;
required fields;
API key signature;
duplicate transaction handling;
hosted payment URL response;
validation behavior.
merchant webhook payload schema;
webhook event types;
HMAC webhook signature requirement;
webhook delivery success criteria.

Step 8. Dictionaries

Dictionaries:

Документ описывает:

permission naming;
transaction permissions;
webhook permissions;
merchant / user / role permissions;
API key permissions;
payment/routing permissions;
provider access permission;
velocity / FX / fee permissions;
system settings permissions.
transaction statuses;
entity statuses;
final statuses;
soft-delete / DELETED behavior.
error codes;
error categories;
recommended HTTP statuses;
merchant/platform/customer error visibility.
canonical customer attributes;
canonical payment/request attributes;
hosted form dynamic attributes;
provider adapter field mapping.
routing rule fields;
routing conditions/operators;
fallback route behavior;
first-level and second-level routing targets.

Step 9. Testing and Quality

Testing and release quality:

09-testing-and-quality/01-test-strategy-and-definition-of-done.md

Документ описывает:

test strategy;
unit tests;
E2E tests;
contract tests;
provider adapter tests;
load/performance tests;
resilience tests;
permissions/visibility tests;
secret leakage tests;
release blockers;
Definition of Done.

Step 10. Technical Architecture

Technical architecture:

Документ описывает:

existing network diagram;
public actors;
Cloudflare WAF / External HTTPS Load Balancer / GKE Gateway API;
Forms Service;
Merchant Gateway;
Backoffice Gateway;
Provider Gateway;
Payment Service as diagram label;
Orchestrator Service naming decision;
Exchange Service;
Report Service;
Pub/Sub;
PostgreSQL / PgBouncer / Read Replica;
Redis;
Cloud Storage;
Observability;
monorepo direction;
deployable services;
gateway responsibilities;
outbox/inbox explanation;
Pub/Sub topics/events explanation;
async deposit/callback/webhook event flow;
failed events and dead-letter concept;
environments: local/dev/stg/prod;
sandbox/test provider inside stg;
test provider availability in prod;
merchant documentation base URLs;
API keys and webhook signing per environment;
2FA requirements by environment;
no transaction environment field;
no maintenance banner in MVP;
no mandatory PO deploy approval gate.

Step 11. Data Requirements

Product-level data requirements:

Документ описывает:

transaction data requirements;
merchant/customer request context;
customer data;
FX snapshot;
provider references;
corrected marker;
legacy marker;
legacy metadata approach;
routing result summary;
transaction visibility;
transaction list/search/export data;
data ownership;
secret/sensitive data rules;
configuration snapshots;
historical version visibility;
routing/fee/FX/velocity snapshots;
raw provider payloads;
merchant webhook payloads/responses;
payload visibility;
payload retention;
timeline payload references;
audit/security events;
actor IP/user agent;
old/new values for non-secret changes;
audit/security retention and export.

Step 12. Merchant Documentation

Merchant-facing public documentation requirements:

12-merchant-documentation/01-merchant-public-documentation-requirements.md

Документ описывает:

public documentation portal;
documentation owner;
Merchant API documentation scope;
HMAC request signing examples;
webhook signature validation examples;
transaction statuses documentation;
error code documentation;
sandbox/test flow documentation;
what is not mandatory in MVP.

Step 13. Gap Review and Next Actions

Optional internal review for core team:

13-gap-review/01-final-gap-review-and-next-actions.md

Документ описывает:

какие product decisions уже закрыты;
что еще нужно Product Owner-у;
что нужно от design team;
что нужно от development team;
что нужно от DevOps;
что нужно от QA;
что нужно от security;
что не входит в MVP;
recommended next steps;
ownership matrix;
remaining gaps before design / technical design.

6. Ключевые product decisions

MVP scope

MVP включает только deposits.

Withdrawals, approve/cancel withdrawals, refunds, advanced reports, anti-fraud/manual review, provider polling и dashboards не входят в MVP.

Architecture direction

Product direction:

design-first approach;
documented use cases before implementation;
DDD;
modular monolith / minimal number of services;
event-driven processing;
asynchronous gateway approach;
strong observability.

Payment method model

Новая система не должна быть provider-centric.

Merchant создает deposit через business payment method:

Cards;
Apple Pay;
Google Pay;
Sofort Uber;
BLIK.

Provider выбирается внутри routing, а не является payment method для merchant.

Routing hierarchy

Основная hierarchy:

text

Payment Method / MID
-> first-level routing rules
-> MASTER MID GROUP
-> MASTER MID
-> second-level routing rules
-> SUB MID GROUP
-> SUB MID / SUB MID AGGREGATOR

Provider visibility

Real provider names и provider internals должны быть скрыты от merchant users, если им явно не выдан provider access.

Это critical business requirement.

MASTER MID

MASTER MID является merchant-scoped сущностью.

Отдельная global MASTER MID вкладка в Platform section не нужна.

Platform user может создать MASTER MID в context merchant. Merchant user может создать MASTER MID, если имеет provider access и permissions.

SUB MID / SUB MID AGGREGATOR

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

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

SUB MID и SUB MID AGGREGATOR используют одну provider execution модель. Главное отличие:

text

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

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

Processing fee настраивается только на MASTER MID, не на SUB MID или SUB MID AGGREGATOR.

Brand

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

Payment configurations создаются под merchant, а не под brand.

brandId обязателен в deposit request и используется для transaction context / hosted form context.

API keys

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

API key является secret value для подписи request.

Для одного merchant может быть только один active API key.

Back Office

Один общий Back Office для platform users и merchant users.

В left menu есть:

Platform;
Merchant.

Доступность pages/actions определяется permissions.

Error mapping

Merchant видит только:

unified error code;
human-readable description.

Provider raw errors хранятся отдельно и доступны только platform users с permission.

Migration

Migration переносит только historical transactions.

Migration запускается вручную platform user-ом.

Migrated transactions read-only.

Webhooks по migrated transactions не отправляются.

Первый merchant переходит на v2 постепенно, payment method за payment method.

Merchant сам начинает использовать новые endpoints в рамках согласованных сроков.

Historical migration выполняется после прекращения v1 traffic по конкретному payment method.

7. Что еще нужно дописать

Детальный список gaps и next actions находится здесь:

13-gap-review/01-final-gap-review-and-next-actions.md

На верхнем уровне еще нужно подготовить или финализировать:

Back Office page-by-page requirements для design team;
Hosted Payment Page final UX;
Merchant public documentation draft;
Database schema draft;
Technical design;
QA/UAT checklist;
Load test plan.

Database schema draft должна быть подготовлена technical team на основе product data requirements.

8. Как работать с документами

Рекомендуемый process:

Product Owner описывает flow / domain / screen на русском.
Команда задает вопросы и фиксирует open points.
Product Owner закрывает product decisions.
Документ обновляется.
После согласования документ переводится на английский.
На основе документа design team готовит UI.
Development team готовит technical design.
После этого создаются tickets и estimates.

9. Статус документов

Все документы в этой папке сейчас являются draft.

Draft означает:

содержание можно менять;
terminology может уточняться;
technical follow-up может оставаться открытым;
product open questions должны постепенно закрываться.

Когда документ будет согласован, нужно изменить status внутри документа с черновик для обсуждения на approved или другой agreed status.

Payment Orchestrator MVP Product Docs ​

1. Назначение папки ​

2. Как использовать этот пакет ​

Обязательный review от команды ​

3. Рекомендуемые маршруты чтения ​

Product Owner / Business / Management ​

Development / Tech Lead ​

Design / UX ​

QA ​

DevOps / Operations ​

4. Быстрый глоссарий ​

5. Полный порядок чтения ​

Step 1. Общий контекст ​

Step 2. Deposit user journeys ​

Step 3. Functional use cases ​

Step 4. Back Office ​

Step 5. Domain model ​

Step 6. Observability ​

Step 7. API contracts ​

Step 8. Dictionaries ​

Step 9. Testing and Quality ​

Step 10. Technical Architecture ​

Step 11. Data Requirements ​

Step 12. Merchant Documentation ​

Step 13. Gap Review and Next Actions ​

6. Ключевые product decisions ​

MVP scope ​

Architecture direction ​

Payment method model ​

Routing hierarchy ​

Provider visibility ​

MASTER MID ​

SUB MID / SUB MID AGGREGATOR ​

Brand ​

API keys ​

Back Office ​

Error mapping ​

Migration ​

7. Что еще нужно дописать ​

8. Как работать с документами ​

9. Статус документов ​

Payment Orchestrator MVP Product Docs

1. Назначение папки

2. Как использовать этот пакет

Обязательный review от команды

3. Рекомендуемые маршруты чтения

Product Owner / Business / Management

Development / Tech Lead

Design / UX

QA

DevOps / Operations

4. Быстрый глоссарий

5. Полный порядок чтения

Step 1. Общий контекст

Step 2. Deposit user journeys

Step 3. Functional use cases

Step 4. Back Office

Step 5. Domain model

Step 6. Observability

Step 7. API contracts

Step 8. Dictionaries

Step 9. Testing and Quality

Step 10. Technical Architecture

Step 11. Data Requirements

Step 12. Merchant Documentation

Step 13. Gap Review and Next Actions

6. Ключевые product decisions

MVP scope

Architecture direction

Payment method model

Routing hierarchy

Provider visibility

MASTER MID

SUB MID / SUB MID AGGREGATOR

Brand

API keys

Back Office

Error mapping

Migration

7. Что еще нужно дописать

8. Как работать с документами

9. Статус документов