Архитектура мультибанковского платёжного агрегатора

Задача

• Описать многоуровневую цепочку денег — банк-эквайер, агрегатор, мерчант, магазин — так, чтобы средства мерчантов лежали на номинальном счёте и не смешивались с деньгами агрегатора.
• Маршрутизировать платежи между банками отдельно для каждого мерчанта и способа оплаты и быстро переключаться, если банк сбоит или отклоняет трафик мерчанта.
• Проводить долгие сценарии с ненадёжными звеньями — вызовы банков, вебхуки, таймауты — без потери денег и двойного учёта.
• Соблюсти требования к фискальным чекам при оплате, отмене и частичном возврате, в том числе для корзин маркетплейса с несколькими продавцами.
• Убрать бэк-офис оператора из публичного интернета и заложить рост от примерно 100 RPS до 1 000+ RPS в пике с понятной схемой отказоустойчивости.

Решение

Мы передали комплект архитектурных документов, диаграмм последовательностей и компонентов и небольшие эталонные реализации, разложенные по областям. Бизнес-домен — единый словарь, доменная модель и сценарии депозита, подключения мерчанта и магазина, отмены и частичного возврата в маркетплейсе. Бэкенд — слоистая структура сервиса на FastAPI (роуты → сервисы → доступ к данным), модель данных и паттерны саг оплаты и возврата на Temporal. Фронтенд — паттерны кабинета мерчанта и бэк-офиса на React и TypeScript с OIDC и PKCE. IAM — дизайн realm и ролей в Keycloak и миграции конфигурации доступа в коде. Инфраструктура — VPC с публичными и приватными подсетями, корпоративный VPN, варианты HA для базы, регламент переключения active-passive и раскладка CI/CD в GitLab с разделением ответственности.

Что умеет система

Платёжная страница и API

Мерчант создаёт платёж через REST API и перенаправляет плательщика на платёжную страницу, где доступны карта, оплата по QR-коду и кошелёк.

Умная маршрутизация

Приоритеты банков для каждого мерчанта и способа оплаты, ручное принудительное переключение и автоматическое отключение банка, когда число ошибок превышает порог.

Сплит на номинальном счёте

Каждый платёж несёт настройки сплита, поэтому доля мерчанта и комиссия агрегатора разделяются на стороне банка при зачислении на номинальный счёт.

Полный жизненный цикл платежа

Счета с TTL и статусами, несколько попыток оплаты одного счёта, полный и частичный возврат, отмена до расчёта и чарджбэки. В маркетплейсе возвращается только доля затронутого продавца, а данные чека идут вместе с платежом и возвратом.

Подключение мерчантов и магазинов

Сначала идентификация, затем проверка бизнеса (KYB) у внешнего провайдера; запись о компании появляется только после положительного ответа. Магазин подтверждает владение доменом, проходит комплаенс и получает боевые API-ключи.

Кабинет мерчанта и бэк-офис

В кабинете — команда с 40+ детальными правами на статистику, балансы, платежи, выплаты, магазины, вебхуки и пользователей. В бэк-офисе — правила маршрутизации, мониторинг банков, индивидуальные комиссии, блокировки и журнал аудита.

Инженерные решения

• Саги оплаты и возврата — это workflow на Temporal. Вебхуки банков приходят в workflow как сигналы, а платёж, не подтверждённый за TTL, корректно истекает. Цена — ещё один stateful-компонент, взамен команда получает ретраи, таймауты и видимое состояние каждого платежа вместо самописных конечных автоматов и cron-задач.
• Журнал операций отделён от состояния платежа. Счёт описывает состояние платёжной сессии, а транзакция — неизменяемый факт движения денег с порядковым номером внутри мерчанта и балансом до и после. Балансы считаются из журнала, поэтому их можно проверить и восстановить на любой момент.
• Тройная сверка перед возвратом: сумма возврата, сумма долей продавцов и сумма позиций чека должны совпасть до любого вызова банка. Расхождение ловится у нас, а не в банке или в чеке.
• Банки подключаются через адаптеры, а маршрутизация хранится в данных: банки, терминалы и приоритеты — это записи в базе, учётные данные терминалов шифруются на уровне колонок. Новый банк — это адаптер и конфигурация, без изменения схемы.
• Для высокой доступности сравнили два варианта с честной ценой: управляемый кластер PostgreSQL с синхронной репликацией между зонами (RPO = 0, автоматическое переключение, дороже) и пару active-passive с асинхронной репликацией. Для второго варианта написали пошаговый регламент: обнаружение, повышение реплики, переключение трафика и пересборка старого primary как реплики.

Стек

• Python
• FastAPI
• SQLAlchemy
• Temporal
• PostgreSQL
• Keycloak
• OAuth 2.0 / OIDC
• React
• TypeScript
• GitLab CI
• OpenTofu
• Helm
• Docker
• Nginx

Что это показывает

• Бизнес-задача превращена в архитектуру регулируемого платёжного продукта, по которой можно строить ещё до первой строки боевого кода.
• Денежные потоки описаны через доменную модель: иерархия агрегатора, номинальные счета, сплиты, журнал операций, возвраты и чарджбэки.
• Надёжные распределённые сценарии вокруг ненадёжных API и вебхуков банков, с маршрутизацией и переключением между провайдерами.
• Безопасность и инфраструктура для финтеха: централизованный IAM, детальный RBAC, закрытый бэк-офис, шифрование секретов, подписанные вебхуки, белые списки IP и план HA с понятными компромиссами.

Вопросы по кейсу