Все заметки
Финтех

В реестре есть, в базе нет: ежедневная сверка платежей с провайдером и банковской выпиской

Провайдер перевёл деньги, а сумма не сходится с базой — какой платёж виноват? Ежедневная сверка на Django и PostgreSQL: типы расхождений, автозакрытие, ledger и алерты.

Утро понедельника, сообщение от финансового отдела: «Провайдер перевёл деньги за пятничные платежи, но сумма меньше, чем в отчёте из админки. Где разница?» Вы смотрите в базу: сумма success-платежей за пятницу — одно число, поступление в банковской выписке — другое. Вычитаете комиссию — всё равно не сходится. Теперь нужно найти одну-две транзакции среди тысяч, и делать это придётся руками, в Excel.

Или обратная ситуация: клиент пишет в поддержку — «с карты списали, баланс не пополнился». В базе платёж до сих пор pending: callback от провайдера так и не пришёл. Не напиши клиент — никто бы об этом не узнал.

В обоих случаях проблема одна: система верит своей базе, а правда — где на самом деле деньги — записана в другом месте. Сверка (reconciliation) — это процесс регулярного, автоматического и объяснимого сравнения этих источников. В этой статье соберём её с нуля на Django и PostgreSQL: импорт реестра, поиск расхождений через SQL, автоматическое и ручное закрытие, связь с ledger, отчёты и алерты.

Откуда берутся расхождения

Как бы аккуратно ни была написана интеграция, данные в базе и у провайдера время от времени расходятся. Типичные причины:

  • Потерянный callback. Провайдер провёл платёж, но webhook не дошёл или вернул ошибку, и повторные попытки закончились. У нас pending, у них success.
  • Таймаут. Вы отправили запрос провайдеру, не дождались ответа и пометили платёж как failed. А провайдер операцию довёл до конца.
  • Поздняя отмена. Операцию отменили на стороне провайдера (reversal, chargeback, вручную через поддержку), а уведомление до вас не дошло.
  • Граница дня. Вы считаете день по UTC, провайдер — по ташкентскому времени, банк — по своему операционному дню (cut-off). Платёж в 23:59:58 попадает в два разных дня.
  • Единицы суммы. Один API отдаёт сумму в тийинах, другой — в сумах с дробной частью. Одно округление — и расхождение по сумме готово.
  • Комиссия. В банк приходит не валовая сумма, а чистая — после удержания комиссии.
  • Обычный баг. Дубликат, неправильный переход статуса, «осиротевшие» строки после миграции.

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

Почему наивный подход не работает

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

Вторая ошибка — пройтись по реестру циклом в Python и для каждой строки вызвать Payment.objects.get(...). На малых объёмах работает, но каждая строка — отдельный query, и главное, такой подход вообще не видит случай «у нас есть, у них нет»: вы проверяете только то, что есть в реестре.

Третья и самая опасная — при найденном расхождении автоматически сделать UPDATE базы под данные провайдера. Это стирает историю, обходит state machine и ledger. А если ошибка на стороне провайдера, вы просто перенесли её к себе.

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

Три источника, два уровня

В финтехе обычно три источника:

  1. Наша база — таблица Payment и ledger.
  2. Реестр провайдера — ежедневный файл (CSV, XLSX или через API). В нём по каждой транзакции: ID провайдера, сумма, комиссия, статус, время. Точный формат зависит от провайдера, поэтому берите его из документации и нормализуйте на этапе импорта.
  3. Банковская выписка — сколько денег реально пришло на счёт. Обычно это один сводный перевод (settlement): чистая сумма за день.

Соответственно, и сверка идёт на двух уровнях:

  • Уровень транзакций: база ↔ реестр. Каждый платёж должен совпасть по отдельности. Отвечает на вопрос «какой именно платёж?».
  • Уровень денег: реестр ↔ банковская выписка. Чистая сумма по реестру должна равняться поступлению в банк. Отвечает на вопрос «деньги действительно пришли?».

Модели

На нашей стороне считаем, что модель Payment уже есть: поля provider, provider_txn_id, amount_tiyin, status, performed_at и unique-ограничение на пару (provider, provider_txn_id). Суммы хранятся целым числом в тийинах — никаких float.

Для сверки нужны четыре модели:

# recon/models.py
from django.conf import settings
from django.db import models
from django.db.models import Q


class StatementBatch(models.Model):
    provider = models.CharField(max_length=32)
    statement_date = models.DateField()
    file_sha256 = models.CharField(max_length=64, unique=True)
    line_count = models.PositiveIntegerField()
    total_tiyin = models.BigIntegerField()
    imported_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [models.Index(fields=["provider", "statement_date"])]


class StatementLine(models.Model):
    batch = models.ForeignKey(StatementBatch, on_delete=models.PROTECT, related_name="lines")
    external_id = models.CharField(max_length=64)
    status = models.CharField(max_length=16)  # normalised: success / cancelled
    amount_tiyin = models.BigIntegerField()
    fee_tiyin = models.BigIntegerField(default=0)
    performed_at = models.DateTimeField()
    raw = models.JSONField()  # the original row, exactly as the provider sent it

    class Meta:
        constraints = [
            models.UniqueConstraint(fields=["batch", "external_id"], name="uniq_line_per_batch"),
        ]
        indexes = [models.Index(fields=["external_id"])]


class ReconciliationRun(models.Model):
    provider = models.CharField(max_length=32)
    batch = models.ForeignKey(StatementBatch, on_delete=models.PROTECT)
    started_at = models.DateTimeField(auto_now_add=True)
    finished_at = models.DateTimeField(null=True)
    stats = models.JSONField(default=dict)


class Discrepancy(models.Model):
    class Kind(models.TextChoices):
        MISSING_OURS = "missing_ours"      # they have it, we don't
        MISSING_THEIRS = "missing_theirs"  # we have it, they don't
        AMOUNT = "amount"
        STATUS = "status"

    class State(models.TextChoices):
        OPEN = "open"
        AUTO_RESOLVED = "auto_resolved"
        RESOLVED = "resolved"

    run = models.ForeignKey(ReconciliationRun, on_delete=models.PROTECT, related_name="discrepancies")
    kind = models.CharField(max_length=16, choices=Kind.choices)
    state = models.CharField(max_length=16, choices=State.choices, default=State.OPEN)
    payment = models.ForeignKey("payments.Payment", null=True, on_delete=models.PROTECT)
    line = models.ForeignKey(StatementLine, null=True, on_delete=models.PROTECT)
    our_amount_tiyin = models.BigIntegerField(null=True)
    their_amount_tiyin = models.BigIntegerField(null=True)
    note = models.TextField(blank=True)
    resolved_by = models.ForeignKey(
        settings.AUTH_USER_MODEL, null=True, blank=True, on_delete=models.PROTECT
    )
    resolved_at = models.DateTimeField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=["kind", "payment", "line"],
                condition=Q(state="open"),
                nulls_distinct=False,
                name="uniq_open_discrepancy",
            ),
        ]

Несколько важных решений:

  • file_sha256 уникален — один и тот же файл не импортируется дважды.
  • raw — исходная строка реестра. Когда возникнет спор «что именно прислал провайдер?», ответ будет здесь.
  • Частичное unique-ограничение в Discrepancy не даёт создать одно и то же открытое расхождение дважды, поэтому сверку можно перезапускать сколько угодно. nulls_distinct=False (Django 5.0+, PostgreSQL 15+) обязателен: одно из полей payment или line часто NULL, а по умолчанию PostgreSQL считает два NULL разными значениями, и ограничение перестаёт работать.

Импорт реестра

# recon/importer.py
import csv
import hashlib
import io
from datetime import date, datetime
from decimal import Decimal
from zoneinfo import ZoneInfo

from django.db import transaction

from .models import StatementBatch, StatementLine

PROVIDER_TZ = ZoneInfo("Asia/Tashkent")
# Map provider statuses to our vocabulary. An unknown status raises KeyError on purpose.
STATUS_MAP = {"SUCCESS": "success", "CANCELLED": "cancelled"}


def to_tiyin(value: str) -> int:
    cleaned = value.strip().replace(" ", "").replace(" ", "").replace(",", ".")
    tiyin = Decimal(cleaned) * 100
    if tiyin != tiyin.to_integral_value():
        raise ValueError(f"fraction of a tiyin: {value!r}")
    return int(tiyin)


def import_statement(provider: str, statement_date: date, content: bytes) -> StatementBatch:
    digest = hashlib.sha256(content).hexdigest()
    if existing := StatementBatch.objects.filter(file_sha256=digest).first():
        return existing  # same file again: nothing to do

    reader = csv.DictReader(io.StringIO(content.decode("utf-8-sig")), delimiter=";")
    lines: list[StatementLine] = []
    for row in reader:
        lines.append(
            StatementLine(
                external_id=row["transaction_id"].strip(),
                status=STATUS_MAP[row["status"].strip().upper()],
                amount_tiyin=to_tiyin(row["amount"]),
                fee_tiyin=to_tiyin(row.get("fee") or "0"),
                performed_at=datetime.strptime(
                    row["performed_at"], "%Y-%m-%d %H:%M:%S"
                ).replace(tzinfo=PROVIDER_TZ),
                raw=row,
            )
        )

    with transaction.atomic():
        batch = StatementBatch.objects.create(
            provider=provider,
            statement_date=statement_date,
            file_sha256=digest,
            line_count=len(lines),
            total_tiyin=sum(line.amount_tiyin for line in lines),
        )
        for line in lines:
            line.batch = batch
        StatementLine.objects.bulk_create(lines, batch_size=2000)
    return batch

Импорт намеренно «строгий»: неизвестный статус или доли тийина роняют его с KeyError или ValueError. Лучше упавший импорт и уведомлённый человек, чем реестр, импортированный «примерно». Batch и его строки пишутся в одной транзакции — полуимпортированного файла не бывает.

Если провайдер кладёт в конец файла контрольные итоги (число строк и общую сумму), сравните их с line_count и total_tiyin. Так вы проверите, что сам файл дошёл целиком.

Поиск расхождений на SQL

Основная работа — в двух запросах. Первый идёт со стороны реестра: есть ли у нас платёж для каждой строки реестра, совпадают ли сумма и статус.

-- THEIR_SIDE_SQL: every statement line vs. our payments
SELECT l.id, l.amount_tiyin, l.status,
       p.id, p.amount_tiyin, p.status
FROM recon_statementline AS l
LEFT JOIN payments_payment AS p
       ON p.provider = %(provider)s
      AND p.provider_txn_id = l.external_id
WHERE l.batch_id = %(batch_id)s
  AND (p.id IS NULL
       OR p.amount_tiyin <> l.amount_tiyin
       OR p.status <> l.status);

Второй — с нашей стороны: платёж у нас успешен, но его нет ни в одном реестре провайдера.

-- OUR_SIDE_SQL: successful payments of one day that appear in no statement at all
SELECT p.id, p.amount_tiyin
FROM payments_payment AS p
WHERE p.provider = %(provider)s
  AND p.status = 'success'
  AND p.performed_at >= %(start)s
  AND p.performed_at <  %(end)s
  AND NOT EXISTS (
        SELECT 1
        FROM recon_statementline AS l
        JOIN recon_statementbatch AS b ON b.id = l.batch_id
        WHERE b.provider = p.provider
          AND l.external_id = p.provider_txn_id
  );

Обратите внимание: второй запрос сравнивает не с одним batch, а со всеми реестрами провайдера. Платёж в 23:59:58 может попасть в завтрашний реестр, поэтому вывод «у них нет» делаем с задержкой (lag): когда приходит реестр за день D, нашу сторону проверяем за день D−2. Так платежи на границе дня не дают ложных срабатываний.

На стороне Python превращаем результат в записи Discrepancy:

# recon/matching.py
from datetime import date, datetime, time, timedelta
from zoneinfo import ZoneInfo

from django.db import connection
from django.utils import timezone

from .models import Discrepancy, ReconciliationRun, StatementBatch
from .sql import OUR_SIDE_SQL, THEIR_SIDE_SQL  # the two queries above

TASHKENT = ZoneInfo("Asia/Tashkent")
MISSING_THEIRS_LAG_DAYS = 2


def day_bounds(day: date) -> tuple[datetime, datetime]:
    start = datetime.combine(day, time.min, tzinfo=TASHKENT)
    return start, start + timedelta(days=1)


def run_reconciliation(batch: StatementBatch) -> ReconciliationRun:
    run = ReconciliationRun.objects.create(provider=batch.provider, batch=batch)
    found: list[Discrepancy] = []

    with connection.cursor() as cur:
        cur.execute(THEIR_SIDE_SQL, {"provider": batch.provider, "batch_id": batch.id})
        for line_id, their_amount, _their_status, payment_id, our_amount, _our_status in cur.fetchall():
            if payment_id is None:
                kind = Discrepancy.Kind.MISSING_OURS
            elif our_amount != their_amount:
                kind = Discrepancy.Kind.AMOUNT
            else:
                kind = Discrepancy.Kind.STATUS
            found.append(Discrepancy(
                run=run, kind=kind, line_id=line_id, payment_id=payment_id,
                our_amount_tiyin=our_amount, their_amount_tiyin=their_amount,
            ))

        start, end = day_bounds(batch.statement_date - timedelta(days=MISSING_THEIRS_LAG_DAYS))
        cur.execute(OUR_SIDE_SQL, {"provider": batch.provider, "start": start, "end": end})
        for payment_id, our_amount in cur.fetchall():
            found.append(Discrepancy(
                run=run, kind=Discrepancy.Kind.MISSING_THEIRS,
                payment_id=payment_id, our_amount_tiyin=our_amount,
            ))

    # ON CONFLICT DO NOTHING: an already open discrepancy is not created twice
    Discrepancy.objects.bulk_create(found, ignore_conflicts=True)
    run.finished_at = timezone.now()
    run.stats = {"lines": batch.line_count, "candidates": len(found)}
    run.save(update_fields=["finished_at", "stats"])
    return run

bulk_create(..., ignore_conflicts=True) в PostgreSQL превращается в ON CONFLICT DO NOTHING: уже открытое расхождение повторно не создаётся.

Обоим запросам нужны индексы: payments_payment (provider, provider_txn_id) (его даёт unique-ограничение), recon_statementline (external_id) и отдельный индекс для выборки по окну дня. План обязательно проверьте сами:

CREATE INDEX CONCURRENTLY IF NOT EXISTS payment_recon_day_idx
    ON payments_payment (provider, status, performed_at);

EXPLAIN (ANALYZE, BUFFERS)
SELECT p.id
FROM payments_payment AS p
WHERE p.provider = 'psp_a'
  AND p.status = 'success'
  AND p.performed_at >= '2026-11-18 00:00+05'
  AND p.performed_at <  '2026-11-19 00:00+05';

В Django-проекте добавляйте индекс миграцией (django.contrib.postgres.operations.AddIndexConcurrently), а не руками. Если в EXPLAIN видно Seq Scan по большой таблице, сверка будет замедляться с ростом объёма.

Четыре типа расхождений

Тип Смысл Типичная причина Автозакрытие
missing_ours У них есть, у нас нет Callback не пришёл вовсе, платёж не создан Нет — самый опасный случай
missing_theirs У нас success, у них нет Поддельный или ошибочно обработанный callback, баг Нет
amount Сумма отличается Единицы (сум/тийин), округление, частичный возврат Никогда
status Статус отличается Потерянный callback, таймаут, поздняя отмена Да, если подтвердил API провайдера

missing_ours особенно серьёзен: деньги с клиента списаны, а услуга не оказана или баланс не пополнен. missing_theirs — обратная ситуация: услуга оказана, а деньги не пришли. Оба требуют решения человека.

Автоматический и ручной разбор

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

# recon/resolve.py
from django.db import transaction
from django.utils import timezone

from payments.models import Payment

from .models import Discrepancy


def close(d: Discrepancy, state: str, note: str, user=None) -> None:
    d.state, d.note, d.resolved_by, d.resolved_at = state, note, user, timezone.now()
    d.save(update_fields=["state", "note", "resolved_by", "resolved_at"])


def try_auto_resolve(d: Discrepancy, client) -> bool:
    if d.kind != Discrepancy.Kind.STATUS:
        return False

    # Network call outside the transaction: no row lock is held while we wait.
    remote = client.get_status(d.payment.provider_txn_id)  # normalised: success / cancelled

    with transaction.atomic():
        payment = Payment.objects.select_for_update().get(pk=d.payment_id)
        if remote == payment.status:
            close(d, Discrepancy.State.AUTO_RESOLVED, f"statement outdated, provider API: {remote}")
            return True
        if payment.status == "pending" and remote == "success":
            payment.mark_success(source="reconciliation")  # the same transition the callback uses
            close(d, Discrepancy.State.AUTO_RESOLVED, "lost callback, confirmed via provider API")
            return True
    return False  # everything else goes to a human

Что здесь происходит:

  1. Автоматически рассматриваются только расхождения типа status.
  2. У API провайдера запрашивается текущий статус — это более свежие данные, чем реестр. Запрос вне транзакции: пока ждём сеть, блокировка на строке не держится.
  3. Если API подтверждает наш статус (например, в реестре success, потом отмена, и у нас тоже cancelled), расхождение просто связано со временем — закрываем.
  4. Если у нас pending, а в API success — это потерянный callback. Проводим платёж тем же переходом, что использует callback: внутри mark_success() проверка статуса, запись в ledger и остальные side-effect'ы. Никакого прямого UPDATE.
  5. Всё остальное, включая необычные переходы вроде failed → success, остаётся открытым и уходит человеку.

Для ручного разбора хватает Django admin: список открытых расхождений, фильтры по типу и возрасту, показ raw-строки и action «закрыть». Главное — у каждого закрытого расхождения должно быть записано, кто закрыл, когда и почему (note). Расхождение, закрытое без комментария, — открытый вопрос для аудита.

Связь с ledger

Сверка должна закрывать не только таблицу Payment, но и бухгалтерию. В double-entry ledger это удобно делать через один транзитный счёт (clearing account):

  • При успешном платеже: Дт receivable:<provider> (провайдер нам должен) / Кт баланс клиента или выручка.
  • Когда в выписке появился settlement: Дт bank:main (чистая сумма), Дт expense:psp_fees (комиссия) / Кт receivable:<provider> (валовая сумма).

Если всё верно, баланс receivable:<provider> равен сумме платежей, по которым ещё не было settlement. Это простой, но сильный инвариант для всей системы.

# recon/settlement.py
from django.db.models import Q, Sum

from ledger.services import post_entry  # postings: (account, amount), debit > 0, credit < 0

from .models import StatementBatch


def book_settlement(batch: StatementBatch, bank_amount_tiyin: int, bank_ref: str) -> int:
    agg = batch.lines.aggregate(
        gross=Sum("amount_tiyin", filter=Q(status="success"), default=0),
        fee=Sum("fee_tiyin", filter=Q(status="success"), default=0),
    )
    gross, fee = agg["gross"], agg["fee"]
    diff = (gross - fee) - bank_amount_tiyin  # > 0: the bank received less than expected

    postings = [
        ("bank:main", bank_amount_tiyin),          # debit: money that actually arrived
        ("expense:psp_fees", fee),                 # debit: provider commission
        (f"receivable:{batch.provider}", -gross),  # credit: the provider no longer owes it
    ]
    if diff:
        postings.append(("suspense:reconciliation", diff))  # keeps the entry balanced
    post_entry(
        reference=f"settlement:{batch.provider}:{batch.statement_date}:{bank_ref}",
        postings=postings,
    )
    return diff

Даже при расхождении проводка обязана быть сбалансированной, поэтому разница уходит на отдельный счёт suspense:reconciliation. Ненулевой баланс этого счёта означает, что есть открытый вопрос. Как именно возвраты и отмены вычитаются из settlement, зависит от договора с провайдером — подгоните формулу под него.

Старые проводки никогда не меняются. Когда расхождение разрешено — например, провайдер доплатил недостающее в следующем settlement или мы признали это убытком, — делается новая корректирующая проводка (adjustment) с suspense на нужный счёт, и в reference пишется ID расхождения.

Отчёты и алерты

Весь процесс запускается ежедневно через Celery beat:

# recon/tasks.py
from datetime import date, timedelta

from celery import shared_task
from django.db.models import Count
from django.utils import timezone

from .clients import StatementNotReady, get_client
from .importer import import_statement
from .matching import run_reconciliation
from .models import Discrepancy
from .notify import notify  # Telegram, Slack, e-mail: whatever the team actually reads
from .resolve import try_auto_resolve


@shared_task(bind=True, max_retries=8, default_retry_delay=30 * 60)
def reconcile_day(self, provider: str, day_iso: str | None = None):
    day = date.fromisoformat(day_iso) if day_iso else timezone.localdate() - timedelta(days=1)
    client = get_client(provider)

    try:
        content = client.download_statement(day)
    except StatementNotReady as exc:
        if self.request.retries >= self.max_retries:
            notify(f"[recon] {provider}: statement for {day} has not arrived", urgent=True)
            return
        # pin the day explicitly, otherwise a retry after midnight checks the wrong day
        raise self.retry(exc=exc, args=(provider, day.isoformat()))

    batch = import_statement(provider, day, content)
    run_reconciliation(batch)

    open_qs = Discrepancy.objects.filter(run__provider=provider, state=Discrepancy.State.OPEN)
    for d in open_qs.filter(kind=Discrepancy.Kind.STATUS).select_related("payment"):
        try_auto_resolve(d, client)

    by_kind = dict(open_qs.order_by().values_list("kind").annotate(n=Count("id")))
    stale = open_qs.filter(created_at__lt=timezone.now() - timedelta(days=3)).count()
    notify(
        f"[recon] {provider} {day}: {batch.line_count} lines, open: {by_kind}, older than 3 days: {stale}",
        urgent=bool(by_kind.get("missing_ours") or by_kind.get("amount") or stale),
    )
# config/celery.py
from celery import Celery
from celery.schedules import crontab

app = Celery("config")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.conf.timezone = "Asia/Tashkent"
app.conf.beat_schedule = {
    "reconcile-psp-a": {
        "task": "recon.tasks.reconcile_day",
        "schedule": crontab(hour=9, minute=0),
        "args": ("psp_a",),
    },
}

Банковская выписка обычно приходит по другому каналу, поэтому book_settlement — отдельная задача, которая вызывается после импорта банковского файла.

Когда нужен алерт:

  • Реестр не пришёл. Самый опасный случай, потому что он проходит тихо: расхождений нет, потому что сравнивать не с чем. После исчерпания retry обязательно шлём уведомление.
  • Появились missing_ours или amount — сразу.
  • Открытое расхождение висит несколько дней — напоминание.
  • Разница по settlement не ноль или баланс suspense не ноль.

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

Отсутствие расхождений и отсутствие проверки — две разные вещи. «Ноль расхождений» имеет смысл только тогда, когда реестр пришёл, импортирован и сверен.

Подводные камни в production

  • Часовые пояса. Храните performed_at всегда timezone-aware и выясните по документации провайдера, в каком поясе время в реестре. Окно дня считайте по Asia/Tashkent и передавайте в запрос aware datetime.
  • Retry и дата. Если задача каждый раз заново вычисляет «вчера», retry после полуночи проверит другой день. Поэтому в коде выше дата явно передаётся в retry(args=...).
  • Возвраты (refund). Многие провайдеры отдают возврат отдельной строкой, иногда с отрицательной суммой и в реестре другого дня. Частичные возвраты сверяйте отдельной моделью, иначе расплодятся ложные расхождения amount.
  • Исправленный реестр. Провайдер может прислать файл повторно. Хеш другой — создаётся новый batch. Отмечайте, какой batch актуален (например, полем supersedes), и учитывайте это в запросах.
  • Дубликаты ID провайдера. Одна транзакция может прийти в одном реестре дважды (платёж и его отмена). Ограничение (batch, external_id) уронит импорт — и это хорошо: значит, вы не до конца поняли формат. Дальше добавляете в строку поле типа и расширяете ограничение.
  • Длинные транзакции. Запросы сверки только читают; не заворачивайте их в большой atomic() и не смешивайте с select_for_update(). Блокировка берётся ненадолго и только на изменяемый платёж.
  • Лимиты API провайдера. При автозакрытии на каждое расхождение идёт вызов API. Если расхождений много, упрётесь в rate limit: замедляйте вызовы или разносите их по отдельным задачам.
  • «Подгонка» базы под реестр. Даже если всё очевидно, не делайте руками UPDATE payments_payment SET status = .... Идите через state machine и ledger, иначе следующая сверка найдёт новое расхождение между ledger и Payment.

Чеклист

  • Суммы хранятся в тийинах целым числом; никаких float.
  • Реестр импортируется идемпотентно по хешу, исходная строка лежит в raw.
  • Сверка двусторонняя: реестр → база и база → все реестры.
  • Вывод «у них нет» делается с lag на границу дня.
  • Автозакрытие — только для status и только с подтверждением от API провайдера.
  • Любое исправление — через state machine и ledger; старые записи не меняются.
  • Settlement сверяется с банковской выпиской, разница уходит на suspense.
  • Реестр не пришёл — алерт. Тишина — тоже сигнал.
  • У каждого закрытого расхождения записано, кто, когда и почему его закрыл.

Итог

Как бы хороша ни была интеграция, расхождения между базой и провайдером всё равно появятся — вопрос лишь в том, кто найдёт их первым: вы или клиент. Ежедневная сверка делает их видимыми — с конкретными записями, типами и ответственным. Постройте её на двустороннем SQL-сравнении, осторожном автозакрытии и одном транзитном счёте в ledger — и ответ на вопрос «где деньги?» будет находиться за минуты.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯