В песочнице 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
Комментарии 0