Системный дизайн платёжной системы: ledger, идемпотентность, PSP, вебхуки и сверка

Как спроектировать платёжную систему на system design интервью: требования, деньги в целых копейках, double-entry ledger, идемпотентность, работа с PSP, вебхуки, ретраи и сверка.

13 мин чтениясистемный дизайн · платежи · надёжность · python

Коротко

ВопросРешение в этом разборе
Нагрузка10 млн платежей в сутки: около 120 в секунду в среднем, до 1–2 тыс. в пике распродаж
Главный приоритеткорректность, а не пропускная способность: потерянная копейка хуже лишних 200 мс
Деньгицелые числа в минимальных единицах валюты (BIGINT копеек) или Decimal, никогда float
Учётdouble-entry ledger: неизменяемые проводки, сумма по каждой транзакции равна нулю
Повторыключ идемпотентности на каждой границе: клиент → мы, мы → PSP, вебхук → мы, событие → ledger
Внешний миркарты обрабатывает PSP; таймаут — это статус unknown, а не failed
Вебхукипроверка подписи, быстрый 200, дедупликация по id события, монотонная машина состояний
Страховкаежедневная сверка с отчётом PSP и банковской выпиской ловит всё, что пропустил код

Платёжную систему дают на интервью не из-за нагрузки: 120 запросов в секунду выдержит один сервер. Её дают, потому что здесь нельзя ответить «будет eventual consistency, пользователь обновит страницу». Деньги не должны появляться из воздуха и пропадать. А между вами и банком лежит сеть, которая теряет ответы, провайдер, который шлёт вебхуки по три раза, и пользователь, который жмёт «Оплатить» дважды.

Общий порядок секции описан в статье про подходы к проектированию систем. Здесь идём по нему же: требования, оценка, API, архитектура, а потом вглубь — ledger, идемпотентность, PSP, вебхуки, ретраи, сверка.

Шаг 1. Требования

Первым делом уточните, что именно проектируем. «Платёжная система» — это может быть и процессинг карт уровня банка, и платёжный сервис маркетплейса. На интервью почти всегда имеют в виду второе.

ВопросОтвет интервьюераЧто это меняет
Кто платит и кому?покупатели продавцам на маркетплейседеньги проходят через нас, нужен учёт долга продавцам
Мы сами обрабатываем карты?нет, через внешнего провайдера (PSP)номера карт к нам не попадают, PCI DSS проще
Нужны ли возвраты?да, полные и частичныеплатёж — не одна запись, а история операций
Выплаты продавцам?да, раз в деньотдельный поток payouts и баланс продавца
Несколько валют?да, но без конвертации внутрисумма всегда хранится вместе с валютой
Несколько PSP?пока один, но хотим уметь переключатьсяадаптер к PSP за общим интерфейсом
Кошелёк, кэшбэк, подписки?вне рамокне усложняем модель

Нефункциональные требования назовите сами, интервьюер ждёт именно их:

  • Ни одного двойного списания. Повтор запроса из-за таймаута не должен списать деньги второй раз.
  • Ни одной потерянной операции. Если PSP списал деньги, мы об этом узнаем, даже если ответ потерялся.
  • Полная история. Любой баланс можно объяснить списком операций, которые его сформировали. Задним числом ничего не правится.
  • Строгая согласованность для денег. Баланс продавца и проводки — в одной ACID-базе. Eventual consistency допустима для аналитики, уведомлений, поиска.
  • Доступность важна, но вторична. Лучше честно ответить «попробуйте позже», чем принять платёж, который потом не сойдётся.

Последний пункт — сознательный выбор в терминах CAP-теоремы: при сбое платёжный контур выбирает согласованность.

Шаг 2. Оценка нагрузки

Допущения:

  • 10 млн платежей в сутки. В распродажу пик в 10 раз выше среднего.
  • Каждый платёж порождает 3–5 проводок в ledger: списание, комиссии, возможный возврат, выплата.
  • Проводка с метаданными занимает около 200 байт.
  • Финансовые записи хранятся годами: сроки задают закон и аудиторы, а не мы.
ПараметрРасчётРезультат
Платежей в секунду10 млн / 86 400около 120
Пик120 × 10около 1 200 в секунду
Проводок в сутки10 млн × 440 млн
Объём ledger в сутки40 млн × 200 байт8 ГБ
Объём за год8 ГБ × 365около 3 ТБ без реплик

Выводы:

  1. По QPS это маленькая система. Один хорошо настроенный Postgres с репликами справится. Шардирование нужно не сразу, и то в основном из-за горячих счетов (о них ниже).
  2. Медленное звено — PSP. Ответ провайдера идёт сотни миллисекунд, а с 3-D Secure — десятки секунд, потому что пользователь вводит код. Синхронно ждать это в потоке запроса нельзя.
  3. Объём ledger растёт линейно и навсегда. Нужно партиционирование по времени и холодное хранилище для старых периодов.

Как быстро получать такие цифры, разобрано в статье про оценки на салфетке.

Шаг 3. Деньги не во float

Это первое, на чём проверяют внимательность. Двоичная плавающая точка не может точно хранить большинство десятичных дробей:

print(0.1 + 0.2) # 0.30000000000000004 print(0.1 + 0.2 == 0.3) # False print(round(2.675, 2)) # 2.67, а не 2.68 from decimal import Decimal, ROUND_HALF_UP print(Decimal("2.675").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)) # 2.68 print(Decimal(2.675)) # 2.67499999999999982236431605997495353221893310546875

round(2.675, 2) даёт 2.67 не из-за странного округления, а потому что в памяти лежит не 2.675, а 2.67499999…, что видно в последней строке. На миллионах операций такие ошибки складываются в рубли, которые не сходятся при сверке.

Два правильных способа:

  • Целое число минимальных единиц. 1499.90 ₽ хранится как 149990 копеек в BIGINT. Сложение и сравнение точные, индексы быстрые. Так делают большинство платёжных API.
  • Десятичный тип. NUMERIC(19, 4) в базе и Decimal в коде. Удобен, когда нужны доли копейки, например в курсах валют или начислении процентов.

Подвох в том, что «минимальная единица» у валют разная. По ISO 4217 у рубля и доллара два знака после запятой, у японской иены ноль, у кувейтского динара три. Поэтому сумма всегда хранится парой «число + валюта», а перевод делается по таблице:

from decimal import Decimal # ISO 4217: сколько знаков после запятой у валюты EXPONENT = {"RUB": 2, "USD": 2, "EUR": 2, "JPY": 0, "KWD": 3} def to_minor(amount: str, currency: str) -> int: exp = EXPONENT[currency] value = Decimal(amount).scaleb(exp) if value != value.to_integral_value(): raise ValueError(f"{amount} {currency}: слишком много знаков после запятой") return int(value) def from_minor(minor: int, currency: str) -> str: exp = EXPONENT[currency] return f"{Decimal(minor).scaleb(-exp):.{exp}f}" print(to_minor("1499.90", "RUB")) # 149990 print(to_minor("1500", "JPY")) # 1500 print(to_minor("1.234", "KWD")) # 1234 print(from_minor(149990, "RUB")) # 1499.90 try: to_minor("10.005", "USD") except ValueError as e: print(e) # 10.005 USD: слишком много знаков после запятой

Обратите внимание: сумма приходит строкой, а не числом. JSON-парсер во многих языках превратит 1499.90 во float раньше, чем код до него доберётся.

Деление без потерянных копеек

Вторая ловушка — деление. 100 ₽ на троих — это не 33.33 × 3, иначе копейка исчезнет. В маркетплейсе это происходит постоянно: комиссия площадки, доля продавца, частичный возврат заказа из нескольких товаров. Остаток нужно явно кому-то отдать:

def allocate(amount: int, weights: list[int]) -> list[int]: """Делит сумму в минимальных единицах пропорционально весам без потери копеек.""" total = sum(weights) parts = [amount * w // total for w in weights] remainder = amount - sum(parts) # остаток раздаём тем, у кого самая большая отброшенная дробная часть order = sorted(range(len(weights)), key=lambda i: -(amount * weights[i] % total)) for i in order[:remainder]: parts[i] += 1 return parts print(allocate(10000, [1, 1, 1])) # [3334, 3333, 3333]: 100.00 ₽ на троих print(allocate(999, [70, 30])) # [699, 300]: 9.99 ₽, 70% продавцу, 30% площадке assert sum(allocate(10000, [1, 1, 1])) == 10000

Инвариант простой: сумма частей всегда равна целому. Правило, кому достаётся лишняя копейка, должно быть детерминированным и записанным: бухгалтерия спросит.

Шаг 4. API и модель платежа

Клиент (фронтенд маркетплейса или сервис заказов) создаёт платёж:

POST /api/v1/payments Idempotency-Key: 0d6c5f3e-8a4b-4c1e-9f7a-2b1d8e6c4a90 { "order_id": "ord_777", "amount": "1499.90", "currency": "RUB", "payer_id": "usr_42", "merchant_id": "mrc_9", "return_url": "https://shop.example/orders/777" }

Ответ — 201 с payment_id, статусом pending и redirect_url на платёжную страницу PSP. Пользователь вводит карту не у нас, а на странице или в виджете провайдера. Номер карты не касается наших серверов, и большая часть требований PCI DSS ложится на провайдера, а не на нас.

Остальные методы:

  • GET /api/v1/payments/{id} — статус. Фронтенд опрашивает его после возврата с платёжной страницы.
  • POST /api/v1/payments/{id}/refunds — возврат, тоже с Idempotency-Key и суммой.
  • POST /webhooks/psp — сюда провайдер присылает события.

Платёж, попытка и машина состояний

Разделите две сущности:

  • Payment — намерение: «заказ 777 нужно оплатить на 1499.90 ₽».
  • Payment attempt — одна попытка провести его через PSP. Карта отклонена, пользователь ввёл другую — это вторая попытка того же платежа. attempt_id мы передаём провайдеру как его ключ идемпотентности и как ссылку для сверки.

У каждого платежа есть статус, и меняется он только по разрешённым переходам:

created --> pending --> authorized --> captured --> partially_refunded --> refunded | | | v v +----------------------------> refunded failed voided ^ | unknown (таймаут: ждём вебхук или опрашиваем PSP)

authorized — банк заморозил деньги на карте, captured — списал. Двухшаговая схема нужна, когда товар могут не отгрузить: заморозку можно отменить (voided) без возврата. Для цифровых товаров часто делают авторизацию и списание сразу.

Машина состояний защищает от запоздавших и повторных событий:

ALLOWED = { "created": {"pending", "failed"}, "pending": {"authorized", "captured", "failed", "unknown"}, "unknown": {"authorized", "captured", "failed"}, "authorized": {"captured", "voided"}, "captured": {"refunded", "partially_refunded"}, "partially_refunded": {"refunded", "partially_refunded"}, } def transition(payment: dict, new_status: str) -> bool: """Возвращает False, если событие устарело или пришло повторно.""" current = payment["status"] if new_status == current and new_status != "partially_refunded": return False # дубль if new_status not in ALLOWED.get(current, set()): return False # запоздавшее событие: authorized после captured и т. п. payment["status"] = new_status return True p = {"id": "pay_1", "status": "created"} for event in ["pending", "unknown", "captured", "authorized", "captured", "refunded"]: print(f"{event:11} -> {transition(p, event)!s:5} status={p['status']}") # pending -> True status=pending # unknown -> True status=unknown # captured -> True status=captured # authorized -> False status=captured # captured -> False status=captured # refunded -> True status=refunded

В базе это один атомарный запрос: UPDATE payments SET status = 'captured' WHERE id = $1 AND status IN ('pending', 'unknown', 'authorized'). Обновилась ноль строк — событие устарело или уже обработано, и это не ошибка. Повторные частичные возвраты различаются не статусом, а id операции возврата, о нём ниже.

Шаг 5. Архитектура

клиент --> API платежей --> БД платежей: payments, attempts, outbox | | | redirect v v очередь событий --> заказы, уведомления, аналитика страница PSP | | v v сервис ledger --> БД ledger: проводки, балансы PSP ^ | | +--> приёмник вебхуков (подпись, дедупликация, сырые события) ^ планировщик: опрос зависших unknown, выплаты продавцам | сверка: отчёт PSP + выписка банка <--> ledger --> расхождения на разбор

API платежей принимает запрос, проверяет ключ идемпотентности, создаёт payment и attempt, вызывает PSP и возвращает ссылку на оплату. Он владеет статусами.

Адаптер PSP — единственное место, которое знает формат конкретного провайдера. Остальная система видит общие операции: authorize, capture, refund, get_status. Так второй провайдер добавляется без переписывания бизнес-логики.

Приёмник вебхуков проверяет подпись, сохраняет сырое событие и сразу отвечает 200. Обработка асинхронная.

Сервис ledger — двойная запись, единственный источник правды о деньгах. Его не вызывают напрямую из API: он получает события из очереди и пишет проводки идемпотентно.

Сверка раз в день сравнивает наши данные с отчётами провайдера и банка.

Статус платежа и событие «платёж списан» нужно записать атомарно. Если обновить базу, а публикация в брокер упадёт, ledger никогда не узнает о деньгах. Поэтому событие пишется в таблицу outbox в той же транзакции, что и статус, а отдельный релей переносит его в очередь. Подробно паттерн разобран в статье про transactional outbox.

Шаг 6. Double-entry ledger

Наивная модель — колонка balance у продавца и UPDATE balance = balance + 950. Она ломается сразу: нельзя объяснить, откуда взялся баланс, нельзя найти ошибку, а повтор события молча удвоит сумму.

Двойная запись — способ, которым бухгалтерия работает пятьсот лет. Идея:

  • Есть счета: деньги, которые нам должен PSP; деньги, которые мы должны продавцу; наша выручка; комиссии провайдера; деньги на банковском счёте.
  • Любая операция — транзакция из двух и более проводок. Каждая проводка — сумма на одном счёте, дебет со знаком плюс, кредит со знаком минус.
  • Сумма проводок в транзакции всегда равна нулю. Деньги не создаются и не исчезают, а только перемещаются между счетами.
  • Проводки неизменяемы. Ошибку исправляют новой, обратной транзакцией, а не UPDATE.
  • Баланс счёта — это сумма его проводок. Его можно кэшировать, но всегда можно пересчитать.

Пример: платёж, перечисление от PSP, возврат

Покупатель заплатил 1000 ₽, наша комиссия 5%, комиссия провайдера 2%:

ТранзакцияСчётДебет (+)Кредит (−)
Платёж списанpsp_receivable1000.00
merchant_42_payable950.00
platform_revenue50.00
PSP перечислил деньги на счётbank_cash980.00
psp_fees20.00
psp_receivable1000.00
Частичный возврат 300 ₽merchant_42_payable285.00
platform_revenue15.00
psp_receivable300.00

После возврата psp_receivable уходит в минус: провайдер вернул деньги покупателю и удержит 300 ₽ из следующего перечисления. Ledger это честно показывает. Продавец должен получить 665 ₽, а не 950.

Минимальная реализация:

from collections import defaultdict from dataclasses import dataclass from decimal import Decimal @dataclass(frozen=True) class Entry: account: str amount: int # минимальные единицы; дебет > 0, кредит < 0 class Ledger: def __init__(self): self.transactions = {} # tx_id -> список проводок self.balances = defaultdict(int) def post(self, tx_id: str, entries: list[Entry]) -> bool: if tx_id in self.transactions: # повтор той же операции return False if len(entries) < 2: raise ValueError("в транзакции минимум две проводки") if sum(e.amount for e in entries) != 0: raise ValueError("дебет не равен кредиту") self.transactions[tx_id] = entries for e in entries: self.balances[e.account] += e.amount return True def check(self) -> bool: return sum(self.balances.values()) == 0 ledger = Ledger() ledger.post("pay_1:captured", [ Entry("psp_receivable", 100000), # PSP должен нам деньги Entry("merchant_42_payable", -95000), # мы должны продавцу Entry("platform_revenue", -5000), # наша комиссия 5% ]) print(ledger.post("pay_1:captured", [])) # False: вебхук пришёл второй раз ledger.post("settlement_2026_11_07", [ Entry("bank_cash", 98000), Entry("psp_fees", 2000), Entry("psp_receivable", -100000), ]) ledger.post("refund_7", [ Entry("merchant_42_payable", 28500), Entry("platform_revenue", 1500), Entry("psp_receivable", -30000), ]) for account, balance in sorted(ledger.balances.items()): print(f"{account:22} {Decimal(balance).scaleb(-2):>10}") print("сумма всех счетов = 0:", ledger.check())

bank_cash 980.00

merchant_42_payable -665.00

platform_revenue -35.00

psp_fees 20.00

psp_receivable -300.00

сумма всех счетов = 0: True


Ключевая деталь — `tx_id`. Это не случайный UUID, а детерминированный идентификатор бизнес-события: `pay_1:captured`, `refund_7`. Сколько бы раз событие ни пришло, проводки появятся один раз.

### Схема в базе

```sql
CREATE TABLE accounts (
  id        TEXT PRIMARY KEY,           -- 'merchant_42_payable'
  type      TEXT NOT NULL,              -- asset | liability | revenue | expense
  currency  TEXT NOT NULL
);

CREATE TABLE ledger_transactions (
  id          TEXT PRIMARY KEY,         -- 'pay_1:captured' — ключ идемпотентности
  kind        TEXT NOT NULL,            -- capture | refund | settlement | payout
  created_at  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE ledger_entries (
  id              INTEGER PRIMARY KEY,
  transaction_id  TEXT    NOT NULL REFERENCES ledger_transactions(id),
  account_id      TEXT    NOT NULL REFERENCES accounts(id),
  amount          BIGINT  NOT NULL CHECK (amount <> 0),  -- дебет > 0, кредит < 0
  currency        TEXT    NOT NULL
);

-- Проверка, которую гоняют по расписанию: каждая транзакция сбалансирована
SELECT transaction_id, currency, SUM(amount) AS diff
FROM ledger_entries
GROUP BY transaction_id, currency
HAVING SUM(amount) <> 0;

Транзакция и все её проводки вставляются в одной транзакции базы. Повтор упирается в первичный ключ ledger_transactions.id. Баланс проверяется дважды: в коде до вставки и запросом по расписанию после. Право на UPDATE и DELETE для ledger_entries у сервиса лучше вообще отобрать.

Баланс продавца для выплаты читается из материализованной таблицы account_balances, которая обновляется в той же транзакции, что и проводки. Чтобы не выплатить больше, чем есть, строку баланса блокируют (SELECT ... FOR UPDATE) или обновляют с условием WHERE balance >= $amount.

Шаг 7. Идемпотентность на каждой границе

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

ГраницаОткуда повторЧем защищаемся
Клиент → APIдвойной клик, ретрай SDK после таймаутаIdempotency-Key с уникальным индексом и сохранённым ответом
API → PSPнаш ретрай после таймаутаattempt_id как ключ идемпотентности провайдера
PSP → вебхукпровайдер шлёт, пока не получит 2xxуникальный индекс по id события провайдера
Очередь → ledgerat-least-once доставка, перезапуск потребителядетерминированный tx_id транзакции ledger
Статус платежавебхук и опрос пришли одновременноусловный UPDATE ... WHERE status IN (...)

Как устроить ключ на входе, что делать с параллельными повторами и почему повтор с другим телом должен получить 422, подробно разобрано в статье про идемпотентность API. Здесь важна мысль уровня архитектуры: одного ключа на входе недостаточно. Если сервис сам ретраит вызов PSP с новым ключом, защита клиента ничего не стоит.

Шаг 8. Взаимодействие с PSP

У вызова внешнего провайдера три исхода, и путать их нельзя:

  1. Определённый успех. PSP ответил, что деньги списаны или заморожены.
  2. Определённый отказ. Недостаточно средств, карта заблокирована, банк отклонил. Повторять бессмысленно, а иногда и вредно: банки не любят серии одинаковых запросов.
  3. Неизвестно. Таймаут, обрыв соединения, 502. Деньги могли списаться, а могли и нет.

Главная ошибка на интервью и в проде — считать третий случай отказом. Пользователь видит «оплата не прошла», платит второй раз, а через час приходит вебхук о первом списании. Правильно: статус unknown, ретрай с тем же ключом, а если не помогло — выяснение по вебхуку или опросу get_status.

import random import time class PSPTimeout(Exception): ... class PSPDeclined(Exception): ... class PSPUnavailable(Exception): ... # 5xx, 429, обрыв до отправки def charge_with_retries(psp, attempt_id: str, amount: int, currency: str, max_tries: int = 4, base: float = 0.2) -> str: """Ключ идемпотентности для PSP — id попытки, он одинаков во всех ретраях.""" for n in range(max_tries): try: return psp.charge(idempotency_key=attempt_id, amount=amount, currency=currency) except PSPDeclined: return "failed" # отказ банка — окончательный ответ, не ретраим except (PSPTimeout, PSPUnavailable): if n == max_tries - 1: return "unknown" # не failed: деньги могли списаться time.sleep(random.uniform(0, base * 2 ** n)) # full jitter return "unknown" class FlakyPSP: """Имитация: первый запрос списал деньги, но ответ потерялся.""" def __init__(self): self.charges = {} self.calls = 0 def charge(self, idempotency_key, amount, currency): self.calls += 1 if idempotency_key not in self.charges: self.charges[idempotency_key] = (amount, currency) raise PSPTimeout() return "captured" psp = FlakyPSP() print(charge_with_retries(psp, "att_1", 100000, "RUB", base=0.01)) # captured print("вызовов:", psp.calls, "списаний:", len(psp.charges)) # вызовов: 2 списаний: 1

Ещё несколько правил работы с провайдером:

  • Короткие таймауты и circuit breaker. Если PSP лежит, лучше быстро вернуть пользователю «попробуйте через минуту», чем держать тысячи потоков в ожидании.
  • Не всё делать синхронно. С 3-D Secure пользователь уходит на страницу банка. Наш API возвращает redirect_url, а итог узнаём по вебхуку и по запросу статуса при возврате пользователя.
  • Записать попытку до вызова. attempt со статусом pending сохраняется в базу до запроса к PSP. Если сервис упадёт в момент вызова, останется след, по которому планировщик потом спросит провайдера.
  • Не ретраить бесконечно. Если статус всё ещё unknown через несколько часов, это задача для сверки и человека, а не для очередного ретрая.

Шаг 9. Вебхуки

Вебхук — HTTP-запрос от провайдера на наш адрес: «платёж att_1 списан». У вебхуков четыре неприятных свойства: их может прислать кто угодно, они приходят повторно, они приходят не по порядку, и они иногда не приходят совсем.

Подпись. Провайдер подписывает тело запроса общим секретом через HMAC, обычно вместе с меткой времени. Похожую схему использует, например, Stripe: в заголовке передаются время и HMAC-SHA256 от строки «время.тело». Проверка выглядит так:

import hashlib import hmac import time SECRET = b"whsec_test" TOLERANCE = 300 # секунд def sign(payload: bytes, ts: int) -> str: mac = hmac.new(SECRET, f"{ts}.".encode() + payload, hashlib.sha256) return mac.hexdigest() def verify(payload: bytes, ts: int, signature: str, now: int | None = None) -> bool: now = int(time.time()) if now is None else now if abs(now - ts) > TOLERANCE: return False # защита от повторной отправки старого запроса expected = sign(payload, ts) return hmac.compare_digest(expected, signature) # сравнение за постоянное время body = b'{"id":"evt_9","type":"payment.captured","payment":"att_1"}' ts = int(time.time()) sig = sign(body, ts) print(verify(body, ts, sig)) # True print(verify(body.replace(b"att_1", b"att_2"), ts, sig)) # False: тело подменили print(verify(body, ts - 3600, sign(body, ts - 3600))) # False: слишком старый

Подпись считается от сырых байтов тела. Если сначала распарсить JSON и сериализовать обратно, порядок ключей или пробелы изменятся, и подпись не сойдётся.

Быстрый ответ. Приёмник проверяет подпись, сохраняет событие в таблицу psp_events с уникальным индексом по id события и отвечает 200. Вся бизнес-логика — потом, в фоновом обработчике. Если обработка займёт 30 секунд, провайдер решит, что вебхук не дошёл, и пришлёт его снова.

Дубли. Вставка с тем же id события упирается в уникальный индекс — значит, уже получали, отвечаем 200 и ничего не делаем. Отвечать ошибкой на дубль нельзя: провайдер продолжит ретраить.

Порядок. payment.refunded может прийти раньше payment.captured. Машина состояний из шага 4 не даст статусу откатиться назад. Для надёжности обработчик может не доверять содержимому события, а по его id запросить у PSP актуальный статус платежа: так вебхук становится сигналом «что-то изменилось», а не источником правды.

Пропажа. Вебхук может не прийти вовсе: у нас был деплой, провайдер исчерпал ретраи. Поэтому планировщик раз в несколько минут опрашивает PSP по всем платежам, которые слишком долго висят в pending или unknown.

Шаг 10. Ретраи и долгие процессы

Ретраи в платёжной системе живут на трёх уровнях:

  1. Внутри запроса — 2–3 быстрых повтора вызова PSP с экспоненциальной задержкой и jitter, как в коде выше. Только для временных ошибок и только с тем же ключом.
  2. Фоновые — планировщик подбирает зависшие unknown и pending, опрашивает статус, публикует события через outbox. Потребители очередей при ошибке откладывают сообщение и после N попыток отправляют его в DLQ.
  3. Человеческие — то, что не разрешилось автоматически, попадает в очередь на ручной разбор вместе с отчётом сверки.

Платёж редко живёт сам по себе. Заказ, резерв товара, списание и уведомление продавца — это несколько сервисов со своими базами. Распределённую транзакцию между ними не делают. Используют сагу: последовательность локальных шагов, где у каждого есть компенсация. Не удалось зарезервировать товар после списания — компенсация делает возврат. Важно, что компенсация в мире денег — это не удаление записи, а новая операция: возврат порождает новые проводки в ledger. Как выбирать между хореографией и оркестрацией, разобрано в статье про паттерн Saga.

Шаг 11. Сверка (reconciliation)

Даже с идеальным кодом данные расходятся: вебхук потерялся, провайдер списал комиссию по другому тарифу, банк вернул платёж по спору (chargeback), инженер руками поправил статус. Сверка — это страховка, которая не зависит от того, правильно ли работает остальная система.

Раз в сутки PSP выдаёт отчёт о расчётах (settlement report): какие операции прошли, на какие суммы, какие комиссии удержаны, сколько перечислено. Банк выдаёт выписку по счёту. Сверка сопоставляет три источника:

наши платежи и ledger <--> отчёт PSP <--> выписка банка что мы думаем что PSP провёл что реально пришло на счёт

Сопоставление идёт по ключу, который мы передали провайдеру, — attempt_id. Это обычный join по хеш-таблице:

def reconcile(ours: list[dict], theirs: list[dict]) -> dict: """Сверка за день: наши captured-платежи против отчёта PSP. Ключ сопоставления — id попытки, который мы передали PSP.""" by_ref = {p["ref"]: p for p in ours} report = {"matched": 0, "missing_in_ours": [], "missing_in_psp": [], "mismatch": []} for row in theirs: p = by_ref.pop(row["ref"], None) if p is None: report["missing_in_ours"].append(row["ref"]) # PSP списал, мы не знаем elif (p["amount"], p["currency"]) != (row["amount"], row["currency"]): report["mismatch"].append((row["ref"], p["amount"], row["amount"])) else: report["matched"] += 1 report["missing_in_psp"] = list(by_ref) # у нас captured, у PSP нет return report ours = [ {"ref": "att_1", "amount": 100000, "currency": "RUB"}, {"ref": "att_2", "amount": 49900, "currency": "RUB"}, {"ref": "att_3", "amount": 15000, "currency": "RUB"}, ] theirs = [ {"ref": "att_1", "amount": 100000, "currency": "RUB"}, {"ref": "att_2", "amount": 4990, "currency": "RUB"}, {"ref": "att_4", "amount": 250000, "currency": "RUB"}, # тот самый «unknown» ] for key, value in reconcile(ours, theirs).items(): print(f"{key:16} {value}") # matched 1 # missing_in_ours ['att_4'] # missing_in_psp ['att_3'] # mismatch [('att_2', 49900, 4990)]

Что делать с каждым видом расхождения:

РасхождениеТипичная причинаДействие
Есть у PSP, нет у наспотерянный вебхук, платёж застрял в unknownавтоматически дотянуть статус и создать проводки
Есть у нас, нет у PSPоперация попадёт в отчёт завтра, или наш багподождать один цикл, потом на ручной разбор
Разные суммыошибка конвертации, частичное списание, багручной разбор, исправление обратной транзакцией
Разные комиссиитариф провайдера изменилсяпроводка на разницу в psp_fees, уведомить финансы
Перечисление не пришлозадержка банка, удержание провайдеромалерт финансовой команде

Сверка не исправляет ledger задним числом. Каждое исправление — новая транзакция с понятной причиной, чтобы аудитор через год мог восстановить историю.

Узкие места и вопросы вглубь

Горячие счета. На счёт platform_revenue пишет каждый платёж. При тысяче транзакций в секунду блокировка одной строки баланса становится узким местом. Варианты: разбить счёт на N подсчетов и писать в случайный, а баланс считать суммой; обновлять агрегированный баланс асинхронно, если он не нужен для проверок «хватает ли денег». Для счетов продавцов, с которых делаются выплаты, баланс нужен точный.

Шардирование ledger. Шардируют по счёту, но транзакция затрагивает несколько счетов. Чтобы она осталась локальной, счета одного продавца держат в одном шарде, а общие счета платформы дробят на подсчета по шардам.

Мультивалютность. Проводки одной транзакции балансируются в каждой валюте отдельно. Конвертация — это две транзакции через счёт обмена с зафиксированным курсом.

Безопасность. Номеров карт у нас нет: только токены провайдера. Доступ к ledger — по принципу минимальных прав, все изменения в журнал аудита, секреты вебхуков в хранилище секретов с ротацией.

Что если упала основная база? Синхронная реплика в другой зоне доступности: для денег асинхронная репликация с потерей последних секунд неприемлема. Платим задержкой записи.

Как переключиться на второго PSP? Адаптер за общим интерфейсом, маршрутизация по правилам (валюта, тип карты, доступность провайдера), отдельный отчёт сверки на каждого.

Типичные ошибки

  • Хранить суммы во float или передавать их в JSON числом с плавающей точкой.
  • Считать таймаут отказом. Пользователь платит второй раз, первый платёж находится через час.
  • Генерировать новый ключ идемпотентности на каждый ретрай к провайдеру.
  • Хранить только колонку balance без истории операций. Ошибку невозможно найти, дубль невозможно заметить.
  • Править или удалять проводки. Исправление — только новая обратная транзакция.
  • Делать бизнес-логику прямо в обработчике вебхука и отвечать провайдеру после неё.
  • Проверять подпись после парсинга JSON, а не по сырому телу.
  • Обновлять статус и публиковать событие без outbox. Однажды одно из двух не случится.
  • Обходиться без сверки, потому что «код же правильный».

Как рассказывать на собеседовании

Примерный план на 45 минут:

  1. 5 минут — требования. Маркетплейс, PSP обрабатывает карты, возвраты и выплаты нужны. Сразу скажите главное нефункциональное: ни двойных списаний, ни потерь, строгая согласованность денег.
  2. 3 минуты — оценка. Нагрузка скромная, узкое место — внешний провайдер и корректность, а не QPS.
  3. 7 минут — API и модель. Idempotency-Key, суммы строкой и в минимальных единицах, payment и attempt, машина состояний.
  4. 10 минут — архитектура. API, адаптер PSP, приёмник вебхуков, outbox, ledger, планировщик, сверка.
  5. 15 минут — вглубь. Double-entry ledger с примером проводок, идемпотентность на каждой границе, три исхода вызова PSP, вебхуки, сверка.
  6. 5 минут — узкие места. Горячие счета, шардирование, отказ базы, второй провайдер.

Фраза, которая хорошо работает: «Я исхожу из того, что любой вызов может повториться и любой ответ может потеряться. Поэтому на каждой границе есть ключ идемпотентности, а поверх всего — ежедневная сверка, которая не доверяет нашему же коду». После неё интервьюер обычно переходит к вопросам вглубь, а не к проверке основ.

Потренироваться в спокойной обстановке

Все задачи