В песочнице Payme есть правило, которое легко пропустить при чтении документации: запросы CreateTransaction, PerformTransaction и CancelTransaction она посылает дважды, и ответ на второй должен совпасть с ответом на первый. Интеграция, написанная «по шагам», на этом и падает. Чаще всего из-за одной строки: perform_time: Date.now(), которая на повторе возвращает уже другое время.
Песочница не придирается. Она проверяет ровно то, что потом случится в бою: ответ потерялся по дороге, Payme Business отправил тот же запрос ещё раз и ждёт, что вы ответите так же, как в первый раз. Если интеграция к этому не готова, вы получите либо платёж, который висит у Payme на ручном разборе, либо самый неприятный тикет в интернет-магазине: «деньги списались, а заказ неоплачен».
Дальше — как я строю обработчик Merchant API, чтобы повтор любого запроса был безопасен. Код на TypeScript и PostgreSQL, но от языка тут почти ничего не зависит.
Что Payme обещает и чего требует
Пять фактов из документации, на которых держится всё остальное.
Протокол — JSON-RPC 2.0 поверх HTTP POST. Отвечать нужно всегда со статусом 200, даже на ошибку: бизнес-ошибка лежит в поле
errorтела. Любой другой статус Payme засчитывает как системную ошибку-32400, а не как ваш отказ.Сумма приходит целым числом в тийинах. 15 000 сумов — это
1500000.Время — 13-значный timestamp в миллисекундах.
Если ответ на
CreateTransactionилиPerformTransactionне дошёл, Payme повторяет запрос с теми же параметрами.Транзакция в состоянии «создана» живёт 12 часов (43 200 000 мс), потом её нужно отменять.
Из четвёртого пункта следует главное: идентификатор транзакции Payme (params.id) — это ключ идемпотентности. Свой ключ поверх него придумывать не надо. А проверять «был ли такой запрос» через select перед insert нельзя: два одинаковых запроса, пришедших параллельно, пройдут такую проверку оба.
Таблица, в которую упирается всё
Транзакции провайдера я храню отдельно от заказов. У заказа бывает несколько попыток оплаты, отмены и возвраты, и при разборе инцидента нужно видеть каждую.
create table provider_txn ( id serial primary key, provider text not null, -- 'payme' | 'click' external_id text not null, -- params.id от Payme order_id bigint not null references orders(id), amount_tiyin bigint not null, state smallint not null, -- 1, 2, -1, -2 reason smallint, provider_time bigint, -- params.time, нужен для GetStatement 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;
Две защиты делает база, а не код. Уникальность (provider, external_id) ловит гонку параллельных дублей. Частичный индекс не даёт заказу получить вторую ожидающую транзакцию. Обе работают, сколько бы экземпляров приложения ни было запущено.
Комментарий «пишется один раз» у трёх полей времени — не украшение. На них и падает песочница.
Четыре состояния и все разрешённые переходы
PerformTransaction [нет] ─Create─► (1) ───────────────► (2) │ │ Cancel/таймаут │ │ Cancel, если услуга не оказана ▼ ▼ (-1) (-2)
1 — создана и ждёт, 2 — проведена, -1 — отменена до проведения, -2 — отменена после. Всё, чего нет на схеме, — ошибка -31008, «невозможно выполнить операцию». Отмена по таймауту ставит -1 с причиной 4.
CreateTransaction
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 — // перечитываем строку и отвечаем как в ветке existing. Иначе сработал // one_pending_per_order: у заказа уже есть ожидающая транзакция. const twin = await tx.findTxn('payme', p.id); if (twin) return { create_time: twin.create_time, transaction: String(twin.id), state: twin.state }; throw rpcError(-31008); } return { create_time: row.create_time, transaction: String(row.id), state: 1 }; }); }
Песочница отдельно проверяет случай, когда заказ уже ждёт оплаты по другой транзакции, и ждёт -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, не новое. 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 }; }); }
Смена состояния транзакции и статуса заказа идут в одной транзакции базы. Именно разрыв между ними даёт «оплачено, а заказа нет». Сценарий простой: обработчик записал state = 2, потом пошёл отправлять SMS или чек, упал на таймауте и не дошёл до заказа. Payme повторит запрос, увидит state = 2, получит успешный ответ, и заказ останется неоплаченным навсегда. Поэтому всё, что ходит в сеть, уходит в outbox и выполняется отдельным обработчиком после коммита.
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) { 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 означает «товар или услуга уже предоставлены, отменить нельзя». Решать это по флагу «оплачен» неправильно: оплачен и отгружен — разные вещи. Нужен настоящий признак из вашей системы: отгрузка, выданный доступ, оказанная услуга.
CheckTransaction и GetStatement
CheckTransaction отдаёт из той же строки create_time, perform_time, cancel_time, transaction, state и reason. Нет строки — -31003.
Про GetStatement часто забывают, а именно по нему Payme сверяется с вами. Метод возвращает транзакции, у которых время создания в Payme (time из CreateTransaction) попадает в диапазон from ≤ time ≤ to, по возрастанию. Транзакции, на которых CreateTransaction вернул ошибку, туда не попадают. Ради этого метода provider_time хранится отдельно от собственного create_time: это два разных времени, и путать их нельзя.
Авторизация
Payme присылает Authorization: Basic …, паролем служит ключ кассы — в кабинете он так и называется, «ключ-пароль». Неверные данные — -32504. Песочница проверяет и этот сценарий. Ключ сравнивайте функцией с постоянным временем (crypto.timingSafeEqual), а не через ===.
Чек-лист перед боем
params.id— ключ идемпотентности, защищённый уникальным индексом, а не проверкой в коде.Повторный запрос получает сохранённые
create_time,perform_time,cancel_time.Ответ всегда с HTTP 200, ошибки — в теле.
Суммы — целые тийины, никакого
float.Таймаут 43 200 000 мс проверяется в
CreateTransactionиPerformTransaction.Транзакция Payme и статус заказа меняются в одной транзакции базы; всё сетевое — в outbox.
-31007решается по факту отгрузки, а не по флагу оплаты.Песочница test.paycom.uz пройдена полностью до первого реального платежа.
В следующей части — Click: там два шага вместо шести методов, подпись MD5 и другой ответ на повтор. И ночная сверка, которая ловит то, что пропустили оба провайдера.
Источники
Payme Business, методы Merchant API: https://developer.help.paycom.uz/metody-merchant-api/
CreateTransaction и таймаут: https://developer.help.paycom.uz/metody-merchant-api/createtransaction
Типы данных (State, Reason, Timestamp): https://developer.help.paycom.uz/metody-merchant-api/tipy-dannykh
Ошибки: https://developer.help.paycom.uz/metody-merchant-api/oshibki-errors
Протокол и HTTP 200: https://developer.help.paycom.uz/protokol-merchant-api/
Схема взаимодействия, повторы: https://developer.help.paycom.uz/protokol-merchant-api/skhema-vzaimodeystviya
GetStatement: https://developer.help.paycom.uz/metody-merchant-api/getstatement
Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
