05.01 Business Entities

Status: draft for discussion

1. Goal

This document describes the main business entities of the system.

It is not a database schema or a technical description of relationships.

2. Merchant

Merchant is a platform client that accepts payments through Payment Orchestrator.

Expected behavior:

• platform user can create and manage merchant;
• merchant can have several brands;
• payment methods are created inside a specific brand;
• merchant has users, roles, API keys, and transactions;
• merchant can belong to a merchant group;
• inactive merchant does not accept new deposits.

3. Brand

Brand is a brand inside merchant.

Expected behavior:

• brand shows which brand the transaction is created for;
• merchant selects brand when creating a deposit;
• payment methods are created inside brand;
• different brands of the same merchant can have different payment methods and routing configurations;
• in the future, brand can be used to customize Hosted Payment Page;
• migrated transactions are moved into the context of a specific brand.

4. Merchant Group

Merchant Group is a group of merchants used for operational management and access.

Expected behavior:

• platform user can add merchants to group;
• merchant user can receive access to group if the business wants to give access to several merchants at once.

5. Payment Method / MID

Payment Method / MID is a payment method inside a specific brand.

Examples:

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

Expected behavior:

• merchant does not think in providers;
• merchant selects brand and a clear payment method inside brand;
• routing is configured inside payment method;
• payment method has a clear blueprint that shows the possible transaction path.

6. MASTER MID GROUP

MASTER MID GROUP is a group of MASTER MIDs inside routing.

Expected behavior:

• group can contain several MASTER MIDs;
• inside group, user can manage how MASTER MID is selected;
• if selected path does not work, the system can move to the next option if fallback is enabled.

7. MASTER MID

MASTER MID is a routing and financial terms level.

Expected behavior:

• MASTER MID is created in routing context of a specific payment method inside brand;
• processing fee applies on MASTER MID;
• routing to SUB MID GROUP is configured inside MASTER MID;
• merchant user does not see internal details of MASTER MID created by the platform unless the business grants access.

8. SUB MID GROUP

SUB MID GROUP is a group of execution options.

Expected behavior:

• group can contain SUB MID and/or SUB MID AGGREGATOR;
• inside group, user can manage execution option selection;
• if one option does not fit, the system tries the next one if fallback is enabled;
• if there is no suitable option, transaction is rejected with a clear reason.

9. SUB MID

SUB MID is a provider configuration for a specific merchant.

Expected behavior:

• SUB MID is linked to provider and provider method;
• SUB MID can have credentials, velocity limits, currency conversion, and additional settings;
• secret values are not shown after saving;
• if SUB MID was created by the platform, merchant user does not see internal provider data without business access.

10. SUB MID AGGREGATOR

SUB MID AGGREGATOR is a reusable provider configuration created by the platform.

Expected behavior:

• used between merchants;
• created and managed only by platform users;
• merchant users do not see internal provider details of this configuration;
• can be used in routing as an execution option.

11. Transaction

Transaction is a payment operation.

It can be created by merchant or by platform user for testing.

Expected behavior:

• transaction has a clear lifecycle;
• transaction can be investigated through timeline;
• transaction stores important business context: merchant, brand, payment method, amount, currency, customer, routing result, and final status;
• migrated transaction is read-only and marked as legacy.

12. API Key

API Key is a merchant secret used for integration with the system.

Expected behavior:

• merchant can create API key;
• secret is shown only on creation;
• merchant can safely replace key with grace period;
• key is created for merchant, not for brand.

13. Audit Log

Audit Log is the history of changes in Back Office.

Expected behavior:

• all important changes are visible for investigation;
• user understands who changed what and when;
• secret values are not exposed;
• audit log visibility depends on the user's business access.