Payment Orchestrator

Тема

01. MVP Scope ​

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

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

Этот документ описывает границы MVP для новой версии платежной системы.

Цель документа - зафиксировать:

  • что входит в первую версию;
  • что переносится из прошлой версии, но должно быть переработано;
  • какой новый функционал нужен;
  • что не входит в MVP;
  • что нужно учитывать архитектурно, но не реализовывать в первой версии;
  • какие вопросы нужно дополнительно обсудить с командой.

MVP не должен быть попыткой полностью переписать старую систему. MVP должен покрыть минимальный, но полноценный deposit-flow, который можно использовать для постепенного перевода первого merchant / merchant brand / payment method на новую версию.

2. Главная цель MVP ​

Главная цель MVP - дать возможность merchant провести deposit transaction через новую систему с новым routing и понятной операционной поддержкой.

Для MVP должно быть возможно:

  1. Создать merchant.
  2. Создать brand под merchant.
  3. Создать и настроить payment method.
  4. Настроить routing для payment method.
  5. Настроить необходимые MASTER MID / SUB MID GROUP / SUB MID / SUB MID AGGREGATOR сущности.
  6. Создать deposit через API.
  7. Провести customer через hosted payment form.
  8. Обработать provider callback.
  9. Отправить webhook merchant.
  10. Увидеть transaction в Back Office / Merchant Portal.
  11. Понять полный flow transaction через transaction timeline.
  12. Перенести historical transactions из старой системы для истории.
  13. Управлять пользователями, ролями, permissions, API keys и активными sessions.

MVP считается успешным, если первый merchant может начать принимать deposits по выбранным payment methods в новой системе, а platform admin, support и merchant users могут видеть и расследовать эти transactions без помощи разработчиков.

3. Основной принцип MVP ​

В MVP мы строим систему вокруг payment methods, а не вокруг provider names.

Правильная модель:

text
Merchant
-> Merchant Brand
-> Payment Method
-> Routing
-> Provider execution through SUB MID / SUB MID AGGREGATOR

Пример:

  • не "Interkassa deposit";
  • а "Apple Pay deposit", внутри которого может быть выбран один из провайдеров, поддерживающих Apple Pay.

Provider должен быть внутренней execution-сущностью, а не главным продуктовым методом для merchant.

4. Операции, которые входят в MVP ​

В MVP входит только deposit-flow.

Входит:

  • создание deposit через merchant API;
  • создание test deposit из Back Office, если это необходимо для проверки конфигурации;
  • public Merchant API documentation portal;
  • HMAC request signing examples на нескольких programming languages;
  • webhook signature validation examples;
  • transaction statuses documentation;
  • merchant-facing error codes documentation;
  • sandbox/test provider flow documentation;
  • test provider для всех MVP methods;
  • test transaction marker;
  • environments: local/dev/stg/prod;
  • test provider available in stg and prod;
  • hosted payment form;
  • expiration для hosted payment form / payment link;
  • expiration time на уровне MID configuration;
  • polling transaction status на hosted payment form;
  • provider callback processing;
  • merchant webhook sending;
  • webhook retry;
  • transaction status/details;
  • transaction timeline;
  • transaction export;
  • transaction status correction.

Не входит:

  • withdrawals;
  • withdrawal approval;
  • withdrawal cancellation;
  • refunds;
  • manual review;
  • anti-fraud module.

В Merchant API MVP не входят:

  • transaction details/status lookup endpoint;
  • manual cancel endpoint;
  • merchant-triggered webhook resend endpoint;

Refunds нужно учесть архитектурно. Если provider предоставляет refund functionality, ее нужно будет поддержать в будущих версиях, но не в MVP.

4.1 Runtime configuration boundaries ​

В MVP не нужна отдельная Back Office page System Settings.

Runtime configuration должна задаваться через environment variables / code-level configuration.

К таким настройкам относятся:

  • transaction expiration;
  • hosted form / payment session expiration;
  • webhook retry duration;
  • webhook retry intervals;
  • callback processing retry settings;
  • provider timeout.

Platform admin не меняет эти настройки из Back Office в MVP.

В MVP не входят:

  • System Settings UI;
  • feature flags UI;
  • emergency pause UI;
  • maintenance/incidents banner in Back Office.

Canary / legacy migration должен быть реализован как отдельный temporary migration tool.

Migration tool может быть максимально простым: internal admin tool или Swagger/internal API. Это одноразовый функционал, который будет удален после завершения migration phase.

4.2 Architecture baseline ​

Для MVP уже существует network / runtime diagram.

Она фиксирует high-level infrastructure baseline:

  • Cloudflare WAF;
  • External HTTPS Load Balancer;
  • GKE Gateway API;
  • Forms Service;
  • Merchant Gateway;
  • Backoffice Gateway;
  • Provider Gateway;
  • Payment Service as diagram label / Orchestrator Service as application core;
  • Exchange Service;
  • Report Service;
  • Pub/Sub;
  • PostgreSQL / PgBouncer / Read Replica;
  • Redis;
  • Cloud Storage;
  • Cloud Logging / Cloud Monitoring / Grafana.

Эта diagram является network/runtime baseline, но не заменяет application architecture design.

Product-level architecture expectation:

  • monorepo is required;
  • gateways are thin and async-oriented;
  • Orchestrator Service is core business service / modular monolith candidate;
  • Exchange Service remains separate service inside the same project/monorepo;
  • Report Service remains separate service inside the same project/monorepo;
  • Designed Swagger
  • Merchant Gateway creates payment session and hosted payment URL before returning success;
  • Provider Gateway publishes callback to durable queue before returning OK;
  • Merchant Gateway and Provider Gateway must stay operational during core service restart/lag;
  • Pub/Sub is used to decouple gateway entry points from core processing;
  • important business events must be reflected in transaction timeline;
  • failed async events must be visible for investigation;
  • dead-letter / failed-event handling is technical requirement, but separate Back Office DLQ UI is not MVP;
  • PostgreSQL is durable system of record;
  • Redis is supporting/cache layer

5. Payment Methods в MVP ​

В MVP нужно поддержать deposit methods, которые действительно нужны для первого этапа миграции.

Payment methods в MVP:

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

Важно не переносить старые provider-specific методы как продуктовые методы.

Generic APM не является payment method в MVP. Если нужен alternative payment method, он должен быть заведен конкретным названием, например Skrill Quick Checkout или Jeton

6. Пользователи и роли, которые входят в MVP ​

В MVP должны быть учтены следующие категории пользователей:

  • Platform Admin;
  • Platform Support;
  • Merchant Admin;
  • Merchant User;
  • Merchant API Client;
  • Customer;
  • Provider.

Важно: роли должны быть настраиваемыми через permission model. Нельзя заранее жестко зашить все роли в коде как единственный возможный вариант.

В MVP также входит полноценная auth-система:

  • login/logout;
  • 2FA / OTP;
  • forgot password / password reset;
  • отправка email message с кодом для восстановления пароля;
  • first platform admin bootstrap flow;
  • управление active sessions;
  • возможность иметь несколько активных sessions;
  • пользователь должен видеть свои sessions в профиле;
  • пользователь должен иметь возможность завершать / удалять одну выбранную session;
  • session management actions должны попадать в audit log, если это значимое security action.

Password reset requirements:

  • password reset code действует 30 минут;
  • время жизни password reset code должно настраиваться через environment variables;
  • максимальное количество password reset attempts по умолчанию: 3;
  • количество attempts должно настраиваться через environment variables.

Invite requirements:

  • invite email link действует 72 часа;
  • время жизни invite link должно настраиваться через environment variables;
  • обязательная смена пароля после invite / bootstrap не требуется.

При создании пользователя platform user с нужной permission должен выбрать тип пользователя:

  • platform user;
  • merchant user.

Это нужно, чтобы роли и доступы могли строиться отдельно для platform users и merchant users.

Роли создаются только platform admins с соответствующей permission. Роли строятся на основе permissions.

При первом деплое Back Office должен поддерживать bootstrap flow: если в системе нет ни одного пользователя, можно создать первого platform user. Этому пользователю автоматически выдается platform role с названием Admin, к которой подключены все permissions системы.

Доступ пользователя должен задаваться в конкретном контексте:

  • если пользователю дают доступ к merchant, нужно указать его роль в контексте этого merchant;
  • если пользователю дают доступ к merchant group, нужно указать его роль в контексте этой merchant group.

User не может одновременно быть platform user и merchant user.

User не может одновременно иметь platform role и merchant access.

User type после создания не меняется.

Merchant user может быть создан без доступа к merchant или merchant group.

Если user залогинился без access context, он должен видеть пустой Back Office.

User email должен быть уникальным и не может быть переиспользован после soft-delete.

Merchant user может приглашать других пользователей только если у него есть роль с нужной permission в контексте конкретного merchant. В этом случае он может выдавать роли только в том merchant context, где у него самого есть доступ и право управлять пользователями.

Доступ к merchant group может выдавать только platform user с соответствующей permission.

Повторный invite на email существующего user-а или pending invite должен вернуть ошибку.

Expired invite можно отправить повторно через resend invite action.

Отдельный invite status CANCELED в MVP не нужен.

Если активному user-у добавляют новый merchant / merchant group access, email notification в MVP не отправляется.

Если user удаляется из merchant context, active sessions завершать не нужно. Система должна сразу пересчитать permissions/access.

Изменения role/permissions должны применяться сразу.

Если merchant добавили в merchant group или убрали из merchant group, users с group access должны сразу получить или потерять доступ к этому merchant.

Один merchant может входить только в одну merchant group.

Merchant group нужна только для grouping/access.

Merchant group создают только platform users.

Добавлять/удалять merchants из merchant group могут только platform users.

Автоматическое изменение access из-за изменения состава merchant group должно попадать в audit log.

Если role переводится в INACTIVE или DELETED, эта role должна быть удалена у users, которым она была назначена.

User в status DISABLED можно вернуть в ACTIVE.

User в status DELETED нельзя восстановить.

User может редактировать свои first name / last name.

Admin с permission может редактировать first name / last name user-а.

User должен видеть active sessions, history завершенных sessions / login sessions и security events в profile.

User invitation должен работать через email link.

7. Platform Admin функционал в MVP ​

Platform Admin area должна включать функционал для управления платформой и внутренними настройками.

В MVP входит:

  • merchant management;
  • merchant brand management;
  • merchant group management;
  • payment method management;
  • MASTER MID management;
  • MASTER MID GROUP management;
  • SUB MID GROUP management;
  • SUB MID management;
  • SUB MID AGGREGATOR management;
  • routing configuration;
  • velocity limits;
  • currency conversion / FX configuration;
  • fee configuration;
  • users management;
  • roles and permissions management;
  • API keys management;
  • transaction list;
  • transaction details;
  • transaction timeline;
  • transaction export;
  • webhook attempts;
  • webhook resend, если у пользователя есть permission;
  • manual correction из transaction details для любых transaction statuses, если у пользователя есть permission;
  • webhook resend из transaction details на PROCESSING and final statuses, если у пользователя есть permission;
  • test deposit из Back Office;
  • migration utility;
  • audit logs.

Platform Admin должен видеть внутренние сущности и provider-related information только при наличии соответствующих permissions.

Для каждой важной сущности в Back Office должна быть вкладка или раздел Audit logs, где пользователь с permission может увидеть историю изменений этой сущности.

Back Office должен быть разделен на две логические зоны:

  • Platform section;
  • Merchant section.

В обеих зонах должны быть provider/acquirer-related разделы, но уровень возможностей будет разный.

В Platform section -> SUB MID Aggregators platform user с нужными permissions видит и управляет platform-level reusable provider/acquirer configurations.

В Merchant section -> SUB MID пользователь видит provider/acquirer configurations только по тем merchants, к которым у него есть доступ. Дополнительно в контексте этих merchants у пользователя должна быть роль с permission, разрешающей просматривать и управлять SUB MID, а также мерчант должен иметь доступ к конкретному provider/acquirer, чтобы иметь возможность их конфигурировать.

В Merchant section также должна быть вкладка Payment Method / MID.

В Merchant section -> Payment Method / MID пользователь видит таблицу merchant-level payment method configurations. Например, пользователь может создать новую configuration для Cards или для Jeton.

При открытии такой configuration отображается configuration details. Через configuration details можно открыть routing blueprint. На первом уровне находятся rules. Через эти rules пользователь может добавить в routing MASTER MID, которые доступны в контексте этого мерчанта.

MASTER MID является merchant-scoped сущностью. Его может создать platform user в контексте мерчанта или merchant user с permission и provider access. Если MASTER MID создан platform user, merchant user не видит его internal blueprint без специального доступа.

8. Merchant Portal функционал в MVP ​

Merchant Portal должен быть отделен от Platform Admin area.

Merchant user должен видеть только merchant-facing functionality.

В MVP входит:

  • brand filter;
  • transactions list;
  • transaction details;
  • visible payment methods;
  • visible routing level;
  • sent merchant webhook payloads;
  • webhook delivery statuses;
  • API keys management;
  • users management, если у merchant user есть permission;
  • roles assignment только из разрешенного набора merchant roles;
  • webhook resend, если у merchant user есть permission;
  • transaction export.

Merchant user не должен видеть:

  • реальные provider names, если ему явно не выдан доступ;
  • provider credentials;
  • internal MID configuration;
  • raw provider responses;
  • внутренние routing attempts, которые раскрывают provider execution, если это не разрешено permissions.

API keys создаются на уровне merchant, не на уровне brand. Merchant user с нужной permission может создавать API keys самостоятельно.

При создании нового API key merchant должен иметь возможность выбрать key rotation grace period. Это нужно, чтобы старый key продолжал работать некоторое время после создания нового key, и merchant мог безопасно переключить интеграцию.

Варианты key rotation grace period для MVP:

  • 1 час;
  • 3 часа;
  • 12 часов;
  • 24 часа.

9. MASTER MID, SUB MID и provider visibility в MVP ​

MASTER MID - это верхнеуровневая настройка routing для конкретного payment method.

SUB MID - это настройка provider execution.

SUB MID AGGREGATOR - это reusable platform-level provider/acquirer configuration, которую создают platform admins и могут переиспользовать между merchants.

На уровне SUB MID можно настраивать:

  • provider credentials / keys;
  • provider-specific configuration;
  • expiration time для transaction;
  • velocity limits;
  • FX / conversion configuration;
  • замену реальных email пользователей в контексте этого SUB MID;
  • список обязательных attributes для конкретного provider method, если этот SUB MID требует дополнительные данные.

SUB MID required fields для MVP:

  • name;
  • merchant;
  • provider;
  • provider method;
  • method;
  • status;
  • credentials;
  • specific-config;
  • velocity-limits;
  • conversion;

methid, provider и provider method нельзя изменить после создания SUB MID.

SUB MID AGGREGATOR использует ту же provider execution модель и те же required fields, но является global/reusable platform-level configuration с aggregator = true.

SUB MID является merchant-scoped configuration с aggregator = false.

Credentials/config у SUB MID / SUB MID AGGREGATOR:

  • показываются как обычные inputs при создании;
  • secret values шифруются после сохранения;
  • secret values нельзя повторно увидеть после сохранения;
  • secret можно только заменить новым введенным значением;
  • non-secret config fields могут быть повторно открыты после сохранения users с permission и visibility access;
  • non-secret config fields показывают старые значения при редактировании;
  • имеют version/history;
  • не требуют OTP / 2FA confirmation при изменении;

Audit log фиксирует изменение credentials/config и changed field names, но не хранит old/new secret values.

Merchant может видеть provider / SUB MID information только если:

  • merchant получил доступ видеть этого provider;
  • у конкретного merchant user есть соответствующая permission.
  • SUB MID создан merchant-user;

Если merchant не имеет доступа видеть provider, то для него routing должен оставаться blackbox. Он видит payment method, например Card payment, но не видит, какие реальные SUB MIDs/providers подключены внутри.

Доступ merchant к provider может выдать только пользователь, у которого есть permission управлять provider access. Обычно это platform user с platform role, где есть соответствующая permission.

После выдачи provider access пользователи, у которых есть доступ к этому merchant и нужные permissions, могут видеть больше информации об этом provider в контексте этого merchant.

Provider access выдается:

  • на уровне merchant;
  • к конкретному provider;
  • сразу ко всем provider methods этого provider.

Provider access не выдается на уровне brand, merchant group, user.

Provider access можно revoke.

После revoke уже созданные SUB MID остаются active, но merchant users больше не видят provider details по этим SUB MID и больше не могут создавать новые SUB MID этого provider.

Provider access grant/revoke должен попадать в audit log.

Provider access управляется на странице merchant details.

В Merchant section отдельная страница Provider Access не нужна. При создании SUB MID merchant user видит в provider selector только providers, к которым merchant имеет access.

Если SUB MID создан конкретно под merchant user-merchant'ом, и merchant получил доступ видеть provider, то merchant user с нужными permissions может видеть больше информации по этому SUB MID.

Если используется SUB MID AGGREGATOR, merchant не должен видеть его внутренние настройки. Такая reusable configuration создается platform admins и может переиспользоваться между разными merchants.

SUB MID и SUB MID AGGREGATOR можно soft-delete, даже если по ним есть transactions.

Historical transactions должны хранить execution snapshot выбранного SUB MID / SUB MID AGGREGATOR, чтобы transaction details оставались понятными после удаления, отключения или изменения credentials/config.

Error mapping / error dictionary в MVP не требует отдельного UI. На первом этапе mapping может быть реализован на уровне кода.

Provider Catalog в MVP не является отдельным пользовательским разделом и не является бизнес-сущностью в базе.

Список providers и provider methods хранится в коде.

Если provider method не реализован в коде, он не должен показываться в UI и не может использоваться для создания SUB MID.

Временная недоступность provider method является operational agreement / operational handling, а не отдельной product setting в Back Office.

Рабочая терминология MVP:

  • MASTER MID GROUP - верхнеуровневая группа MASTER MID, в которую routing направляет transaction после первого уровня rules
  • MASTER MID - верхнеуровневая routing configuration для payment method;
  • SUB MID GROUP - группа execution configurations, в которую routing направляет transaction после MASTER MID;
  • SUB MID - merchant-specific acquirer/provider configuration;
  • SUB MID AGGREGATOR - reusable platform-level acquirer/provider configuration.

Отдельная глобальная вкладка MASTER MID в Platform section в MVP не нужна.

MASTER MID управляется через merchant context, потому что он всегда принадлежит конкретному merchant. Platform user может создать новую MASTER MID configuration для конкретного merchant и payment method, например Cards.

MASTER MID:

  • всегда принадлежит одному merchant;
  • всегда привязан к одному method;
  • может использоваться в нескольких Payment Method / MID routings одного merchant;
  • может быть создан platform user-ом с permission;
  • может быть создан merchant user-ом с permission, если merchant имеет provider access;
  • имеет required fields: name, method, status, createdByType;
  • может иметь пустую processing fee;
  • может быть создан без published routing blueprint;
  • не может быть published без valid routing to SUB MID GROUP;
  • сохраняет historical transactions доступными после soft-delete.

MASTER MID GROUP:

  • создается внутри Payment Method / MID routing;
  • может быть пустой;
  • может быть published пустой;
  • не требует name;
  • имеет required settings: selectionStrategy, fallbackEnabled;
  • поддерживает selectionStrategy: sequence и weight;
  • имеет fallbackEnabled true by default;
  • fallback можно выключить;
  • weight values могут быть любыми положительными числами и считаются пропорционально;
  • один MASTER MID может быть добавлен в несколько MASTER MID GROUP внутри одного merchant;
  • historical transactions должны показывать, через какую MASTER MID GROUP / MASTER MID они прошли, даже если MASTER MID позже удалили из group.

SUB MID GROUP:

  • создается только внутри MASTER MID blueprint;
  • может быть пустой;
  • может быть published пустой;
  • не требует name в MVP;
  • имеет required settings: selectionStrategy, fallbackEnabled;
  • поддерживает selectionStrategy: sequence и weight;
  • имеет fallbackEnabled true by default;
  • fallback можно выключить;
  • weight values могут быть любыми положительными числами и считаются пропорционально;
  • один SUB MID может быть добавлен в несколько SUB MID GROUP внутри одного merchant;
  • historical transactions должны показывать, через какую SUB MID GROUP / SUB MID они прошли, даже если SUB MID позже удалили из group.

При открытии MASTER MID configuration отображается MASTER MID details. В MASTER MID details можно перейти в routing blueprint. На первом уровне blueprint находятся rules. Эти rules направляют transaction на SUB MID GROUP. Внутри SUB MID GROUP находятся SUB MID и/или SUB MID AGGREGATOR.

Целевая routing chain:

text
Payment Method
-> первый уровень routing
-> MASTER MID
-> rules внутри MASTER MID blueprint
-> SUB MID GROUP
-> SUB MID / SUB MID AGGREGATOR

Пример:

  1. Есть payment method для карт.
  2. Для payment method открывается MASTER MID configuration.
  3. В MASTER MID blueprint первый уровень rules направляет transaction на SUB MID GROUP.
  4. В SUB MID GROUP находятся реальные SUB MID / SUB MID AGGREGATOR, например Interkassa.

SUB MID / SUB MID AGGREGATOR и реальные provider details должны быть скрыты от merchant, если у него нет специальных permissions.

10. Функционал из прошлой версии, который нужно перенести и переработать ​

Из прошлой версии нужно перенести не саму реализацию, а полезные продуктовые возможности.

Нужно перенести и переработать:

  • deposit creation;
  • merchant validation;
  • routing;
  • provider execution;
  • currency conversion;
  • provider callback processing;
  • merchant callback/webhook sending;
  • webhook retry;
  • velocity limits;
  • transaction callback resend;
  • transaction correction;
  • transaction inbox/outbox logs;
  • callback inbox/outbox logs;
  • report generation / transaction export;
  • observability;
  • merchant management;
  • merchant group management;
  • users management;
  • roles and permissions management;
  • providers management;
  • audit logs.

Важно: эти возможности не должны быть перенесены один-в-один. Их нужно переосмыслить с учетом новой модели payment methods, merchant brands, routing hierarchy, permissions и transaction timeline.

11. Новый функционал в MVP ​

В новой версии появляется функционал, которого раньше не было или который был выражен недостаточно явно.

В MVP входит:

  • Merchant Brands under Merchant;
  • разделение Back Office на Platform Admin area и Merchant Portal;
  • разделение UI на Platform section и Merchant section;
  • Platform section / SUB MID Aggregators для SUB MID AGGREGATOR configurations;
  • Merchant section / MASTER MID для merchant-scoped MASTER MID configurations;
  • Merchant section / SUB MID для provider/acquirer configurations, доступных merchant;
  • Merchant section / Payment Method / MID для merchant-level payment method routing configurations;
  • улучшенная transaction explainability;
  • transaction timeline как основной инструмент расследования;
  • динамическая hosted payment form;
  • динамический сбор дополнительных полей, если выбранный MID требует данные, которые merchant не передал;
  • единый naming для provider attributes внутри нашей системы;
  • API key rotation grace period;
  • session management в профиле пользователя;
  • новая модель payment methods, отделенная от provider names;
  • новый hierarchical routing;
  • скрытие real provider names от merchant users;
  • managed permission model;
  • standard error mapping для merchant-facing ошибок;
  • legacy marker для migrated transactions.

Transaction timeline должен поддерживать visibility levels:

  • merchant_safe;
  • platform_only;
  • sensitive_platform_only.

Timeline events immutable.

Timeline должен хранить фактически использованные configuration versions.

Raw payload не должен храниться прямо внутри timeline event. Timeline должен хранить payload reference, если raw payload сохранен отдельно.

Timeline event может содержать request ID / correlation ID для связи logs, provider request, callback and webhook delivery.

Transaction list должен:

  • показывать основные columns по default;
  • позволять скрывать/показывать все columns, кроме transaction ID;
  • всегда показывать transaction ID;
  • сохранять column settings на client side;
  • показывать legacy transactions как badge/marker.

Transaction details должен:

  • показывать Routing tab merchant user-у всегда, но только merchant-safe representation;
  • показывать Raw Payloads tab для merchant webhook payloads, если user имеет permission;
  • показывать raw provider request/response/callback только platform user-у с permission.

12. Dynamic Attributes для provider methods ​

У каждого provider может быть несколько provider methods, и у каждого provider method может быть свой список обязательных attributes.

Если merchant при создании deposit не передал все attributes, необходимые для итогового выбранного MID/provider method, система должна дособрать недостающие данные на нашей hosted payment form.

Обязательные поля для создания deposit задаются на уровне Merchant Deposit API DTO.

Если merchant не передал обязательное поле deposit DTO, transaction не создается.

Provider adapter schema не должна дублировать deposit DTO required fields как отдельную merchant-required модель.

Provider adapter schema описывается в коде и включает:

  • provider-specific required customer attributes;
  • optional customer attributes;
  • canonical attribute mapping;
  • hosted form input type;
  • validation rules;
  • English label;
  • future localization key;
  • SUB MID / SUB MID AGGREGATOR config fields.

Config fields для SUB MID / SUB MID AGGREGATOR могут быть:

  • secret required;
  • secret optional;
  • non-secret required;
  • non-secret optional;
  • boolean;
  • enum/select;
  • string/text;
  • number;
  • URL.

Важно унифицировать naming attributes внутри нашей системы.

Например:

  • Provider A ожидает поле ip;
  • Provider B ожидает поле ipAddress;
  • в нашей системе merchant должен передавать одно стандартное поле, например ip.

Наша система должна маппить canonical attribute name на provider-specific field name внутри provider adapter / MID execution logic.

Для MVP минимальный список canonical attributes:

  • email;
  • country;
  • ip;
  • address;
  • city.

Labels hosted form в MVP только на английском.

Код должен быть заложен так, чтобы в будущем добавить мультиязычность.

Данные, которые customer ввел на hosted form, сохраняются в transaction customer context.

13. Transaction correction в MVP ​

В старой системе уже есть возможность корректировать transaction status. Этот функционал нужно перенести в MVP, но ограничить его понятными правилами.

Семантика final statuses:

  • COMPLETED - устанавливается в результате обработки webhook/callback от provider.
  • FAILED - устанавливается в результате обработки webhook/callback от provider.
  • CANCELED - устанавливается в результате обработки callback от provider или если transaction/payment session expired на нашей стороне.
  • REJECTED - устанавливается в результате внутреннего processing, если transaction была отклонена по внутренней причине.

В MVP transaction correction позволяет:

  • вручную изменить только transaction status;
  • выставить любой final status;
  • указать, нужно ли после correction сделать resend callback / webhook merchant.

Transaction correction должен быть доступен любому пользователю, если у него есть соответствующая permission.

В MVP не нужно ограничивать correction final statuses в зависимости от текущего статуса transaction. Пользователь с соответствующей permission может выставить любой final status.

При создании transaction merchant может передать список webhook URLs.

Если выполняется manual resend webhook event, система должна отправить webhook на все webhook URLs, которые были указаны при создании transaction.

Каждая correction должна попадать в audit log и transaction timeline.

Merchant webhook payload должен содержать:

  • transactionId;
  • merchantTransactionId;
  • providerTransactionId;
  • status;
  • userId;
  • amount;
  • currency;
  • paymentMethodId;
  • brandId;
  • merchantId;
  • accountReference;
  • corrected;
  • type;
  • sentAt;
  • errorCode;
  • errorDescription.

Webhook payload не должен содержать statusChangedAt, createdAt, updatedAt или amountInEur.

errorCode и errorDescription всегда присутствуют в payload и равны null, если ошибки нет.

Webhook подписывается через HMAC. Exact HMAC format должна предложить development team.

Delivery success - любой HTTP 2xx; response body не влияет на success. Любой non-2xx считается failed attempt и идет в retry.

13.1 Transaction data requirements ​

Transaction должна хранить all merchant/customer-provided non-secret data.

Минимально transaction data должна покрывать:

  • merchant/request context;
  • customer context;
  • hosted form collected attributes;
  • original amount;
  • original currency;
  • amount in EUR;
  • conversion date/time;
  • conversion rate;
  • providerTransactionId, если provider его вернул;
  • accountReference, если provider его вернул;
  • corrected marker;
  • legacy marker;
  • final routing result summary.

Merchant user видит routing/data summary только в safe/filtered виде.

Platform user с permission видит full routing result and internal transaction details.

Migration legacy identifiers должны храниться без раздувания normal transaction model множеством first-class legacy fields.

Database schema является responsibility development team.

13.2 Configuration snapshot requirements ​

Transaction должна сохранять фактически использованные configuration versions/snapshots.

Минимально нужно сохранять:

  • Payment Method / MID configuration version;
  • first-level routing blueprint version;
  • selected MASTER MID GROUP and selection settings;
  • selected MASTER MID and processing fee configuration;
  • MASTER MID routing blueprint version;
  • selected SUB MID GROUP and selection settings;
  • selected SUB MID / SUB MID AGGREGATOR configuration version;
  • credentials/config snapshot reference without secret values;
  • applied velocity rule/result;
  • applied FX/conversion fee snapshot;
  • applied processing fee snapshot.

Transaction details должны показывать historical version/snapshot used, not current configuration.

Если configuration version была archived/soft-deleted after transaction, historical transaction investigation must still work.

Merchant user видит historical snapshot only at visible/safe levels.

Platform user с permission видит full historical config snapshot.

13.3 Payload and raw data requirements ​

Для investigation система должна сохранять raw payloads.

Нужно сохранять:

  • raw provider callback payload полностью, если технически возможно;
  • raw provider request payload;
  • raw provider response payload;
  • merchant webhook request payload;
  • merchant webhook response status/body/headers/error/timeout details.

Raw provider data видят только platform users with permission.

Merchant user with permission может видеть merchant webhook payload and response data.

Secrets must be hidden/masked/removed from raw payloads.

Customer sensitive data in raw payloads can be visible to platform users with permission.

Raw payloads are retained indefinitely.

Raw payloads не входят в CSV export.

Transaction timeline stores payload reference/link, not inline raw payload.

13.4 Audit/security data requirements ​

Audit/security logs must store:

  • login success;
  • failed login attempts;
  • logout;
  • session created/terminated;
  • password reset requested/completed;
  • 2FA setup/reset/failed attempts;
  • invite created/resent/accepted/expired;
  • user role/access changes;
  • provider access grant/revoke;
  • API key created/rotated/revoked.

Actor IP/user agent must be stored for Back Office user actions and login/security events, if available.

Audit log stores old/new values for non-secret field changes.

Audit log does not store old/new values for secrets.

For secret changes, audit log stores only the fact that secret field was changed.

Audit/security logs are retained indefinitely.

Merchant user sees audit events only in accessible merchant contexts.

Platform user with permission sees global audit/security logs.

Audit log export is included in MVP.

14. Merchant transition and migration in MVP ​

Переход первого merchant-а должен быть постепенным.

Merchant переводит payment methods на v2 по одному.

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

Решение о readiness принимает Product Owner.

MVP acceptance выполняет Product Owner.

Перед live traffic по конкретному payment method должны быть проверены:

  • merchant created;
  • brand created;
  • API key created;
  • payment method active;
  • routing published;
  • provider callback tested;
  • merchant webhook tested;
  • test deposit successful;
  • transaction visible in Back Office;
  • routing/timeline understandable.

Отдельный standalone checklist для первого merchant в MVP не нужен.

Эти checks должны быть частью release tasks / UAT demo scenarios.

Required UAT/demo scenarios для MVP acceptance:

  • full demo from merchant creation to successful deposit;
  • failed deposit;
  • fallback routing;
  • velocity rejection;
  • manual transaction correction;
  • webhook retry;
  • manual webhook resend;
  • duplicate provider callback handling;
  • ignored provider callback handling;
  • platform/merchant permission visibility;
  • secret leakage manual check;
  • load test result review.

Load test обязателен для MVP acceptance.

В MVP не нужно:

  • хранить date/time switch marker;
  • показывать migrated to v2 marker на merchant/payment method;
  • делать technical feature flag для переключения;

Старая система продолжает работать, пока merchant использует v1 endpoints.

Historical migration выполняется после того, как merchant перестал отправлять traffic в v1 по конкретному payment method.

Предполагаемый process:

  1. В новой системе создается merchant.
  2. Под merchant создается brand.
  3. Под merchant создается payment method.
  4. Выполняется test deposit.
  5. Merchant начинает отправлять traffic по этому payment method в v2.
  6. Merchant перестает отправлять traffic по этому payment method в v1.
  7. Historical transactions переносятся из старого Back Office в новый Back Office.

В MVP migration utility должна позволять:

  • выбрать merchant;
  • выбрать payment method / brand;
  • перенести historical transactions;
  • сохранить old transaction IDs;
  • пометить migrated transactions как legacy;
  • показать immediate migration report.

Migration tool не требует отдельного audit log и постоянного хранения migration reports.

Default brand для migration автоматически не создается. Target brand должен быть выбран явно.

Для migration mapping нужны следующие данные:

  • из старой системы: merchantId / merchantConfigId;
  • в новой системе: brandId и paymentMethodId.

15. Observability и расследование transactions ​

В MVP не обязательно делать полноценные monitoring dashboards внутри UI, но система должна быть наблюдаемой.

Обязательно:

  • transaction timeline;
  • audit logs;
  • provider callback logs;
  • merchant webhook logs;
  • transaction inbox/outbox logs;
  • callback inbox/outbox logs;
  • Prometheus metrics / alerts на техническом уровне;
  • понятное error mapping для merchant-facing статусов и ошибок;
  • audit logs tab для каждой важной сущности.

Prometheus alerts для MVP должны покрывать падение success rate:

  • по provider;
  • по merchant;
  • по системе в целом.

Merchant users могут видеть audit logs по доступным им сущностям, если у них есть соответствующая permission.

Audit log должен создаваться на любые изменения сущностей в системе. Видимость audit log зависит от permissions и visibility rules пользователя.

Audit logs не должны хранить key/secret values ни в old values, ни в new values, ни в export.

Merchant-facing audit logs должны скрывать platform-hidden provider/internal details. Другие provider-sensitive non-secret поля дополнительно скрывать не нужно, если у пользователя есть право видеть соответствующую сущность.

Для каждой transaction должно быть понятно:

  • какой payment method был использован;
  • какой routing path был выбран;
  • какие rules применились;
  • какие attempts были выполнены;
  • какие attempts были отклонены;
  • почему был выполнен fallback;
  • какой provider callback пришел;
  • какой webhook был отправлен merchant;
  • какие retry были выполнены;
  • какая причина ошибки.

16. Что не входит в MVP ​

В MVP не входит:

  • Customers;
  • Customer profile management;
  • Customer blocking;
  • Blocklist;
  • Withdrawals;
  • Withdrawal approval;
  • Withdrawal cancellation;
  • Internal balance;
  • Advanced reports;
  • Cloud reports / signed URL reports;
  • Anti-fraud module;
  • Manual review;
  • Frozen / unfreeze functionality;
  • Routing simulation;
  • Advanced reconciliation;
  • Advanced analytics dashboards inside UI.

Эти направления могут быть учтены архитектурно, но не должны входить в первый delivery scope.

17. Что нужно учесть архитектурно, но не делать в MVP ​

Даже если функционал не входит в MVP, система должна быть спроектирована так, чтобы позже можно было добавить:

  • withdrawals;
  • approve/cancel withdrawal;
  • refunds;
  • anti-fraud;
  • blocklist;
  • customer profile;
  • customer blocking;
  • routing simulation;
  • advanced merchant/provider analytics.

Архитектурно новая система должна быть построена как monorepo с минимальным количеством сервисов. Предварительное направление:

  • Back Office / Admin service;
  • transaction processing service;
  • gateways для внешних entry points;
  • общие пакеты / modules внутри monorepo.

Точная техническая архитектура должна быть предложена development team.

18. Критерии успеха MVP ​

MVP можно считать успешным, если:

  • Platform Admin может создать merchant.
  • Platform Admin / User Merchant может создать brand под merchant.
  • Platform Admin может создать и настроить payment method.
  • Один merchant может иметь несколько Payment Method / MID с одним method type.
  • Payment Method / MID required fields: name, method, status, createdByType.
  • Payment Method / MID name видят platform и merchant users с доступом.
  • Customer не видит Payment Method / MID name.
  • Payment Method / MID method нельзя менять после создания.
  • Payment Method / MID хранит createdByType: platform или merchant.
  • Payment Method / MID может быть создан без published routing blueprint.
  • Payment Method / MID нельзя активировать для processing без valid published routing blueprint.
  • INACTIVE/DELETED Payment Method / MID rejected без создания transaction.
  • DELETED Payment Method / MID сохраняет historical transactions доступными.
  • Payment Method / MID можно soft-delete, даже если по нему есть transactions.
  • Payment Method / MID имеет Audit Logs tab.
  • Merchant имеет только обязательные fields: name, status, legal name.
  • Brand имеет только обязательные fields: name, status, domain.
  • Merchant может иметь несколько brands с одинаковым domain.
  • INACTIVE merchant автоматически отключает processing для его brands, payment methods, API keys и новых deposits.
  • Platform Admin может настроить routing.
  • Platform Admin может настроить MASTER MID / SUB MID GROUP / SUB MID / SUB MID AGGREGATOR.
  • MASTER MID required fields: name, method, status, createdByType.
  • MASTER MID method нельзя менять после создания.
  • MASTER MID может использоваться в нескольких Payment Method / MID routings одного merchant.
  • MASTER MID processing fee может быть пустой.
  • MASTER MID может быть создан без processing fee.
  • MASTER MID может быть создан без published routing blueprint.
  • MASTER MID нельзя publish без valid routing to SUB MID GROUP.
  • DELETED MASTER MID сохраняет historical transactions доступными.
  • MASTER MID GROUP может быть пустой и published пустой.
  • MASTER MID GROUP required settings: selectionStrategy, fallbackEnabled.
  • MASTER MID GROUP поддерживает sequence и weight.
  • MASTER MID GROUP fallback включен по default и может быть выключен.
  • MASTER MID GROUP weights считаются пропорционально и не обязаны суммироваться до 100.
  • Один MASTER MID можно добавить в несколько MASTER MID GROUP внутри одного merchant.
  • Historical transactions показывают MASTER MID GROUP / MASTER MID, через которые прошли.
  • SUB MID GROUP может быть пустой и published пустой.
  • SUB MID GROUP required settings: selectionStrategy, fallbackEnabled.
  • SUB MID GROUP поддерживает sequence и weight.
  • SUB MID GROUP fallback включен по default и может быть выключен.
  • SUB MID GROUP weights считаются пропорционально и не обязаны суммироваться до 100.
  • Один SUB MID можно добавить в несколько SUB MID GROUP внутри одного merchant.
  • Historical transactions показывают SUB MID GROUP / SUB MID, через которые прошли.
  • SUB MID required fields: name, provider, provider method, method, status, credentials/config, createdByType.
  • SUB MID нельзя создать без required credentials/config.
  • SUB MID нельзя сохранить inactive, если required credentials/config не заполнены.
  • SUB MID provider нельзя менять после создания.
  • SUB MID provider method нельзя менять после создания.
  • Secret values SUB MID шифруются и не раскрываются после сохранения.
  • Secret SUB MID можно только заменить новым введенным значением.
  • Non-secret config fields SUB MID можно повторно открыть после сохранения, если user имеет permission и visibility access.
  • SUB MID credentials/config имеют version/history.
  • SUB MID AGGREGATOR required fields: name, provider, provider method, method, status, credentials/config, createdByType.
  • SUB MID AGGREGATOR нельзя создать без required credentials/config.
  • SUB MID AGGREGATOR нельзя сохранить inactive, если required credentials/config не заполнены.
  • SUB MID AGGREGATOR provider нельзя менять после создания.
  • SUB MID AGGREGATOR provider method нельзя менять после создания.
  • Secret values SUB MID AGGREGATOR шифруются и не раскрываются после сохранения.
  • Secret SUB MID AGGREGATOR можно только заменить новым введенным значением.
  • Non-secret config fields SUB MID AGGREGATOR можно повторно открыть после сохранения platform user-ом с permission.
  • SUB MID AGGREGATOR credentials/config имеют version/history.
  • Rollback credentials/config к старой version в MVP не нужен.
  • OTP / 2FA confirmation для изменения SUB MID / SUB MID AGGREGATOR credentials/config не нужен.
  • Audit log не хранит old/new secret values credentials/config.
  • SUB MID и SUB MID AGGREGATOR можно soft-delete даже если по ним есть transactions.
  • Historical transactions хранят execution snapshot выбранного SUB MID / SUB MID AGGREGATOR.
  • Platform Admin может настроить expiration time на SUB MID.
  • Platform Admin может настроить velocity limits.
  • Platform Admin может настроить FX / fees.
  • Platform Admin может создать platform user или merchant user.
  • Если в системе нет пользователей, можно создать первого platform user через bootstrap flow.
  • Первому platform user автоматически выдается role Admin со всеми permissions.
  • Platform Admin может создать роли отдельно для platform / merchant contexts.
  • Пользователю можно выдать роль в контексте merchant.
  • Пользователю можно выдать роль в контексте merchant group.
  • Merchant user может быть создан без merchant / merchant group access.
  • User без access context видит пустой Back Office.
  • User type после создания не меняется в MVP.
  • User email уникален и не переиспользуется после soft-delete.
  • Merchant user с нужной permission может приглашать пользователей только в доступный ему merchant context.
  • Доступ к merchant group user-ам выдает только platform user с permission.
  • Повторный invite на существующий email возвращает ошибку.
  • Expired invite можно отправить повторно через resend invite action.
  • Отдельный invite status CANCELED в MVP не нужен.
  • Изменения role/permissions применяются сразу.
  • Изменение состава merchant group сразу влияет на group-based access.
  • Один merchant может входить только в одну merchant group.
  • Merchant group используется только для grouping/access.
  • Merchant group создают только platform users.
  • Merchants в merchant group добавляют/удаляют только platform users.
  • Автоматическое изменение access из-за изменения состава merchant group пишется в audit log.
  • INACTIVE/DELETED role удаляется у users.
  • DISABLED user можно вернуть в ACTIVE.
  • DELETED user нельзя восстановить.
  • User видит active sessions, session history и security events.
  • User invitation работает через email link.
  • Password reset работает через email message с кодом.
  • Пользователь может управлять своими active sessions.
  • Merchant может создать API key.
  • Merchant может создать новый API key с grace period для rotation.
  • API key rotation grace period поддерживает варианты 1 час, 3 часа, 12 часов и 24 часа.
  • Merchant может создать deposit через API.
  • Customer может открыть hosted payment form.
  • Customer может завершить payment flow.
  • Provider callback обрабатывается системой.
  • Merchant webhook отправляется и retry работает.
  • Merchant user может сделать webhook resend, если у него есть permission.
  • Manual webhook resend требует reason/comment.
  • Transaction видна в Back Office и Merchant Portal.
  • Transaction timeline показывает полный flow.
  • Provider names скрыты от merchant users без нужных permissions.
  • Users / roles / permissions работают.
  • Provider access для merchant работает через permission-based управление.
  • Provider access выдается на уровне merchant к конкретному provider.
  • Provider access можно revoke.
  • Provider access grant/revoke пишется в audit log.
  • Provider access revoke не требует reason/comment.
  • Providers и provider methods хранятся в code registry.
  • Provider method показывается в UI только если он реализован в коде.
  • Provider method status в Back Office в MVP не нужен.
  • Test provider существует в MVP и поддерживает все MVP payment methods.
  • Sandbox/test flow работает внутри stg.
  • Отдельный sandbox environment не нужен.
  • Test provider доступен in prod.
  • Test provider in prod доступен всем merchants.
  • Test provider возвращает hosted redirect URL.
  • Test provider умеет симулировать PROCESSING, COMPLETED, FAILED, CANCELED, REJECTED.
  • Test provider умеет симулировать provider timeout and provider error response.
  • Merchant/admin может intentionally choose/simulate expected test outcome.
  • Test transactions помечаются как test.
  • Test transactions видны в normal transaction list/details.
  • Test transactions отправляют merchant webhooks.
  • Test transactions могут участвовать в velocity/fees/turnover в test context.
  • В Platform section есть раздел SUB MID Aggregators для platform-level SUB MID AGGREGATOR configurations.
  • В Merchant section есть раздел MASTER MID для merchant-scoped MASTER MID configurations.
  • В Merchant section есть раздел SUB MID для доступных merchant provider/acquirer configurations.
  • В Merchant section есть раздел Payment Method / MID, где можно создать configuration для payment method и добавить в routing доступные MASTER MID.
  • Audit log записывает важные действия.
  • У каждой важной сущности есть audit logs visibility для пользователей с permission.
  • Soft-delete actions в Back Office требуют confirmation modal and reason/comment.
  • Обычные сущности, которые не влияют напрямую на routing/payment execution, используют обычный Save.
  • Transaction correction доступна пользователю с permission.
  • Transaction correction требует reason/comment.
  • При transaction correction можно выставить final status.
  • Correction final status не ограничивается текущим статусом transaction.
  • При transaction correction можно выбрать, делать ли resend callback / webhook на все webhook URLs transaction.
  • Transaction может перейти в CANCELED, если transaction/payment session expired по настройке SUB MID.
  • Historical transactions можно перенести из старой системы.
  • Migrated transactions помечаются как legacy.
  • Legacy transactions видны как legacy badge/marker в transaction list и transaction details.
  • Transaction list позволяет скрывать/показывать все columns, кроме transaction ID.
  • Transaction table column settings сохраняются на client side.
  • Transaction details показывает merchant-safe Routing tab merchant user-у всегда.
  • Merchant webhook raw payloads видны merchant user-у с permission.
  • Raw provider payloads видны только platform user-у с permission.
  • Manual correction доступна из transaction details для любых statuses при наличии permission.
  • Webhook resend доступен из transaction details на PROCESSING and final statuses при наличии permission.
  • Empty states в Back Office показывают No data yet.
  • Первый merchant переводится на v2 постепенно, payment method за payment method.
  • MVP принимает Product Owner.
  • Public merchant documentation portal готов.
  • Documentation owner: Product Owner.
  • Public documentation содержит HMAC request signing examples на нескольких programming languages.
  • Public documentation содержит webhook signature validation examples.
  • Public documentation содержит transaction statuses, error codes and sandbox/test flow.
  • Public documentation разделяет stg/prod base URLs.
  • API keys are environment-local.
  • Webhook signing secret/key material is merchant-specific and environment-local.
  • Postman collection и OpenAPI spec не обязательны как merchant-facing MVP deliverables.
  • Troubleshooting section не обязательна в MVP.
  • Отдельный standalone checklist для первого merchant не нужен.
  • Перед live traffic выполняется test deposit.
  • MVP считается принятым, если первый live deposit успешно создан через /api/v2/deposit, webhook доставлен merchant-у, transaction видна в Back Office, а routing/timeline понятны для investigation.
  • MVP acceptance требует прохождения обязательных UAT/demo scenarios.
  • Load test обязателен для MVP acceptance.
  • Отдельный technical rollback / feature flag / migrated-to-v2 marker не нужен в MVP.
  • 2FA обязательна in dev/stg/prod, login without 2FA в dev/stg не разрешается.
  • Required tests должны проходить перед release.
  • Любой fail обязательного test layer блокирует release.
  • Support может расследовать transaction без помощи разработчика.
  • Prometheus alerts срабатывают на падение success rate по provider, merchant и системе.
  • Each endpoint has schema and detailed description in Swagger