В первой части был Payme: шесть методов JSON-RPC, четыре состояния и песочница, которая повторяет каждый запрос. У Click всё устроено иначе: два шага вместо шести, подпись MD5 вместо Basic Auth, сумма в сумах вместо тийинов и, что важнее всего, другой ответ на повтор. Если писать обе интеграции по одному шаблону, одна из них сломается.
А в конце — то, что не входит ни в один протокол, но без чего я бы не запускал приём платежей: ночная сверка.
Чем Click отличается от Payme
Payme Merchant API | Click SHOP API | |
|---|---|---|
Формат | JSON-RPC 2.0 | POST, |
Проверка | Basic Auth, ключ кассы |
|
Сумма | целое, в тийинах | дробное, в сумах |
Ключ идемпотентности |
|
|
Шаги | Check → Create → Perform, плюс Cancel, CheckTransaction, GetStatement | Prepare ( |
Повтор проведённого платежа | тот же успешный ответ | ошибка |
Последняя строка — та, на которой спотыкаются, когда переносят код с 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
Ключ идемпотентности —
click_trans_idс уникальным индексом в базе.Подпись проверяется по исходным строкам запроса, без приведения типов.
Сумма сравнивается с заказом в целых тийинах.
На повторный
Complete—-4; наerror < 0от Click — отмена у себя и-9.Товар нельзя отпустить после списания — успешный
Completeи reversal в тот же день, а не ошибка.Ночная сверка: четыре внутренних инварианта и внешний реестр, каждое расхождение — задача с ответственным.
Источники
Click, SHOP API — запросы: https://docs.click.uz/shop-api/requests
Click, SHOP API — ошибки: https://docs.click.uz/shop-api/errors
Click, Merchant API — status_by_mti, reversal, авторизация: https://docs.click.uz/merchant-api/requests
Payme Business, GetStatement: https://developer.help.paycom.uz/metody-merchant-api/getstatement
Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
