Status — итог для интерфейса, state — подробности проверки
У Merchant API есть короткий status и подробный state. pending объединяет несколько стадий: создание, ожидание покупателя и сверку с банком. Отсутствие paid в данный момент ещё не означает окончательный отказ. Храните payment id у заказа и читайте тот же объект: GET /api/v1/payments/{id} для checkout или GET /api/v1/invoices/remote/{id} для удалённого счёта.
- paid / paid: подтверждённая оплата; перед выдачей сверяйте сумму, заказ, валюту и livemode.
- needs_review: результат требует разбора, например из-за неизвестного или противоречивого банковского ответа. Это не подтверждённая неоплата.
- expired / expired_unverified: истёк локальный срок, но банковского доказательства неоплаты нет. Проверка может продолжаться.
- failed_verified, expired_verified, cancelled_verified: закрытый результат соответствующего state. В публичном status суффикса _verified нет.
Проверяйте банковскую определённость там, где поле действительно существует. Webhook содержит data.bank_verified; GET платежа — нет. У payment.expired значение false оставляет результат неопределённым. Одно имя события expired без его данных недостаточно, чтобы отменить уже оплаченный заказ или запретить покупателю доступ.
Поздняя оплата и запрос отмены
Покупатель может оплатить открытый банковский объект, пока ваш интерфейс уже показывает истечение времени. Поздний подтверждённый paid после expired_unverified должен обработаться как оплата. Webhooks приходят повторно и не по порядку: старый expired не должен перезаписывать сохранённый paid. В спорной ситуации перечитайте текущее состояние и отправьте заказ на разбор, а не создавайте второй счёт.
POST /api/v1/payments/{id}/cancel запрашивает отмену checkout. Если QR уже открыт в банке, запрос не превращает его мгновенно в неоплаченный: оплаченный QR остаётся оплаченным. cancel_requested_at показывает запрос, а не окончательный результат. У удалённого счёта дополнительно есть invoice.creation_status: creation_unknown означает, что создание не удалось достоверно подтвердить, а не что счёт отсутствует.
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjsimport { Bankemes } from './bankemes.mjs';
const bankemes = new Bankemes({ token: process.env.BANKEMES_API_TOKEN });
export function paymentDecision(payment) {
if (payment.status === 'paid' && payment.state === 'paid') return 'paid';
if (['failed_verified', 'expired_verified', 'cancelled_verified']
.includes(payment.state)) return 'closed';
return 'checking';
}
// For a remote invoice use bankemes.remoteInvoices.retrieve(paymentId).
export async function refreshCheckout(paymentId) {
const payment = await bankemes.payments.retrieve(paymentId);
return { payment, decision: paymentDecision(payment) };
}Повторяйте запрос, не создавая дубль
Для создания checkout и удалённого счёта сохраняйте Idempotency-Key длиной 8–128 символов вместе с заказом. Повтор с теми же данными возвращает тот же платёж; другой body с тем же ключом получает 409 IDEMPOTENCY_KEY_REUSED. Новый случайный ключ после сетевого таймаута может создать новый финансовый запрос. Чтение существующего платежа не требует нового ключа.
// Save order.id and this key in your database BEFORE sending the request.
// Reuse both after a timeout, process restart, or a duplicate button click.
const payment = await bankemes.payments.create({
order_id: order.id,
amount: order.amountKzt,
description: order.description,
}, { idempotencyKey: order.bankemesIdempotencyKey });
await orders.bindPayment(order.id, payment.id);
// If you lost the response, this token can also look up the same order:
const result = await bankemes.payments.list({ order_id: order.id });Node.js SDK по умолчанию повторяет безопасные запросы при сетевой ошибке, 429 и 5xx не больше двух раз: GET либо POST с Idempotency-Key. Ключ остаётся одинаковым внутри этого вызова. Для повтора после перезапуска приложения передайте свой сохранённый ключ явно. При 429 учитывайте Retry-After. Не переносите этот алгоритм бездумно на все методы: например, отмена не получает автоматического повторения POST в SDK.
Что показать покупателю и оператору
- При pending: «Ожидаем оплату» или «Проверяем результат» согласно state; не обещайте фиксированное время банковского ответа.
- При needs_review и expired_unverified: сохраните заказ, покажите проверку результата, не требуйте повторной оплаты.
- Для разбирательства сохраните payment id, order_id, state/status_reason и request_id ошибки API; секреты и полный телефон в логи не пишите.
- Повторите чтение с паузой и ограничением частоты, а не в бесконечном быстром цикле; выдачу делайте один раз после сверки paid.
Форматы полей и ошибок: Merchant API. Надёжная доставка результата: webhooks. Выставление счета на телефон: удалённые счета.
Вопросы по теме
- expired всегда означает, что покупатель не заплатил?
- Нет. Проверяйте state и, у webhook, bank_verified. expired_unverified не подтверждает неоплату; позднее банковское подтверждение может изменить результат.
- Где bank_verified в GET платежа?
- Этого поля в Merchant payment DTO нет. Оно есть в data платежного webhook. Через GET используйте status и подробный state, не придумывайте отсутствующее поле.
- Можно повторить создание после 202 creation_unknown?
- Не создавайте другой счёт с новым заказом или ключом. Сохраните существующий id, читайте результат; безопасный повтор того же API-запроса использует прежние данные и ключ.
- Достаточно paid, чтобы выдать любой заказ?
- Нужен именно связанный с заказом платёж с верной суммой, валютой и режимом livemode. Тестовый paid не подтверждает реальные деньги; сумма другого заказа не подтверждает этот заказ.