Click SHOP API: подпись, Prepare и Complete, и ночная сверка, которая ловит «оплачено, а заказа нет»

В первой части был 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 { 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 { 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. Ночная сверка: четыре внутренних инварианта и внешний реестр, каждое расхождение — задача с ответственным.

Источники

  • 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

Источник: habr.com

0 0 голоса
Рейтинг новости
1
0
Подписаться
Уведомить о
0 комментариев