Мазмұнға өту

Telegram бот арқылы төлеу: Bankemes сыртқы сілтемесі

Бот серверінде төлем жасау, тапсырысты пайдаланушымен байланыстыру және webhook арқылы растау. Сыртқы checkout пен Telegram Stars айырмашылығы.

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

Бот тапсырысты жүргізеді, төлемді сатушы кассасы қабылдайды

Бұл сценарийде Telegram бот Bankemes бетіне апаратын кәдімгі URL түймесін жібереді. Сервер төлем жасайды, сатып алушы checkout_url ашады, ал backend нәтижені webhook арқылы алады. Ақша ботта сақталмайды: төлем сатушының қосылған кассасы арқылы өтеді. Бұл — сыртқы төлем беті, Telegram-ның кіріктірілген шоты да, Telegram Stars та емес.

Тауарыңызға рұқсат етілетін сценарийді таңдаңыз: мысалы, заттай тапсырыс немесе офлайн қызмет. Telegram ішіндегі цифрлық тауар мен қызметке бөлек ереже қолданылады: Telegram XTR валютасындағы Stars талап етеді. Сыртқы Kaspi сілтемесі бұл механизмді алмастырмайды. Қолдану шегі Telegram құжаттамасында берілген.

Қолданбаның тіркелген ресурсын, қосылған кассаны және сол ресурс токенін дайындаңыз. Bankemes пен бот токендерін тек серверде сақтаңыз. Чатқа, HTML-ге, Mini App-қа және түйме мекенжайына Bearer токенсіз ашық checkout_url ғана беріледі. Төмендегі мысал өзіңіздің bot адаптеріңізді пайдаланады; Bankemes SDK Telegram бот жасамайды және оны орналастырмайды.

Төлем сұрауына дейін тапсырыс жасаңыз

Telegram-нан кіретін деректің шынайылығын бот серверіңіз тексереді. Клиенттің кез келген JSON ішіндегі user id, сома не тапсырыс нөміріне сенуге болмайды; алдымен пайдаланушыны анықтап, содан кейін оның тапсырысына әрекетке рұқсат беріңіз.

Серверде ішкі order_id мәнін Telegram user id, chat id, тауар және сомамен байланыстырыңыз. Пайдаланушы аты өзгеруі мүмкін; чат атауы тапсырыс иесін анықтамайды. Соманы callback_data не сатып алушы хабарламасынан емес, өз каталогыңыздан алыңыз. Пайдаланушы күйін сұрағанда оның Telegram сәйкестігін сақталған тапсырыс иесімен салыстырыңыз.

Алғашқы сұрауға дейін тұрақты Idempotency-Key мәнін тапсырыспен бірге сақтаңыз. payments.create id және checkout_url қайтарады; түймені жібермес бұрын id мәнін тапсырысқа сақтаңыз. Қайта басу мен таймауттан кейінгі қайталау сол тапсырысты, денені және кілтті қолдануы тиіс. metadata үшін арнаның техникалық белгісі жеткілікті; сатып алушының байланысы өз БД-ңызда қалады.

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 });

// order is a server-side record owned by the authenticated Telegram user.
// orders and bot are YOUR database and bot-library adapters, not SDK methods.
export async function sendOrderCheckout(order, orders, bot) {
  const payment = await bankemes.payments.create({
    order_id: order.id,
    amount: order.amountKzt,
    description: order.description,
    metadata: { channel: 'telegram' },
  }, { idempotencyKey: order.bankemesIdempotencyKey });

  await orders.bindPayment(order.id, payment.id);
  await bot.sendMessage(order.chatId, 'Checkout', {
    reply_markup: { inline_keyboard: [
      [{ text: 'Open payment page', url: payment.checkout_url }],
    ] },
  });
}

Нәтижені тексерілген webhook бойынша беріңіз

«Төледім» түймесі тапсырысты беруді емес, күйін оқуды бастай алады. payment.paid оқиғасын бөлек сервер endpoint-інде қабылдаңыз: бастапқы дене қолтаңбасын тексеріп, event.id сақтаңыз және payment_id мәнін API арқылы қайта оқыңыз. Тапсырысты, нақты amount_tiyn сомасын, KZT және livemode мәндерін сервер жазбасымен салыстырыңыз. Содан кейін тапсырысты бір рет растаңыз немесе өнімде көзделген қолжетімділікті ашыңыз.

Растау алушысы тапсырыс пен пайдаланушы арасындағы сақталған байланыстан алынады. Сілтеме басқаға жіберілсе не бот хабарламасы өшірілсе де, байланыс өзгермейді. Төлемді растау мен кейін хабарлама жіберу сервер қайта қосылғанда сақталуы керек: транзакция және кезек қолданыңыз. Telegram хабарлама жіберу қатесі төлем болмады дегенді білдірмейді; төлемді емес, хабарламаны қайталаңыз.

Телефонға Kaspi шоты қажет болса, ол бөлек remoteInvoices.create әдісі: онда checkout_url және bms_test режимі жоқ. Мысалдағы кәдімгі checkout-ты livemode=false тест токенімен тексеріңіз. Шот кестесі автоматты ақша алуды білдірмейді. Толығырақ: қашықтағы шоттар, тұрақты шоттар, webhook тексеру.

Бот сценарийін тексеру

  • Екі рет басу бір төлем жасайды; қайта іске қосу Idempotency-Key мәнін өзгертпейді.
  • Басқа Telegram user id сатып алушы тапсырысын оқымайды және өзгертпейді.
  • Жабылған checkout пен расталмаған expired тапсырысты тексеру күйінде қалдырады.
  • Қайталанған webhook тапсырысты екінші рет бермейді; тест төлемі нақты тапсырысты орындамайды.
  • Хабарлама қатесі жаңа төлем жасамай, хабарламаны қайталайды.

Сұрау шарты: Merchant API. Серверді бастапқы баптау: Quickstart. Белгісіз нәтиже: төлем күйлері.

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

Бұл Telegram-ға кіріктірілген төлем бе?
Жоқ. Бот Bankemes сыртқы бетіне URL түймесін жібереді. Мұнда Telegram sendInvoice, provider_token немесе Stars қолданылмайды; Telegram цифрлық тауар ережелері сақталады.
API токенін Mini App-қа беруге бола ма?
Жоқ. Mini App пайдаланушыны тексеріп, төлем жасайтын backend-іңізге жүгінеді. Клиентке сервер құпиясын емес, checkout_url қайтарыңыз.
Сілтеме басқаға жіберілсе, тапсырыс кімге беріледі?
Серверіңіз төлем жасалғанға дейін тапсырыспен байланыстырған пайдаланушыға. Төлем URL-і тапсырыс иесін ауыстырмауы немесе басқа адамның дерегін ашпауы тиіс.
Бот жауап бермесе, жаңа төлем жасау керек пе?
Алдымен сақталған төлем мен хабарлама кезегін оқыңыз. Telegram жеткізу қатесі төлем болмағанын дәлелдемейді. API нәтижесі белгісіз болса, бұрынғы Idempotency-Key қолданыңыз.

Келесі қадам