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<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), а не через ===.

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

  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 и другой ответ на повтор. И ночная сверка, которая ловит то, что пропустили оба провайдера.

Источники

ссылка на оригинал статьи https://habr.com/ru/articles/1109614/