Status is the public result; state explains verification
The Merchant API returns a short status and a detailed state. pending covers creation, waiting for the buyer and bank reconciliation. Not being paid yet does not establish final failure. Store the payment id on your order and read the same object: GET /api/v1/payments/{id} for checkout, or GET /api/v1/invoices/remote/{id} for a remote invoice.
- paid / paid: confirmed payment; verify amount, order, currency and livemode before fulfillment.
- needs_review: the outcome needs review, for example after an unknown or contradictory bank response. It does not confirm non-payment.
- expired / expired_unverified: the local deadline passed without bank proof of non-payment. Verification may continue.
- failed_verified, expired_verified, cancelled_verified: a closed result for the corresponding state. The public status omits the _verified suffix.
Check bank verification where the field actually exists. Webhooks include data.bank_verified; payment GET responses do not. For payment.expired, false leaves the result unresolved. The expired event name alone is insufficient to cancel an already paid order or revoke a buyer’s access.
Late payment and cancellation requests
The buyer can pay an open bank object after your interface has timed out. A late confirmed paid after expired_unverified must still be processed as payment. Webhooks can repeat and arrive out of order: an older expired must not overwrite a recorded paid. When evidence conflicts, re-read the current state and send the order to review instead of creating another invoice.
POST /api/v1/payments/{id}/cancel requests checkout cancellation. If a QR is already open at the bank, the request does not instantly make it unpaid: a paid QR stays paid. cancel_requested_at records a request, not a final outcome. Remote invoices also include invoice.creation_status: creation_unknown means creation was not conclusively confirmed, not that no invoice exists.
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) };
}Retry the request without creating a duplicate
Persist an 8–128-character Idempotency-Key with the order when creating checkout payments or remote invoices. A retry with the same data returns the same payment; a different body with the same key returns 409 IDEMPOTENCY_KEY_REUSED. Generating a new random key after a network timeout can create another financial request. Reading an existing payment does not need a new key.
// 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 });By default the Node.js SDK retries safe requests up to twice after network errors, 429 or 5xx: GET requests, or POST requests carrying an Idempotency-Key. That key stays unchanged within the call. For a retry after an application restart, explicitly supply your persisted key. Honor Retry-After on 429. Do not generalize this to every method: the SDK does not automatically retry cancellation POSTs.
What buyers and operators should see
- For pending, show “Awaiting payment” or “Verifying payment” according to state; promise no fixed bank response time.
- For needs_review and expired_unverified, retain the order, show verification in progress, and do not demand another payment.
- For investigation, keep payment id, order_id, state/status_reason and the API error request_id; keep secrets and full phones out of logs.
- Re-read with delays and rate limits, rather than a tight infinite loop; fulfill once after verifying paid.
Field and error formats: Merchant API. Reliable outcome delivery: webhooks. Invoicing a buyer’s phone: remote invoices.
Questions about this topic
- Does expired always mean the buyer did not pay?
- No. Check state and, for webhooks, bank_verified. expired_unverified does not confirm non-payment; later bank verification can change the result.
- Where is bank_verified in a payment GET response?
- The Merchant payment DTO has no such field. It is in payment webhook data. For GET, use status and the detailed state instead of assuming the field exists.
- May I create another invoice after 202 creation_unknown?
- Do not create a different invoice with a new order or key. Retain the existing id and read its result; a safe retry of the same API request uses the original data and key.
- Is paid enough to fulfill any order?
- It must be the payment bound to that order, with the correct amount, currency and livemode. Test paid does not confirm real money; another order’s amount does not confirm this order.