Мазмұнға өту

Bankemes төлем күйлері: paid, күту және банк тексеруі

paid, needs_review және expired_unverified күйлерін ажырату, бас тарту мен кеш төлемді өңдеу, сұрауларды сол Idempotency-Key арқылы қайталау.

Bankemes командасы · Жаңартылды

Status — интерфейс нәтижесі, state — тексеру мәліметі

Merchant API қысқа status және толық state береді. pending бірнеше кезеңді біріктіреді: жасау, сатып алушыны күту және банкпен салыстыру. Қазір paid болмауы түпкілікті бас тартуды білдірмейді. Төлем id мәнін тапсырысқа сақтап, сол нысанды оқыңыз: checkout үшін GET /api/v1/payments/{id}, қашықтағы шот үшін 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 атауының өзі төленген тапсырысты жоюға немесе сатып алушының қолжетімділігін жабуға жеткіліксіз.

Кеш төлем және бас тарту сұрауы

Интерфейс уақыты өтті деп көрсетсе де, сатып алушы ашық банк нысанын төлеуі мүмкін. expired_unverified күйінен кейін келген расталған paid төлем ретінде өңделуі керек. 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 пен қашықтағы шот жасау үшін 8–128 таңбалы Idempotency-Key мәнін тапсырыспен бірге сақтаңыз. Сол дерекпен қайталау сол төлемді қайтарады; денесі басқа болса, сол кілтке 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 немесе Idempotency-Key бар POST. Бір шақыру ішінде кілт өзгермейді. Қолданба қайта іске қосылғаннан кейін қайталау үшін сақталған кілтті нақты беріңіз. 429 кезінде Retry-After ескеріңіз. Бұл тәсілді барлық әдіске бірдей қолданбаңыз: мысалы, SDK бас тартудың POST сұрауын автоматты қайталамайды.

Сатып алушы мен операторға не көрсету керек

  • pending кезінде state бойынша «Төлем күтілуде» немесе «Нәтиже тексерілуде» көрсетіңіз; банк жауабының нақты уақытын уәде етпеңіз.
  • needs_review және expired_unverified кезінде тапсырысты сақтап, нәтиже тексеріліп жатқанын көрсетіңіз, қайта төлеуді талап етпеңіз.
  • Тексеру үшін payment id, order_id, state/status_reason және API қатесінің request_id мәндерін сақтаңыз; құпия мен толық телефонды логқа жазбаңыз.
  • Оқуды үзіліспен және жиілік шектеуімен қайталаңыз; шексіз жылдам цикл жасамаңыз. paid расталған соң тапсырысты бір рет орындаңыз.

Өріс пен қате пішімдері: Merchant API. Нәтижені сенімді жеткізу: webhooks. Телефонға шот жіберу: қашықтағы шоттар.

Тақырып бойынша сұрақтар

expired сатып алушы төлемеді дегенді білдіре ме?
Жоқ. state мәнін және webhook ішіндегі bank_verified тексеріңіз. expired_unverified төленбегенін растамайды; кейінгі банк растауы нәтижені өзгертуі мүмкін.
GET төлем жауабында bank_verified қайда?
Merchant payment DTO ішінде бұл өріс жоқ. Ол төлем webhook-ының data бөлігінде бар. GET кезінде status пен толық state қолданыңыз; жоқ өріске сүйенбеңіз.
202 creation_unknown кейін жасауды қайталауға бола ма?
Жаңа тапсырыс не кілтпен басқа шот жасамаңыз. Бар id мәнін сақтап, нәтижені оқыңыз; сол API сұрауын қауіпсіз қайталау бұрынғы дерек пен кілтті пайдаланады.
paid кез келген тапсырысты беруге жеткілікті ме?
Тапсырысқа байланыстырылған, сомасы, валютасы және livemode режимі дұрыс төлем қажет. Тест paid нақты ақшаны растамайды; басқа тапсырыс сомасы осы тапсырысты растамайды.

Келесі қадам