mufassall

Шпаргалка · Бизнес-процессы

Сверка платежей

14 мин · Средний · mufassall.dtwin.uz/ru/l/reconciliation/

← Открыть урок

Проблема

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

Чему вы научитесь

  • Почему журнал, собранный из колбэков, расходится с деньгами и почему суммы хранятся целыми в минимальных единицах
  • Сопоставление реестра расчётов по 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_pager

Mermaid: последовательность запросов

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 0

D2

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
@enduml

PlantUML: компоненты

@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%
Открытые кейсы011

Шаги

  1. Кейс Журнал пишется по ответам и колбэкам

    Покупатель платит на странице оплаты.

  2. Проблема Журнал и деньги расходятся

    Вызов списания падает по таймауту через 10 с, и API помечает заказ failed.

  3. Решение Реестр расчётов провайдера

    Каждое утро провайдер публикует вчерашний реестр файлом (или API с постраничным чтением): строка на каждое проведённое списание, возврат и комиссию.

  4. Решение Задача сверки соединяет реестр с журналом

    Задача загружает файл в промежуточную таблицу и соединяет его с журналом по id транзакции провайдера и валюте.

  5. Кейс Каждое расхождение попадает в один из четырёх классов

    Задача размечает каждую строку, которая не сошлась чисто.

  6. Решение Безопасный класс исправляется автоматически, с записью в аудит

    По каждой строке missing_ours задача ещё раз спрашивает API статусов провайдера.

  7. Решение Всё остальное уходит в очередь ручной проверки с SLA

    Остальные 11 случаев становятся кейсами проверки.

  8. Решение Итоги дня по каждой валюте

    Построчное сопоставление может пропустить то, что поймает сумма: изменившееся правило комиссии, строку, которую пропустил парсер.

  9. Проблема Перезапуск исправляет одно и то же дважды

    Провайдер нашёл ошибку и прислал вчерашний реестр заново.

  10. Решение У каждого исправления есть ключ, перезапуск ничего не меняет

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

  11. Итоги Итог

    Пять правил сверки.

Термины

Сверка (reconciliation)
Сравнение своего журнала с внешней записью тех же денег и разбор каждого расхождения.
Реестр расчётов
Ежедневный (T+1) список провайдера по всем реально проведённым списаниям, возвратам и комиссиям.
Минимальные единицы
Хранение денег целым числом в наименьших единицах (тийины, центы), чтобы суммы были точными.