В первой части был 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
Комментарии 0