Payment Orchestrator MVP Business Requirements

Status: working business requirements package for team review

1. Why This Package Exists

This package describes how the business expects the new version of Payment Orchestrator to work.

The documents help the team align on:

what product we are building;
what problems the new version must solve;
which user journeys are included in the MVP;
which roles exist in the system;
which Back Office sections are needed;
which business entities matter;
which data must be hidden;
where users need transparency and investigation tools.

This package is not a technical design, database schema, API specification, event model, permission matrix, backlog, or delivery estimate.

The Product Owner describes the business expectation: what must be possible, who uses it, which constraints matter, and what result is considered correct.

The development team proposes the technical solution: architecture, integration contracts, data storage, internal processing, access model, monitoring, and other engineering decisions.

2. How to Read and Review

The team uses this package as the basis for product review:

confirm that the MVP scope is understood in the same way by everyone;
validate business terms and names;
walk through the main journeys;
find contradictions in routing, statuses, webhooks, access rules, and visibility rules;
leave questions and comments before UI design and technical design begin.

Every team member must review the specification and leave a comment on each page.

Comment format:

Reviewed / Approved - the page was reviewed and there are no questions;
Reviewed / Questions - the page was reviewed and there are questions, comments, or suggestions.

Questions should be left directly on the relevant page so the Product Owner can review them and update the requirements.

3. Recommended Reading Paths

Product, Business, Management

Design / UX

Development, QA, Operations

4. Quick Glossary

Merchant - a platform client that accepts payments through Payment Orchestrator.
Brand - a brand inside a merchant. Payment methods are created inside a brand.
Merchant Group - a group of merchants used for operational management and access.
Payment Method - a payment method inside a specific brand, for example Cards, Apple Pay, Google Pay, or BLIK.
MASTER MID GROUP - a group of MASTER MIDs from which the system selects the next processing step.
MASTER MID - a routing level where financial terms are applied and the next processing path is selected.
SUB MID GROUP - a group of execution options.
SUB MID - a provider configuration for a specific merchant.
SUB MID AGGREGATOR - a reusable provider configuration created by the platform.
Provider - the real payment provider. Its name is hidden from merchant users unless the business grants separate access.
Provider Access - business permission for a merchant to work with a specific provider.
Routing Rule - a business rule used to select a route.
Condition - a condition inside a routing rule, for example country, amount, or currency.
Fallback Route - a backup route used when regular rules do not match.
Hosted Payment Page - our payment page opened by the customer.
Transaction Timeline - the history of important transaction events used for investigation.
API Key - a merchant secret used for integration with the system.
Webhook - a merchant notification about an important transaction change.

5. Package Structure

General Context

User Journeys

Back Office

Business Entities

Operational Expectations

6. Key Decisions

MVP

The MVP includes only the deposit flow, Back Office, and the internal functionality described in this package.

Withdrawals, approve/cancel withdrawals, refunds, advanced reports, anti-fraud/manual review, and dashboards are not included in the MVP.

The first release must be good enough to migrate one merchant gradually by brand and payment method.

Payment Method Model

The new system must not be provider-centric.

Merchant users work with payment methods inside a specific brand:

Cards;
Apple Pay;
Google Pay;
Open Banking;
BLIK;
other specific methods that will be added later.

The provider is selected inside routing and must not be the main payment method shown to the merchant.

Payment Method is created under Brand, not directly under Merchant.

Routing Hierarchy

The business expects multi-level routing:

text

Brand
-> Payment Method
-> routing rules
-> MASTER MID GROUP
-> MASTER MID
-> routing rules
-> SUB MID GROUP
-> SUB MID / SUB MID AGGREGATOR

The development team proposes the technical model for storing and executing routing.

Provider Visibility

Real provider names and internal provider data are hidden from merchant users unless the business explicitly grants provider access.

This is a critical business rule.

Back Office

Back Office must be understandable for platform users and merchant users.

The menu is split into two sections:

Platform;
Merchant.

Page, data, and action availability depends on role, merchant context, and visibility rules.

Errors

Merchant and customer users must not see raw provider errors.

They should see a clear error description and, when needed, a code or reference that can be shared with support.

Migration

Migration moves historical transactions only.

Migration starts after the merchant stops using the old flow for a specific payment method.

Migrated transactions are read-only and visually marked as legacy.

7. How to Work With the Documents

The team reads the documents as business requirements.
The team leaves comments on each page.
The Product Owner resolves questions and updates the requirements.
The development team proposes the technical design.
After alignment, the team moves to decomposition, estimation, and tasks.

8. Document Status

All documents are currently in draft status.

This means:

content can change;
terminology can be refined;
technical solutions are not fixed yet;
open questions are closed through team review.

Payment Orchestrator MVP Business Requirements ​

1. Why This Package Exists ​

2. How to Read and Review ​

3. Recommended Reading Paths ​

Product, Business, Management ​

Design / UX ​

Development, QA, Operations ​

4. Quick Glossary ​

5. Package Structure ​

General Context ​

User Journeys ​

Back Office ​

Business Entities ​

Operational Expectations ​

6. Key Decisions ​

MVP ​

Payment Method Model ​

Routing Hierarchy ​

Provider Visibility ​

Back Office ​

Errors ​

Migration ​

7. How to Work With the Documents ​

8. Document Status ​

Комментарии

Payment Orchestrator MVP Business Requirements

1. Why This Package Exists

2. How to Read and Review

3. Recommended Reading Paths

Product, Business, Management

Design / UX

Development, QA, Operations

4. Quick Glossary

5. Package Structure

General Context

User Journeys

Back Office

Business Entities

Operational Expectations

6. Key Decisions

MVP

Payment Method Model

Routing Hierarchy

Provider Visibility

Back Office

Errors

Migration

7. How to Work With the Documents

8. Document Status