Системный дизайн платёжной системы: ledger, идемпотентность, PSP, вебхуки и сверка
Как спроектировать платёжную систему на system design интервью: требования, деньги в целых копейках, double-entry ledger, идемпотентность, работа с PSP, вебхуки, ретраи и сверка.
Коротко
| Вопрос | Решение в этом разборе |
|---|---|
| Нагрузка | 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 млн × 4 | 40 млн |
| Объём ledger в сутки | 40 млн × 200 байт | 8 ГБ |
| Объём за год | 8 ГБ × 365 | около 3 ТБ без реплик |
Выводы:
- По QPS это маленькая система. Один хорошо настроенный Postgres с репликами справится. Шардирование нужно не сразу, и то в основном из-за горячих счетов (о них ниже).
- Медленное звено — PSP. Ответ провайдера идёт сотни миллисекунд, а с 3-D Secure — десятки секунд, потому что пользователь вводит код. Синхронно ждать это в потоке запроса нельзя.
- Объём 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_receivable | 1000.00 | |
| merchant_42_payable | 950.00 | ||
| platform_revenue | 50.00 | ||
| PSP перечислил деньги на счёт | bank_cash | 980.00 | |
| psp_fees | 20.00 | ||
| psp_receivable | 1000.00 | ||
| Частичный возврат 300 ₽ | merchant_42_payable | 285.00 | |
| platform_revenue | 15.00 | ||
| psp_receivable | 300.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 события провайдера |
| Очередь → ledger | at-least-once доставка, перезапуск потребителя | детерминированный tx_id транзакции ledger |
| Статус платежа | вебхук и опрос пришли одновременно | условный UPDATE ... WHERE status IN (...) |
Как устроить ключ на входе, что делать с параллельными повторами и почему повтор с другим телом должен получить 422, подробно разобрано в статье про идемпотентность API. Здесь важна мысль уровня архитектуры: одного ключа на входе недостаточно. Если сервис сам ретраит вызов PSP с новым ключом, защита клиента ничего не стоит.
Шаг 8. Взаимодействие с PSP
У вызова внешнего провайдера три исхода, и путать их нельзя:
- Определённый успех. PSP ответил, что деньги списаны или заморожены.
- Определённый отказ. Недостаточно средств, карта заблокирована, банк отклонил. Повторять бессмысленно, а иногда и вредно: банки не любят серии одинаковых запросов.
- Неизвестно. Таймаут, обрыв соединения,
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. Ретраи и долгие процессы
Ретраи в платёжной системе живут на трёх уровнях:
- Внутри запроса — 2–3 быстрых повтора вызова PSP с экспоненциальной задержкой и jitter, как в коде выше. Только для временных ошибок и только с тем же ключом.
- Фоновые — планировщик подбирает зависшие
unknownиpending, опрашивает статус, публикует события через outbox. Потребители очередей при ошибке откладывают сообщение и после N попыток отправляют его в DLQ. - Человеческие — то, что не разрешилось автоматически, попадает в очередь на ручной разбор вместе с отчётом сверки.
Платёж редко живёт сам по себе. Заказ, резерв товара, списание и уведомление продавца — это несколько сервисов со своими базами. Распределённую транзакцию между ними не делают. Используют сагу: последовательность локальных шагов, где у каждого есть компенсация. Не удалось зарезервировать товар после списания — компенсация делает возврат. Важно, что компенсация в мире денег — это не удаление записи, а новая операция: возврат порождает новые проводки в 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 минут:
- 5 минут — требования. Маркетплейс, PSP обрабатывает карты, возвраты и выплаты нужны. Сразу скажите главное нефункциональное: ни двойных списаний, ни потерь, строгая согласованность денег.
- 3 минуты — оценка. Нагрузка скромная, узкое место — внешний провайдер и корректность, а не QPS.
- 7 минут — API и модель.
Idempotency-Key, суммы строкой и в минимальных единицах, payment и attempt, машина состояний. - 10 минут — архитектура. API, адаптер PSP, приёмник вебхуков, outbox, ledger, планировщик, сверка.
- 15 минут — вглубь. Double-entry ledger с примером проводок, идемпотентность на каждой границе, три исхода вызова PSP, вебхуки, сверка.
- 5 минут — узкие места. Горячие счета, шардирование, отказ базы, второй провайдер.
Фраза, которая хорошо работает: «Я исхожу из того, что любой вызов может повториться и любой ответ может потеряться. Поэтому на каждой границе есть ключ идемпотентности, а поверх всего — ежедневная сверка, которая не доверяет нашему же коду». После неё интервьюер обычно переходит к вопросам вглубь, а не к проверке основ.