Как принять оплату без «деньги списались, а заказа нет»: Payme, Click и ночная сверка на PostgreSQL и TypeScriptЛонгрид · дайджест за 22 ноября
Предметный натюрморт рабочего места инженера с блокнотом архитектуры платежей, таблицей provider_txn и консолью со статусом 200 OK
Лонгрид7 разделов≈ 28 мин

Как принять оплату без «деньги списались, а заказа нет»: Payme, Click и ночная сверка на PostgreSQL и TypeScript

Представь обычный вечер перед релизом интернет-магазина. Ты аккуратно подключил оплату через Payme Business Merchant API, прогнал заказ на 15 000 сумов, в базе проставился статус «оплачен», всё красиво. Запускаешь автоматические тесты в песочнице Payme — и тесты валятся на первом же прогоне.

В чём подвох? В песочнице зашито правило, на которое редко обращают внимание при чтении доки: запросы CreateTransaction, PerformTransaction и CancelTransaction она шлёт по два раза подряд и ждёт, что второй ответ совпадёт с первым байт в байт. Интеграция, собранная «по шагам», падает на одной безобидной строчке: perform_time: Date.now(). На втором запросе часы ушли вперёд на пару сотен миллисекунд — ответ другой, тест красный.

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

Разберём, как собрать отказоустойчивый приём платежей на PostgreSQL и TypeScript сразу под двух разных провайдеров — Payme и Click SHOP API — и прикрыть систему ночной сверкой. Примеры привязаны к узбекским сумам и тийинам, но сама схема работы с базой, гонками и расхождениями один в один переносится на любую другую платёжку.

Пять правил контракта Payme и ловушка SELECT перед INSERT

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

  1. Протокол — JSON-RPC 2.0 поверх HTTP POST. Отвечать нужно всегда со статусом 200, даже если заказ не найден или сумма не сошлась. Бизнес-ошибка едет внутри поля error в JSON (с числовым кодом и локализованным объектом message на ru, uz и en). Любой другой HTTP-код вроде 400 или 404 провайдер воспримет как системный сбой -32400, а не как наш отказ.
  2. Сумма приходит целым числом в тийинах (15 000 сумов превращаются в 1 500 000). Никакого float и арифметики с плавающей точкой.
  3. Время — 13-значный Unix timestamp в миллисекундах.
  4. Если ответ на CreateTransaction или PerformTransaction потерялся, Payme повторяет вызов с теми же параметрами.
  5. Транзакция в статусе «создана» живёт ровно 12 часов (43 200 000 мс), после чего её нужно отменить.

Из четвёртого пункта вытекает главная штука: внешний идентификатор транзакции Payme (params.id) уже является ключом идемпотентности. Идемпотентность — это свойство операции, при котором повторный вызов с теми же данными даёт точно такой же результат и не ломает состояние системы. Придумывать поверх params.id собственный ключ не нужно.

Первая мысль тут напрашивается сама собой: сделать в коде SELECT, проверить, нет ли такой записи в базе, и если нет — выполнить INSERT. На локальном ноутбуке это сработает. На продакшене два одинаковых вебхука прилетают с разницей в пару миллисекунд на два разных воркера Node.js. Оба делают SELECT, оба видят пустоту и оба спокойно идут на INSERT. Гонка выиграна багом, а не нами. Защиту от дублей должна держать сама база данных.

Единый фундамент в PostgreSQL: таблица provider_txn

Транзакции платёжных шлюзов лучше сразу хранить в отдельной таблице, а не складывать полями в orders. У одного заказа легко набирается несколько попыток оплаты: клиент начал платить через Payme, передумал, вернулся через час и оплатил в Click, а потом попросил возврат. Когда случится разбор инцидента, тебе понадобится история каждой попытки.

create table provider_txn (
  id serial primary key,
  -- 'payme' | 'click'
  provider text not null,
  -- params.id от Payme или click_trans_id от Click
  external_id text not null,
  order_id bigint not null references orders(id),
  amount_tiyin bigint not null,
  -- 1 создана, 2 проведена, -1 отменена до, -2 отменена после
  state smallint not null,
  reason smallint,
  -- params.time от Payme, нужен для сверки GetStatement
  provider_time bigint,
  -- Три поля времени ниже пишутся строго один раз
  create_time bigint not null,
  perform_time bigint not null default 0,
  cancel_time bigint not null default 0,
  raw_last jsonb,
  unique (provider, external_id)
);

-- У заказа не может быть второй ожидающей транзакции Payme
create unique index one_pending_per_order
  on provider_txn (order_id)
  where provider = 'payme' and state = 1;

Две главные защиты здесь встроены прямо в PostgreSQL и работают одинаково надёжно, хоть у тебя один контейнер приложения, хоть двадцать реплик. Составная уникальность (provider, external_id) жёстко отсекает гонку параллельных дублей. А частичный уникальный индекс one_pending_per_order (partial unique index — индекс с условием where, который проверяет уникальность лишь для подходящих строк) не даёт одному заказу получить вторую активную транзакцию Payme в состоянии ожидания.

Отдельно присмотрись к трём колонкам времени: create_time, perform_time и cancel_time. Комментарий «пишутся один раз» там стоит не для красоты. Как только транзакция перешла в нужное состояние, время фиксируется в строке и на всех будущих повторах отдаётся из базы без вызова Date.now().

Машина состояний Payme, Transactional Outbox и авторизация

В протоколе Payme у транзакции ровно четыре состояния и четыре разрешённых перехода между ними:

                       PerformTransaction
  [нет] --Create--> (1) -----------------> (2) проведена
                     |                      |
      Cancel/таймаут |                      | Cancel (услуга не оказана)
                     v                      v
                   (-1)                   (-2)

Здесь 1 означает, что транзакция создана и ждёт подтверждения, 2 соответствует проведённой оплате, -1 ставится при отмене до проведения, а -2 фиксирует отмену уже после проведения. Любая попытка прыгнуть мимо этой схемы должна возвращать JSON-RPC ошибку -31008 («невозможно выполнить операцию»). Если транзакция протухла по 12-часовому таймауту, переводим её в -1 с кодом причины reason = 4.

Посмотрим, как устроен обработчик CreateTransaction. Внутри транзакции БД мы сначала ищем строку с блокировкой SELECT ... FOR UPDATE — эта конструкция ставит эксклюзивную блокировку на найденную строку до коммита, чтобы параллельный запрос подождал и не изменил её в тот же момент.

const TIMEOUT_MS = 43_200_000;

async function createTransaction(
  p: CreateParams,
): Promise<RpcResult> {
  return db.tx(async (tx) => {
    const existing = await tx.oneOrNone<ProviderTxn>(
      `select * from provider_txn
       where provider = 'payme' and external_id = $1
       for update`,
      [p.id],
    );

    if (existing) {
      if (existing.state !== 1) throw rpcError(-31008);
      if (Date.now() - existing.create_time > TIMEOUT_MS) {
        await cancel(tx, existing, -1, 4);
        throw rpcError(-31008);
      }
      // Повтор запроса: отдаём то же сохранённое время
      return {
        create_time: existing.create_time,
        transaction: String(existing.id),
        state: 1,
      };
    }

    const order = await tx.findOrderForUpdate(p.account.order_id);
    if (!order) throw rpcError(-31050, 'order_id');
    if (order.amount_tiyin !== p.amount) throw rpcError(-31001);
    if (order.status !== 'awaiting_payment') {
      throw rpcError(-31008);
    }

    const row = await tx.insertOrNull('provider_txn', {
      provider: 'payme',
      external_id: p.id,
      order_id: order.id,
      amount_tiyin: p.amount,
      state: 1,
      provider_time: p.time,
      create_time: Date.now(),
    });

    if (!row) {
      // Конфликт уникальности: проверяем, дубль ли это params.id
      const twin = await tx.findTxn('payme', p.id);
      if (twin) {
        return {
          create_time: twin.create_time,
          transaction: String(twin.id),
          state: twin.state,
        };
      }
      // Иначе сработал one_pending_per_order: заказ уже занят
      throw rpcError(-31008);
    }

    return {
      create_time: row.create_time,
      transaction: String(row.id),
      state: 1,
    };
  });
}

Тут хорошо видно, зачем мы завели частичный индекс one_pending_per_order. Песочница Payme проверяет хитрый кейс: заказ уже ждёт оплаты по одной транзакции, и прилетает вторая на тот же заказ. В тексте документации это сформулировано обтекаемо (требуется бронировать заказ до оплаты или таймаута), а песочница прямо ждёт код -31008. Частичный индекс переводит всю эту логику в штатный конфликт вставки: если по params.id строки нет, значит сработал индекс занятого заказа, и мы спокойно кидаем -31008.

Теперь самое опасное место всей интеграции — PerformTransaction. Именно здесь на продакшене теряются деньги.

async function performTransaction(
  p: { id: string },
): Promise<RpcResult> {
  return db.tx(async (tx) => {
    const t = await tx.lockTxn('payme', p.id);
    if (!t) throw rpcError(-31003);

    if (t.state === 2) {
      // Повтор: возвращаем сохранённое perform_time, не Date.now()
      return {
        transaction: String(t.id),
        perform_time: t.perform_time,
        state: 2,
      };
    }

    if (t.state !== 1) throw rpcError(-31008);
    if (Date.now() - t.create_time > TIMEOUT_MS) {
      await cancel(tx, t, -1, 4);
      throw rpcError(-31008);
    }

    const performTime = Date.now();
    await tx.update('provider_txn', t.id, {
      state: 2,
      perform_time: performTime,
    });
    await tx.markOrderPaid(t.order_id, t.id);
    await tx.insert('outbox', {
      type: 'order.paid',
      order_id: t.order_id,
    });

    return {
      transaction: String(t.id),
      perform_time: performTime,
      state: 2,
    };
  });
}

Смотри на три строчки перед return. Смена статуса транзакции в provider_txn, перевод заказа в paid и запись события в таблицу outbox едут в одной транзакции PostgreSQL. Что случится, если разорвать эти шаги? Допустим, обработчик записал state = 2, потом пошёл в сеть отправлять SMS с чеком, поймал таймаут внешнего шлюза и упал, так и не обновив заказ. Payme повторит PerformTransaction, наш код увидит state === 2, радостно вернёт успешный ответ — и заказ останется неоплаченным навсегда.

Чтобы этого избежать, применяется паттерн Transactional Outbox. Вместо прямых сетевых вызовов внутри платёжного вебхука мы просто пишем строку-задачу в таблицу outbox в той же транзакции базы. Отдельный фоновый воркер позже вычитывает новые строки из outbox и спокойно шлёт SMS, фискальные чеки и уведомления на склад.

Архитектурная схема паттерна Transactional Outbox: запись состояния и события в одной транзакции БД (Источник: microservices.io)

С отменой CancelTransaction логика тоже прозрачная, но с одной подковыркой.

async function cancelTransaction(
  p: { id: string; reason: number },
) {
  return db.tx(async (tx) => {
    const t = await tx.lockTxn('payme', p.id);
    if (!t) throw rpcError(-31003);

    if (t.state === 1) {
      await cancel(tx, t, -1, p.reason);
    } else if (t.state === 2) {
      // -31007 только по реальному факту отгрузки или выдачи
      if (await tx.isOrderFulfilled(t.order_id)) {
        throw rpcError(-31007);
      }
      await cancel(tx, t, -2, p.reason);
    }

    // Для уже отменённых (-1 и -2) отдаём сохранённое время
    const fresh = await tx.getTxn(t.id);
    return {
      transaction: String(fresh.id),
      cancel_time: fresh.cancel_time,
      state: fresh.state,
    };
  });
}

Код -31007 переводится как «товар или услуга уже предоставлены, отменить нельзя». Частая ошибка — проверять это по флагу «заказ оплачен». Оплачен и отгружен — разные вещи. Если клиент оплатил подписку или курьер уже отдал коробку, тогда возвращаем -31007. Если заказ просто висит в статусе paid и ещё не уехал со склада, транзакцию можно перевести в -2.

Остаются два вспомогательных метода и авторизация. CheckTransaction просто отдаёт поля из строки provider_txn (если строки нет — -31003). А вот про GetStatement на старте частенько забывают, хотя именно через него Payme сверяется с магазином. Метод возвращает список транзакций по возрастанию, у которых время создания на стороне Payme (params.time из CreateTransaction) попадает в отрезок from <= time <= to, без записей, где CreateTransaction упал с ошибкой. Именно ради GetStatement мы держим колонку provider_time отдельно от локального create_time — путать их нельзя.

Авторизацию Payme шлёт в заголовке Authorization: Basic ..., где паролем выступает ключ кассы из кабинета (в интерфейсе он называется «ключ-пароль»). На неверный ключ отвечаем -32504, песочница это тоже проверяет. Сравнивать секрет через обычное === не стоит: стандартное сравнение строк обрывается на первом несовпавшем символе, что теоретически даёт утечку по времени отклика (timing-атака). В Node.js для этого есть встроенная функция crypto.timingSafeEqual, которая всегда сравнивает буферы за постоянное время.

Почему шаблон Payme ломается на Click SHOP API

Как только интеграция с Payme заработала, возникает соблазн скопировать обработчики, поменять имена полей и за вечер подключить второй шлюз — Click. Если сделать так в лоб, интеграция с Click сломается. Протоколы устроены по-разному почти в каждой мелочи.

Инженерная схема сопоставления протоколов Payme и Click с форматами JSON-RPC и URL-encoded, расчетом сумм и кодами ответов

ПараметрPayme Merchant APIClick SHOP API
Формат запросаJSON-RPC 2.0 (HTTP POST, всегда 200)POST, application/x-www-form-urlencoded
Авторизация / подписьBasic Auth (ключ кассы)sign_string (MD5 с SECRET_KEY)
СуммаЦелое число в тийинах (1500000)Дробная строка в сумах ("15000.00")
Ключ идемпотентностиparams.idclick_trans_id
Шаги протокола6 методов (Check, Create, Perform, Cancel, CheckTransaction, GetStatement)2 шага: Prepare (action=0) -> Complete (action=1)
Повтор проведённого платежаТот же успешный ответОшибка -4 («Already paid»)

Самая болезненная строчка в таблице — последняя. В Payme на повторный PerformTransaction ты обязан вернуть точно такой же успешный JSON с сохранённым perform_time. В Click на повторный Complete нужно вернуть ошибку -4. Но прежде чем добраться до шагов оплаты, легко споткнуться ещё на двух вещах: подписи и деньгах.

У двух шагов Click формулы MD5-подписи различаются на одно поле (merchant_prepare_id появляется только на втором шаге):

Prepare:
md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id
    + amount + action + sign_time)

Complete:
md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id
    + merchant_prepare_id + amount + action + sign_time)

Здесь прячется классическая грабля. Склеивать поля в строку для хеширования нужно ровно в том виде, в каком они прилетели в теле формы, до любого парсинга в числа и даты. Если Click прислал amount как "15000.00", а твой фреймворк успел превратить его в число 15000 и обратно в строку "15000", подпись не сойдётся, и ты начнёшь отбивать валидные платежи кодом -1.

Для сверки суммы с заказом из нашей базы переводим строку в целые тийины через BigInt — без Number и без parseFloat, чтобы не словить сюрпризы вроде 19.99 * 100 === 1998.9999999999998:

function sumToTiyin(s: string): bigint {
  // Принимаем целые сумы и максимум два знака после точки
  const m = /^(\d+)(?:\.(\d{1,2}))?$/.exec(s);
  if (!m) throw new ClickError(-2);
  const sums = BigInt(m[1]) * 100n;
  const tiyins = BigInt((m[2] ?? '').padEnd(2, '0'));
  return sums + tiyins;
}

Функция режет строку регуляркой на целую и дробную части, добивает дробную нулями до двух знаков и складывает всё в BigInt. Вся палитра кодов ответа в документации ошибок Click SHOP API компактная: 0 (успех), -1 (неверная подпись), -2 (неверная сумма), -3 (действие не найдено), -4 (уже оплачено), -5 (заказ не найден), -6 (транзакция не найдена), -7 (ошибка обновления), -8 (ошибка в запросе от Click) и -9 (транзакция отменена).

Prepare, Complete и возврат через reversal в Click

На первом шаге (Prepare, action === '0') Click спрашивает наш бэкенд: заказ живой, сумма верная, товар можно отдать? Здесь же магазину стоит зарезервировать товар на складе.

async function prepare(r: ClickPrepare): Promise<ClickResponse> {
  if (!verifySign(r, { withPrepareId: false })) return err(-1);
  if (r.action !== '0') return err(-3);

  return db.tx(async (tx) => {
    const order = await tx.findOrderForUpdate(r.merchant_trans_id);
    if (!order) return err(-5);
    if (order.status === 'paid') return err(-4);
    if (order.amount_tiyin !== sumToTiyin(r.amount)) {
      return err(-2);
    }

    // insert ... on conflict do nothing, затем select:
    // повторный Prepare вернёт тот же merchant_prepare_id
    const t = await tx.insertOrGet(
      'provider_txn',
      { provider: 'click', external_id: r.click_trans_id },
      {
        order_id: order.id,
        amount_tiyin: sumToTiyin(r.amount),
        state: 1,
        create_time: Date.now(),
      },
    );

    if (t.state < 0) return err(-9);
    return ok({
      click_trans_id: r.click_trans_id,
      merchant_trans_id: r.merchant_trans_id,
      merchant_prepare_id: t.id,
    });
  });
}

Таблица provider_txn используется та же самая, что и для Payme. Составной уникальный индекс (provider, external_id) страхует от повторного Prepare, а первичный ключ t.id уезжает в Click как merchant_prepare_id.

На втором шаге (Complete, action === '1') Click присылает обратно наш merchant_prepare_id и сообщает итог списания.

async function complete(r: ClickComplete): Promise<ClickResponse> {
  if (!verifySign(r, { withPrepareId: true })) return err(-1);
  if (r.action !== '1') return err(-3);

  return db.tx(async (tx) => {
    const t = await tx.lockTxnById(Number(r.merchant_prepare_id));
    if (!t || t.external_id !== r.click_trans_id) return err(-6);
    // Повтор Complete по проведённой оплате -> -4 ("Already paid")
    if (t.state === 2) return err(-4);
    if (t.state < 0) return err(-9);

    if (Number(r.error) < 0) {
      // Платёж не прошёл на стороне Click: отменяем у себя
      await cancel(tx, t, -1, null);
      return err(-9);
    }

    await tx.update('provider_txn', t.id, {
      state: 2,
      perform_time: Date.now(),
    });
    await tx.markOrderPaid(t.order_id, t.id);
    await tx.insert('outbox', {
      type: 'order.paid',
      order_id: t.order_id,
    });

    return ok({
      click_trans_id: r.click_trans_id,
      merchant_trans_id: r.merchant_trans_id,
      merchant_confirm_id: t.id,
    });
  });
}

Обрати внимание на ветку Number(r.error) < 0. Если у клиента не хватило денег на карте или банк отклонил списание, Click всё равно присылает Complete, но с отрицательным полем error. В этот момент мы обязаны перевести локальную транзакцию в отменённую (state = -1) и ответить -9.

А теперь правило из примечания к Click SHOP API, о котором обычно узнают уже после первого скандального инцидента. Допустим, Prepare прошёл, деньги с карты клиента списались, прилетел Complete с error = 0 — а последняя единица товара за эту минуту ушла другому покупателю. Отвечать на Complete ошибкой нельзя: деньги клиента зависнут, и платёж уйдёт на ручной разбор. По контракту Click на Complete после списания можно вернуть ошибку лишь в двух случаях — платёж уже подтверждён (-4) или отменён (-9).

Правильный выход такой: отвечаем Click успехом (0), а следом инициируем возврат (reversal — принудительная отмена уже проведённого платежа) через Click Merchant API: DELETE /v2/merchant/payment/reversal/:service_id/:payment_id. Тянуть с этим нельзя. У отмены жёсткие рамки: платёж должен быть завершён и оплачен онлайн-картой, вернуть его можно только в текущем отчётном месяце (за прошлый месяц — лишь в первый день нового), а платёжная система UZCARD вправе отклонить отмену. Если расхождение поймали не в тот же день, а в конце месяца при закрытии актов, автоматический reversal уже не сработает.

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

Симулятор платёжного вебхука: Payme против Click

Когда держишь перед глазами оба контракта рядом, сразу отпадает желание свалить Payme и Click в один «универсальный» контроллер. Общей остаётся только схема базы provider_txn + outbox, а протокольные адаптеры у каждого шлюза должны жить порознь и честно соблюдать чужие коды ответов.

Третий слой защиты: ночная сверка (reconciliation)

Идемпотентность и индексы PostgreSQL хорошо закрывают гонки и повторы, но они бессильны против других жизненных сбоев. Процесс мог упасть ровно между коммитом и отправкой HTTP-ответа. Менеджер в админке мог руками переключить статус заказа. Провайдер мог отменить операцию на своей стороне без вебхука. Такие расхождения ловит только регулярная сверка (reconciliation) — и запускать её нужно каждую ночь, а не раз в месяц перед бухгалтерским актом.

Сначала джоба прогоняет четыре SQL-запроса по внутренним инвариантам нашей базы. В здоровой системе все четыре обязаны вернуть ноль строк. Каждая найденная строка — готовый инцидент:

Архитектурная изометрическая схема ночной сверки транзакций с сопоставлением базы данных PostgreSQL и внешних реестров провайдеров

-- 1. Деньги проведены, а заказ не оплачен (paid_not_fulfilled)
select t.*
from provider_txn t
join orders o on o.id = t.order_id
where t.state = 2
  and o.status <> 'paid';

-- 2. Заказ оплачен, а проведённой транзакции нет (order_without_txn)
select o.*
from orders o
where o.status = 'paid'
  and not exists (
    select 1 from provider_txn t
    where t.order_id = o.id and t.state = 2
  );

-- 3. Двойная оплата одного заказа (double_payment)
select order_id, count(*)
from provider_txn
where state = 2
group by order_id
having count(*) > 1;

-- 4. Зависшие транзакции в state = 1 дольше 12 часов (stuck_pending)
select *
from provider_txn
where state = 1
  and create_time <
      (extract(epoch from now()) * 1000)::bigint - 43200000;

Может возникнуть резонный вопрос: откуда вообще возьмётся третий кейс (double_payment), если у нас уже есть частичный индекс one_pending_per_order? Вспомни его условие: where provider = 'payme' and state = 1. Он страхует от дублей только внутри Payme. Если покупатель бросил оплату в Payme и через пять минут спокойно оплатил тот же заказ в Click, система не должна ему мешать. Блокировать клиента ради редкого совпадения гораздо хуже, чем раз в полгода поймать двойную оплату ночной сверкой и оформить возврат.

После проверки внутренних инвариантов сверяемся с внешними провайдерами. У Click в Merchant API есть точечный эндпоинт проверки статуса по нашему номеру заказа:

GET /v2/merchant/payment/status_by_mti/:service_id/:merchant_trans_id/YYYY-MM-DD

Для него передаётся заголовок Auth: merchant_user_id:digest:timestamp, где digest = sha1(timestamp + secret_key). Тут притаилась ещё одна ловушка с единицами измерения: в отличие от 13-значных миллисекунд Payme, в заголовке Auth у Click передаётся Unix-время в секундах. Этот запрос удобно дёргать точечно по всем подозрительным заказам из запросов 1, 2 и 4.

С Payme направление обратное: GetStatement вызывает сам Payme, сверяясь с нами, поэтому наш ответ обязан совпадать с таблицей provider_txn, а со своей стороны мы сопоставляем базу с суточным реестром операций и банковскими зачислениями. Вот как выглядит скелет самой ночной задачи:

async function nightlyReconciliation(day: Date) {
  const findings: Finding[] = [
    ...(await db.many(Q_PAID_TXN_UNPAID_ORDER))
      .map((r) => f('paid_not_fulfilled', r)),
    ...(await db.many(Q_PAID_ORDER_NO_TXN))
      .map((r) => f('order_without_txn', r)),
    ...(await db.many(Q_DOUBLE_PAYMENT))
      .map((r) => f('double_payment', r)),
    ...(await db.many(Q_STUCK_PENDING))
      .map((r) => f('stuck_pending', r)),
  ];

  // Для Click уточняем живой статус заказа в Merchant API
  for (const x of findings.filter((i) => i.provider === 'click')) {
    x.external = await click.statusByMti(x.merchant_trans_id, day);
  }

  const registry = await loadProviderRegistry(day);
  // Сохраняем сырой реестр до любой обработки
  await archiveRaw(day, registry);
  // Сравниваем строго по ID провайдера, а не по сумме и времени
  findings.push(...diffById(await db.txnsForDay(day), registry));

  // На каждое расхождение заводим задачу с ответственным
  for (const x of findings) {
    await tickets.open(x);
  }
}

Две последние детали в этом коде на практике экономят часы разборов. Во-первых, сопоставлять операции с реестром нужно строго по внешнему ID провайдера (params.id или click_trans_id), а не по паре «сумма + время»: две покупки на 15 000 сумов в одну и ту же минуту случаются в любом магазине каждый день. Во-вторых, исходный файл реестра нужно архивировать в сыром виде до любых парсеров и фильтров — когда через неделю бухгалтерия или поддержка спросят, откуда взялось расхождение, ты достанешь оригинал от провайдера, а не пережёванную копию.

Практический чек-лист перед запуском в продакшен

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

Чек-лист перед запуском Payme и Click в бой

  • В PostgreSQL создана таблица provider_txn с unique (provider, external_id) и частичным индексом one_pending_per_order — защита от гонок живёт в БД, а не в SELECT перед INSERT.
  • Поля create_time, perform_time и cancel_time записываются один раз и возвращаются на повторах неизменными; для GetStatement в Payme отдельно хранится provider_time.
  • Обработчик Payme всегда отвечает HTTP 200 (ошибки в JSON), проверяет 12-часовой таймаут 43 200 000 мс в CreateTransaction и PerformTransaction, а ключ Basic Auth сверяет через crypto.timingSafeEqual.
  • Смена provider_txn.state = 2, перевод заказа в paid и запись задачи в outbox идут в одной транзакции БД; SMS, чеки и вебхуки шлёт отдельный воркер.
  • Ошибка -31007 в Payme (CancelTransaction) завязана на реальный факт отгрузки или выдачи услуги, а не на статус «оплачен».
  • В Click MD5-подпись проверяется по сырым строкам формы до приведения типов, а сумма переводится в целые тийины через BigInt без float.
  • На повторный Complete в Click отдаётся -4, на входящий error < 0 транзакция отменяется с кодом -9, а при нехватке товара после списания возвращается 0 и сразу вызывается DELETE /v2/merchant/payment/reversal/....
  • Песочница test.paycom.uz пройдена полностью, а ночная джоба nightlyReconciliation с четырьмя SQL-инвариантами, архивом сырого реестра и тикетами крутится по расписанию каждый день.

Если вся эта связка прошла зелёным в песочнице Payme, выдержала тестовые повторы Complete в Click и выдала пустой отчёт в ночной сверке, платёжный бэкенд готов к реальному трафику — даже когда у покупателя на полсекунды отвалится мобильный интернет ровно в момент списания.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 7