Перейти к содержимому

Статусы платежей Bankemes: paid, ожидание и проверка банка

Как различать paid, needs_review и expired_unverified, обрабатывать отмену и позднюю оплату, повторять запросы с тем же Idempotency-Key.

Команда Bankemes · Обновлено

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 означает, что создание не удалось достоверно подтвердить, а не что счёт отсутствует.

Shell
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjs
Node.js
import { 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. Новый случайный ключ после сетевого таймаута может создать новый финансовый запрос. Чтение существующего платежа не требует нового ключа.

Node.js
// 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 не подтверждает реальные деньги; сумма другого заказа не подтверждает этот заказ.

Следующий шаг