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

Источники