Обзор сценариев
Система выплат поддерживает два основных способа взаимодействия в зависимости от потребностей пользователя:
- Выплаты через интерфейс - работа через веб-интерфейс личного кабинета
- Выплаты через API - интеграция с внешними системами через REST API
Каждый способ поддерживает выплаты как на банковские карты, так и через СБП (Систему быстрых платежей).
Выплаты через интерфейс
Работа с системой через веб-интерфейс личного кабинета. Поддерживает как массовые выплаты через файлы, так и одиночные выплаты через формы.
1.1. Выплаты через файл (карты/СБП)
Процесс проведения массовых выплат через загрузку файла. Поддерживаются направления: банковские карты и СБП.
Описание процесса
- Пользователь загружает файл с данными получателей или заполняет форму одиночной выплаты
- Система валидирует данные получателей (номер карты, сумма, ФИО)
- Пользователь подтверждает создание выплат
- Система создает записи о выплатах в базе данных
- Фоновые процессы обрабатывают выплаты через банковский API
- Пользователь отслеживает статус через интерфейс
- Получает уведомления о результатах
Диаграмма последовательности
sequenceDiagram
participant U as Пользователь
participant UI as Личный кабинет
participant SYS as Система выплат
participant BANK as Банковский процессинг
activate U
U->>UI: Загружает файл (карты/СБП)
activate UI
UI->>SYS: Отправка файла на проверку
activate SYS
SYS->>SYS: Сохранение файла (черновик)
SYS-->>UI: Предварительный просмотр (валидированные данные)
deactivate SYS
UI-->>U: Отображение предпросмотра
deactivate UI
deactivate U
activate U
U->>UI: Подтверждает создание выплат
activate UI
UI->>SYS: Команда создать выплаты
activate SYS
SYS->>SYS: Создание записей выплат
SYS-->>UI: Успешное создание
deactivate SYS
UI->>U: Отображение результатов
deactivate UI
loop Обработка выплат (асинхронно)
activate SYS
SYS->>SYS: Обработка задач
SYS->>BANK: Выполнение выплаты
activate BANK
BANK-->>SYS: Результат операции
deactivate BANK
SYS->>SYS: Обновление статуса
deactivate SYS
end
U->>UI: Проверяет статус выплат
activate UI
UI->>SYS: Запрос статусов
activate SYS
SYS->>SYS: Получение данных
SYS-->>UI: Данные о выплатах
deactivate SYS
UI-->>U: Отображение результатов
deactivate UI
deactivate U
1.2. Одиночная выплата вручную
Создание одной выплаты через форму в интерфейсе: банковская карта или СБП.
Описание процесса
- Пользователь открывает форму одиночной выплаты
- Вводит данные получателя (карта или СБП: телефон, банк, ФИО) и сумму
- Система валидирует данные в реальном времени
- Пользователь подтверждает создание
- Система создает запись выплаты и запускает обработку
- Статус обновляется асинхронно, доступны уведомления
Диаграмма последовательности
sequenceDiagram
participant U as Пользователь
participant UI as Личный кабинет
participant SYS as Система выплат
participant BANK as Банковский процессинг
activate U
U->>UI: Запрашивает проведение одиночной выплаты
activate UI
UI-->>U: Открывает форму одиночной выплаты
deactivate UI
U->>UI: Вводит реквизиты (карта/СБП) и сумму
activate UI
UI->>SYS: Онлайн-валидация данных
activate SYS
SYS-->>UI: Результат валидации
deactivate SYS
UI-->>U: Отображение результата валидации
deactivate UI
U->>UI: Подтверждает создание
activate UI
UI->>SYS: Создать выплату
activate SYS
SYS->>SYS: Запись выплаты
SYS-->>UI: Создание принято
deactivate SYS
UI-->>U: Отображение результата создания
deactivate UI
Note over SYS,BANK: Асинхронная обработка
activate SYS
SYS->>BANK: Отправка выплаты
activate BANK
BANK-->>SYS: Результат операции
deactivate BANK
SYS->>SYS: Обновление статуса
deactivate SYS
U->>UI: Проверяет статус выплат
activate UI
UI->>SYS: Запрос статусов
activate SYS
SYS->>SYS: Получение данных
SYS-->>UI: Данные о выплатах
deactivate SYS
UI-->>U: Отображение результатов
deactivate UI
deactivate U
Выплаты через API
Интеграция с внешними системами через REST API. Поддерживает два варианта работы: создание заявки с переходом на страницу системы или полное выполнение через API.
2.1. Создание заявки через createPayout
Внешняя система создает заявку на выплату, пользователь переходит на страницу системы для подтверждения.
Описание процесса
- Внешняя система получает Bearer токен для авторизации
- Создает заявку на выплату через API createPayout
- Система валидирует данные и создает заявку
- Возвращает URL для перехода пользователя
- Пользователь переходит по ссылке и подтверждает выплату
- Система выполняет выплату через банковский API
- Внешняя система может запросить статус через getPayoutStatus
Диаграмма последовательности
sequenceDiagram
participant ES as Внешняя система
participant API as API системы
participant U as Пользователь
participant UI as Страница подтверждения
participant SYS as Система выплат
participant BANK as Банковский процессинг
activate ES
ES->>API: POST /api/v1/createPayout
(Bearer token, данные выплаты) activate API API->>SYS: Валидация и создание заявки activate SYS SYS-->>API: Заявка создана deactivate SYS API-->>ES: 200 OK (URL для подтверждения) deactivate API ES->>U: Перенаправление на URL deactivate ES activate U U->>UI: Открывает страницу подтверждения activate UI UI->>SYS: Получение данных заявки activate SYS SYS-->>UI: Данные заявки deactivate SYS UI-->>U: Показывает данные для подтверждения deactivate UI U->>UI: Подтверждает выплату activate UI UI->>SYS: Выполнение выплаты activate SYS par Обработка и отображение результата SYS-->>UI: Уведомление о принятии к обработке и перенаправление на страницу результата deactivate SYS UI-->>U: Перенаправление на страницу результата deactivate UI U->>UI: Открывает страницу результата activate UI SYS->>BANK: Отправка в банк activate SYS activate BANK BANK-->>SYS: Результат операции deactivate BANK end loop Обработка выплаты UI->>SYS: Запрос статуса SYS-->>UI: Статус выполнения deactivate SYS UI-->>U: Результат операции deactivate UI deactivate U end activate ES ES->>API: GET /api/v1/getPayoutStatus
(ID заявки) activate API API->>SYS: Запрос статуса activate SYS SYS-->>API: Текущий статус deactivate SYS API-->>ES: 200 OK (статус и детали) deactivate API deactivate ES
(Bearer token, данные выплаты) activate API API->>SYS: Валидация и создание заявки activate SYS SYS-->>API: Заявка создана deactivate SYS API-->>ES: 200 OK (URL для подтверждения) deactivate API ES->>U: Перенаправление на URL deactivate ES activate U U->>UI: Открывает страницу подтверждения activate UI UI->>SYS: Получение данных заявки activate SYS SYS-->>UI: Данные заявки deactivate SYS UI-->>U: Показывает данные для подтверждения deactivate UI U->>UI: Подтверждает выплату activate UI UI->>SYS: Выполнение выплаты activate SYS par Обработка и отображение результата SYS-->>UI: Уведомление о принятии к обработке и перенаправление на страницу результата deactivate SYS UI-->>U: Перенаправление на страницу результата deactivate UI U->>UI: Открывает страницу результата activate UI SYS->>BANK: Отправка в банк activate SYS activate BANK BANK-->>SYS: Результат операции deactivate BANK end loop Обработка выплаты UI->>SYS: Запрос статуса SYS-->>UI: Статус выполнения deactivate SYS UI-->>U: Результат операции deactivate UI deactivate U end activate ES ES->>API: GET /api/v1/getPayoutStatus
(ID заявки) activate API API->>SYS: Запрос статуса activate SYS SYS-->>API: Текущий статус deactivate SYS API-->>ES: 200 OK (статус и детали) deactivate API deactivate ES
2.2. Полное выполнение через performPayout
Внешняя система создает заявку на выплату через API, система выполняет выплату асинхронно в фоне.
Описание процесса
- Внешняя система получает Bearer токен для авторизации
- Создает заявку на выплату через API performPayout
- Система валидирует данные, создает заявку и сразу возвращает ответ
- Фоновые процессы асинхронно выполняют выплату через банковский API
- Внешняя система может запросить статус через getPayoutStatus
Диаграмма последовательности
sequenceDiagram
participant ES as Внешняя система
participant API as API системы
participant SYS as Система выплат
participant BANK as Банковский процессинг
activate ES
ES->>API: POST /api/v1/performPayout
(Bearer token, данные выплаты) activate API API->>SYS: Валидация данных activate SYS SYS->>SYS: Создание заявки SYS-->>API: Заявка принята deactivate SYS API-->>ES: 200 OK (заявка создана) deactivate API deactivate ES Note over SYS,BANK: Асинхронная обработка в фоне loop Обработка выплат activate SYS SYS->>SYS: Обработка задач SYS->>BANK: Выполнение выплаты activate BANK BANK-->>SYS: Результат операции deactivate BANK SYS->>SYS: Обновление статуса deactivate SYS end activate ES ES->>API: GET /api/v1/getPayoutStatus
(ID заявки) activate API API->>SYS: Запрос статуса activate SYS SYS->>SYS: Получение данных SYS-->>API: Статус заявки deactivate SYS API-->>ES: 200 OK (статус и детали) deactivate API deactivate ES
(Bearer token, данные выплаты) activate API API->>SYS: Валидация данных activate SYS SYS->>SYS: Создание заявки SYS-->>API: Заявка принята deactivate SYS API-->>ES: 200 OK (заявка создана) deactivate API deactivate ES Note over SYS,BANK: Асинхронная обработка в фоне loop Обработка выплат activate SYS SYS->>SYS: Обработка задач SYS->>BANK: Выполнение выплаты activate BANK BANK-->>SYS: Результат операции deactivate BANK SYS->>SYS: Обновление статуса deactivate SYS end activate ES ES->>API: GET /api/v1/getPayoutStatus
(ID заявки) activate API API->>SYS: Запрос статуса activate SYS SYS->>SYS: Получение данных SYS-->>API: Статус заявки deactivate SYS API-->>ES: 200 OK (статус и детали) deactivate API deactivate ES
2.3. Выплаты на карты через API
Специфика работы с банковскими картами через API.
Особенности
- Требуется шифрование номера карты публичным ключом
- Поддержка идемпотентности через orderNumber
- Автоматическое получение access token и публичного ключа
- Интеграция с банковским API ВТБ
2.4. Выплаты через СБП через API
Специфика работы с СБП через API.
Особенности
- Требуется указание телефона получателя в формате 79XXXXXXXXX
- Обязательно указание банка получателя и ФИО
- Двухэтапный процесс: CHECK → CONFIRM
- Автоматическая обработка статусов от СБП
Обработка ошибок и исключительных ситуаций
Стандартные сценарии обработки ошибок во всех типах выплат.
Типы ошибок
- Ошибки валидации - некорректные данные получателя
- Ошибки авторизации - недействительный токен или недостаточные права
- Ошибки банковского API - проблемы с обработкой платежа
- Системные ошибки - недоступность сервисов
- Ошибки лимитов - превышение установленных ограничений
Сценарий обработки ошибок
sequenceDiagram
participant U as Пользователь/Система
participant API as API системы
participant VAL as Валидатор
participant BANK as Банковский процессинг
participant LOG as Логгер
participant RETRY as Система повторов
U->>API: Запрос на выплату
API->>VAL: Валидация данных
alt Ошибка валидации
VAL-->>API: Ошибка валидации
API->>LOG: Логирование ошибки
API-->>U: 400 Bad Request
else Данные корректны
API->>BANK: Выполнение выплаты
alt Ошибка банка
BANK-->>API: Ошибка операции
API->>LOG: Логирование ошибки
API->>RETRY: Планирование повтора
API-->>U: 502 Bad Gateway
else Успешная операция
BANK-->>API: Успех
API-->>U: 200 OK
end
end
Мониторинг и уведомления
Система мониторинга операций и уведомлений пользователей.
Каналы уведомлений
- Веб-интерфейс - уведомления в личном кабинете
- Telegram - push-уведомления в боте
- Email - письма на зарегистрированный адрес
- API - webhook-уведомления для внешних систем
Диаграмма системы уведомлений
sequenceDiagram
participant PROC as Система выплат
participant NOTIF as Система уведомлений
participant TG as Telegram Bot
participant EMAIL as Email сервис
participant WEB as Веб-интерфейс
participant WH as Webhook
PROC->>PROC: Обновление статуса выплаты
PROC->>NOTIF: Триггер уведомления
par Уведомления пользователю
NOTIF->>WEB: Обновление в интерфейсе
NOTIF->>TG: Push-уведомление
NOTIF->>EMAIL: Email уведомление
and Уведомления системам
NOTIF->>WH: Webhook уведомление
end
Рекомендации и лучшие практики
Для разработчиков
- Всегда используйте idempotency ключи для предотвращения дублирования
- Реализуйте retry-логику с экспоненциальной задержкой
- Валидируйте данные на стороне клиента перед отправкой
- Используйте webhook-уведомления для отслеживания статусов
- Логируйте все операции для отладки и аудита
Для пользователей
- Проверяйте данные получателей перед созданием выплат
- Используйте тестовые выплаты для проверки настроек
- Настройте уведомления в Telegram для оперативного контроля
- Регулярно проверяйте отчеты и статистику
- Следите за лимитами и квотами системы