Payme Merchant API: песочница шлёт каждый запрос дважды, и это лучший тест вашей интеграции

В песочнице Payme есть правило, которое легко пропустить при чтении документации: запросы CreateTransaction, PerformTransaction и CancelTransaction она посылает дважды, и ответ на второй должен совпасть с ответом на первый. Интеграция, написанная «по шагам», на этом и падает. Чаще всего из-за одной строки: perform_time: Date.now(), которая на повторе возвращает уже другое время.

Песочница не придирается. Она проверяет ровно то, что потом случится в бою: ответ потерялся по дороге, Payme Business отправил тот же запрос ещё раз и ждёт, что вы ответите так же, как в первый раз. Если интеграция к этому не готова, вы получите либо платёж, который висит у Payme на ручном разборе, либо самый неприятный тикет в интернет-магазине: «деньги списались, а заказ неоплачен».

Дальше — как я строю обработчик Merchant API, чтобы повтор любого запроса был безопасен. Код на TypeScript и PostgreSQL, но от языка тут почти ничего не зависит.

Что Payme обещает и чего требует

Пять фактов из документации, на которых держится всё остальное.

  1. Протокол — JSON-RPC 2.0 поверх HTTP POST. Отвечать нужно всегда со статусом 200, даже на ошибку: бизнес-ошибка лежит в поле error тела. Любой другой статус Payme засчитывает как системную ошибку -32400, а не как ваш отказ.

  2. Сумма приходит целым числом в тийинах. 15 000 сумов — это 1500000.

  3. Время — 13-значный timestamp в миллисекундах.

  4. Если ответ на CreateTransaction или PerformTransaction не дошёл, Payme повторяет запрос с теми же параметрами.

  5. Транзакция в состоянии «создана» живёт 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 { return db.tx(async (tx) => { const existing = await tx.oneOrNone( `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 { 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), а не через ===.

Чек-лист перед боем

  1. params.id — ключ идемпотентности, защищённый уникальным индексом, а не проверкой в коде.

  2. Повторный запрос получает сохранённые create_time, perform_time, cancel_time.

  3. Ответ всегда с HTTP 200, ошибки — в теле.

  4. Суммы — целые тийины, никакого float.

  5. Таймаут 43 200 000 мс проверяется в CreateTransaction и PerformTransaction.

  6. Транзакция Payme и статус заказа меняются в одной транзакции базы; всё сетевое — в outbox.

  7. -31007 решается по факту отгрузки, а не по флагу оплаты.

  8. Песочница 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

  • Песочница: https://developer.help.paycom.uz/pesochnitsa/

  • Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html

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

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