Шпаргалка · Бизнес-процессы
Сверка платежей
Проблема
Магазин записывает карточные платежи по ответам и колбэкам провайдера. Часть из них теряется, падает по таймауту или приходит дважды, и журнал платежей расходится с реальными деньгами. Каждое утро задача сверяет журнал с реестром расчётов провайдера, исправляет то, что безопасно, и отдаёт остальное человеку.
Чему вы научитесь
- Почему журнал, собранный из колбэков, расходится с деньгами и почему суммы хранятся целыми в минимальных единицах
- Сопоставление реестра расчётов по id транзакции провайдера, валюте и окну дат
- Четыре класса расхождений: какой задача исправит сама, а какие уйдут в очередь ручной проверки
- Итоги дня по валютам, алерты и перезапуски, которые не исправляют одно и то же дважды
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_api["API платежей"]
n_provider>"Провайдер"]
n_ledger[("Журнал платежей")]
n_files[("Реестры расчётов")]
n_recon("Задача сверки")
n_review[["Очередь проверки"]]
n_analyst(("Финансист"))
n_pager>"Алерт дежурному"]
n_api --> n_provider
n_provider -.-> n_api
n_api --> n_ledger
n_provider --> n_files
n_files --> n_recon
n_recon --> n_ledger
n_recon --> n_provider
n_recon --> n_review
n_review --> n_analyst
n_recon --x n_pagerMermaid: последовательность запросов
sequenceDiagram
participant n_provider as Провайдер
participant n_api as API платежей
participant n_files as Реестры расчётов
participant n_recon as Задача сверки
participant n_ledger as Журнал платежей
participant n_review as Очередь проверки
participant n_pager as Алерт дежурному
Note over n_provider,n_api: Журнал пишется по ответам и колбэкам
n_provider->>n_api: POST /payments/callback HTTP/1.1
n_api-->>n_provider: HTTP/1.1 200 OK
Note over n_api,n_provider: Журнал и деньги расходятся
n_api->>n_provider: 10:20:31 POST /v1/charges ord_3307 amount_minor=4500
Note over n_provider,n_files: Реестр расчётов провайдера
n_provider->>n_files: settlement_2026-11-17.csv (T+1, ready at 06:00 UTC)
Note over n_recon,n_ledger: Задача сверки соединяет реестр с журналом
n_recon->>n_ledger: SELECT s.provider_txn_id, s.amount_minor AS theirs,
n_ledger-->>n_recon: 48 202 rows
Note over n_recon,n_ledger: Каждое расхождение попадает в один из четырёх классов
n_recon->>n_ledger: recon 2026-11-17: 48 198 provider lines, 48 183 ledger rows
Note over n_recon,n_provider: Безопасный класс исправляется автоматически, с записью в аудит
n_recon->>n_provider: GET /v1/payments/ptx_8813 HTTP/1.1
n_provider-->>n_recon: HTTP/1.1 200 OK
Note over n_recon,n_review: Всё остальное уходит в очередь ручной проверки с SLA
n_recon->>n_review: review_case (new)
Note over n_recon,n_pager: Итоги дня по каждой валюте
n_recon->>n_pager: ALERT recon.totals day=2026-11-17
Note over n_recon,n_ledger: Перезапуск исправляет одно и то же дважды
n_recon->>n_ledger: 06:40 provider re-sent settlement_2026-11-17.csv (v2)
Note over n_recon,n_ledger: У каждого исправления есть ключ, перезапуск ничего не меняет
n_recon->>n_ledger: INSERT INTO recon_fixes (report_date, provider_txn_id, action)
n_ledger-->>n_recon: INSERT 0 0D2
direction: right
n_api: "API платежей" {
shape: rectangle
}
n_provider: "Провайдер" {
shape: cloud
}
n_ledger: "Журнал платежей" {
shape: cylinder
}
n_files: "Реестры расчётов" {
shape: stored_data
}
n_recon: "Задача сверки" {
shape: rectangle
style.multiple: true
}
n_review: "Очередь проверки" {
shape: queue
}
n_analyst: "Финансист" {
shape: person
}
n_pager: "Алерт дежурному" {
shape: cloud
}
n_api -> n_provider
n_provider -> n_api {
style.stroke-dash: 3
}
n_api -> n_ledger
n_provider -> n_files
n_files -> n_recon
n_recon -> n_ledger
n_recon -> n_provider
n_recon -> n_review
n_review -> n_analyst
n_recon -> n_pager {
target-arrowhead.shape: cross
}PlantUML: последовательность запросов
@startuml
boundary "Провайдер" as n_provider
participant "API платежей" as n_api
database "Реестры расчётов" as n_files
participant "Задача сверки" as n_recon
database "Журнал платежей" as n_ledger
queue "Очередь проверки" as n_review
boundary "Алерт дежурному" as n_pager
note over n_provider, n_api : Журнал пишется по ответам и колбэкам
n_provider -> n_api : POST /payments/callback HTTP/1.1
n_api --> n_provider : HTTP/1.1 200 OK
note over n_api, n_provider : Журнал и деньги расходятся
n_api -> n_provider : 10:20:31 POST /v1/charges ord_3307 amount_minor=4500
note over n_provider, n_files : Реестр расчётов провайдера
n_provider -> n_files : settlement_2026-11-17.csv (T+1, ready at 06:00 UTC)
note over n_recon, n_ledger : Задача сверки соединяет реестр с журналом
n_recon -> n_ledger : SELECT s.provider_txn_id, s.amount_minor AS theirs,
n_ledger --> n_recon : 48 202 rows
note over n_recon, n_ledger : Каждое расхождение попадает в один из четырёх классов
n_recon -> n_ledger : recon 2026-11-17: 48 198 provider lines, 48 183 ledger rows
note over n_recon, n_provider : Безопасный класс исправляется автоматически, с записью в аудит
n_recon -> n_provider : GET /v1/payments/ptx_8813 HTTP/1.1
n_provider --> n_recon : HTTP/1.1 200 OK
note over n_recon, n_review : Всё остальное уходит в очередь ручной проверки с SLA
n_recon -> n_review : review_case (new)
note over n_recon, n_pager : Итоги дня по каждой валюте
n_recon -> n_pager : ALERT recon.totals day=2026-11-17
note over n_recon, n_ledger : Перезапуск исправляет одно и то же дважды
n_recon -> n_ledger : [дубль] 06:40 provider re-sent settlement_2026-11-17.csv (v2)
note over n_recon, n_ledger : У каждого исправления есть ключ, перезапуск ничего не меняет
n_recon -> n_ledger : INSERT INTO recon_fixes (report_date, provider_txn_id, action)
n_ledger --> n_recon : INSERT 0 0
@endumlPlantUML: компоненты
@startuml
left to right direction
component "API платежей" as n_api
cloud "Провайдер" as n_provider
database "Журнал платежей" as n_ledger
storage "Реестры расчётов" as n_files
collections "Задача сверки" as n_recon
queue "Очередь проверки" as n_review
actor "Финансист" as n_analyst
cloud "Алерт дежурному" as n_pager
n_api --> n_provider
n_provider ..> n_api
n_api --> n_ledger
n_provider --> n_files
n_files --> n_recon
n_recon --> n_ledger
n_recon --> n_provider
n_recon --> n_review
n_review --> n_analyst
n_recon -[#c62828]-> n_pager
@endumlИтог
Пять правил сверки.
1) Храните суммы целыми в минимальных единицах вместе с валютой. 2) Каждый день сопоставляйте реестр провайдера с журналом по его id транзакции, валюте и расширенному окну дат. 3) Классифицируйте каждое расхождение; автоматически исправляйте только подтверждённые провайдером строки, только вперёд и с записью в аудит. 4) Остальное отправляйте в очередь проверки с обеими сторонами и SLA и сверяйте итоги по валютам, чтобы необъяснённые деньги не спрятались. 5) Дайте ключ каждому исправлению и кейсу, чтобы перезапуск ничего не менял.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Расхождения | 0/день | 35/день |
| Несведённая сумма | 0 $ | 1 950 $ |
| Исправлено автоматически | 0% | 68% |
| Открытые кейсы | 0 | 11 |
Шаги
- Кейс Журнал пишется по ответам и колбэкам
Покупатель платит на странице оплаты.
- Проблема Журнал и деньги расходятся
Вызов списания падает по таймауту через 10 с, и API помечает заказ
failed. - Решение Реестр расчётов провайдера
Каждое утро провайдер публикует вчерашний реестр файлом (или API с постраничным чтением): строка на каждое проведённое списание, возврат и комиссию.
- Решение Задача сверки соединяет реестр с журналом
Задача загружает файл в промежуточную таблицу и соединяет его с журналом по id транзакции провайдера и валюте.
- Кейс Каждое расхождение попадает в один из четырёх классов
Задача размечает каждую строку, которая не сошлась чисто.
- Решение Безопасный класс исправляется автоматически, с записью в аудит
По каждой строке
missing_oursзадача ещё раз спрашивает API статусов провайдера. - Решение Всё остальное уходит в очередь ручной проверки с SLA
Остальные 11 случаев становятся кейсами проверки.
- Решение Итоги дня по каждой валюте
Построчное сопоставление может пропустить то, что поймает сумма: изменившееся правило комиссии, строку, которую пропустил парсер.
- Проблема Перезапуск исправляет одно и то же дважды
Провайдер нашёл ошибку и прислал вчерашний реестр заново.
- Решение У каждого исправления есть ключ, перезапуск ничего не меняет
Прежде чем менять журнал, задача вставляет исправление в
recon_fixesс уникальным ключом. - Итоги Итог
Пять правил сверки.
Термины
- Сверка (reconciliation)
- Сравнение своего журнала с внешней записью тех же денег и разбор каждого расхождения.
- Реестр расчётов
- Ежедневный (T+1) список провайдера по всем реально проведённым списаниям, возвратам и комиссиям.
- Минимальные единицы
- Хранение денег целым числом в наименьших единицах (тийины, центы), чтобы суммы были точными.