В первой части был Payme: шесть методов JSON-RPC, четыре состояния и песочница, которая повторяет каждый запрос. У Click всё устроено иначе: два шага вместо шести, подпись MD5 вместо Basic Auth, сумма в сумах вместо тийинов и, что важнее всего, другой ответ на повтор. Если писать обе интеграции по одному шаблону, одна из них сломается.

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

Чем Click отличается от Payme

Payme Merchant API

Click SHOP API

Формат

JSON-RPC 2.0

POST, application/x-www-form-urlencoded

Проверка

Basic Auth, ключ кассы

sign_string, MD5 с SECRET_KEY

Сумма

целое, в тийинах

дробное, в сумах

Ключ идемпотентности

params.id

click_trans_id

Шаги

Check → Create → Perform, плюс Cancel, CheckTransaction, GetStatement

Prepare (action=0) → Complete (action=1)

Повтор проведённого платежа

тот же успешный ответ

ошибка -4, «Already paid»

Последняя строка — та, на которой спотыкаются, когда переносят код с Payme. Об этом ниже.

Подпись

У двух шагов подписи разные:

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)

Строки склеиваются в том виде, в каком пришли. amount нельзя переформатировать перед подписью: если Click прислал 15000.00, подписывать нужно 15000.00, а не 15000. Поэтому проверять подпись нужно до того, как поля формы превратились в числа и даты.

Для сравнения с заказом сумма переводится в целые тийины без участия float:

function sumToTiyin(s: string): bigint {
  const m = /^(\d+)(?:\.(\d{1,2}))?$/.exec(s);
  if (!m) throw new ClickError(-2);
  return BigInt(m[1]) * 100n + BigInt((m[2] ?? '').padEnd(2, '0'));
}

Коды ошибок, которые возвращает поставщик: 0 — успех, -1 — неверная подпись, -2 — неверная сумма, -3 — действие не найдено, -4 — уже оплачено, -5 — заказ не найден, -6 — транзакция не найдена, -7 — ошибка обновления, -8 — ошибка в запросе от Click, -9 — транзакция отменена.

Prepare

На этом шаге 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 с тем же
    // click_trans_id получает тот же 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). Её id и становится merchant_prepare_id.

Complete

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);

    if (t.state === 2) return err(-4);   // повтор Complete: «Already paid»
    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,
    });
  });
}

Вот разница с Payme. На повторный Complete по проведённому платежу документация Click предписывает ответить -4, а не повторить успех. В примечании к SHOP API это сказано прямо: если Prepare прошёл и деньги списаны, ответ на Complete не может быть ошибкой, кроме двух случаев — платёж уже подтверждён (-4) или повторно подтверждается отменённый (-9).

Из того же примечания следует правило, о котором вспоминают уже после инцидента. Деньги списаны, а товар отпустить нельзя, например он закончился на складе. Отвечать на Complete ошибкой нельзя: деньги клиента зависнут, а платёж уйдёт на ручной разбор. Нужно ответить успехом, а потом отменить платёж через Merchant API: DELETE /v2/merchant/payment/reversal/:service_id/:payment_id. И не откладывать. Условия у отмены жёсткие: платёж должен быть успешно завершён и оплачен онлайн-картой, отменить можно только платёж текущего отчётного месяца (прошлого — лишь в первый день нового), а UZCARD вправе отмену отклонить. Значит, сверка должна ловить такие случаи в тот же день.

Ночная сверка: третий слой

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

Сначала — внутренние инварианты. Каждая строка из этих запросов уже инцидент:

-- 1. Оплачено, а заказ не оплачен.
select t.* from provider_txn t join orders o on o.id = t.order_id
 where t.state = 2 and o.status <> 'paid';

-- 2. Заказ оплачен, а проведённой транзакции нет.
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. Двойная оплата: две проведённые транзакции на один заказ.
select order_id, count(*) from provider_txn
 where state = 2 group by order_id having count(*) > 1;

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

Третий запрос нужен потому, что запрет на вторую ожидающую транзакцию действует внутри одного провайдера. Клиент, бросивший оплату в 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), а timestamp — Unix-время в секундах, не в миллисекундах, как у Payme. Его удобно звать точечно для заказов из запросов 1, 2 и 4. С Payme направление обратное: GetStatement — это инструмент, которым Payme сверяется с вами, поэтому ваш ответ должен совпадать с вашей же таблицей, а сами вы сверяетесь с реестром операций и фактическими зачислениями.

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)),
  ];

  for (const x of findings.filter((x) => x.provider === 'click')) {
    x.external = await click.statusByMti(x.merchant_trans_id, day);
  }

  const registry = await loadProviderRegistry(day);
  await archiveRaw(day, registry);                                   // как пришёл, до обработки
  findings.push(...diffById(await db.txnsForDay(day), registry));   // по ID, не по сумме

  for (const x of findings) await tickets.open(x);                  // задача с ответственным
}

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

Чек-лист для Click

  1. Ключ идемпотентности — click_trans_id с уникальным индексом в базе.

  2. Подпись проверяется по исходным строкам запроса, без приведения типов.

  3. Сумма сравнивается с заказом в целых тийинах.

  4. На повторный Complete — -4; на error < 0 от Click — отмена у себя и -9.

  5. Товар нельзя отпустить после списания — успешный Complete и reversal в тот же день, а не ошибка.

  6. Ночная сверка: четыре внутренних инварианта и внешний реестр, каждое расхождение — задача с ответственным.

Источники