Skip to content

Payments from a Telegram bot: external Bankemes checkout

Create payments on a bot server, map orders to users, and confirm fulfillment through webhooks. External checkout and its distinction from Telegram Stars.

Bankemes team · Updated

The bot manages the order; the seller’s cashier receives payment

In this flow, a Telegram bot sends an ordinary URL button to Bankemes. Your server creates a payment, the buyer opens checkout_url, and your backend receives the outcome through a webhook. The bot does not hold money: payment goes through the seller’s connected cashier. This is external checkout, not a native Telegram invoice or Telegram Stars.

Choose a flow permitted for your product, such as a physical order or offline service. Digital goods and services sold inside Telegram have separate rules: Telegram requires Stars in XTR. An external Kaspi link does not replace that mechanism. See the Telegram documentation for applicability.

Prepare a registered application resource, connected cashier, and token for that resource. Keep both the Bankemes token and bot token on your server. Chat, HTML, a Mini App, and the button URL receive only the public checkout_url, without a Bearer token. The example uses your existing bot adapter; the Bankemes SDK neither creates nor hosts a Telegram bot.

Create the order before requesting a payment

Your bot server verifies incoming Telegram data. Do not trust a user id, amount or order number from arbitrary client JSON; establish the user’s identity before authorizing actions on their order.

On your server, map the internal order_id to the Telegram user id, chat id, product and amount. A username can change; a chat title does not establish order ownership. Calculate the price from your catalog, not callback_data or a buyer message. When someone requests status, verify their Telegram identity against the saved order owner.

Persist a stable Idempotency-Key with the order before the first request. payments.create returns id and checkout_url; bind the id to your order before sending the button. A duplicate click or timeout retry must use the same order, request body and key. A technical channel label is enough metadata; the buyer mapping stays in your database.

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

Fulfill from a verified webhook

An “I have paid” button may trigger a status check, never fulfillment by itself. Receive payment.paid at a separate server endpoint: verify the raw-body signature, persist event.id, and re-read payment_id through the API. Match the order, exact amount_tiyn, KZT and livemode against your server record. Then confirm the order or enable the appropriate product entitlement exactly once.

Choose the confirmation recipient from the saved order-to-user mapping. Forwarding the link or deleting the bot message does not change it. Payment confirmation and the subsequent message must survive server restarts: use a transaction and a queue. A Telegram notification error does not undo payment; retry the message, not the charge.

A Kaspi invoice sent to a phone uses the separate remoteInvoices.create method: it has no checkout_url or bms_test mode. Test the ordinary checkout shown above with a test token and livemode=false. An invoice schedule is not an automatic debit. See remote invoices, recurring invoices, and webhook verification.

Test the bot flow

  • A double click creates one payment; restarting preserves the Idempotency-Key.
  • Another Telegram user id cannot read or modify the buyer’s order.
  • Closing checkout or unverified expiry leaves the order under verification.
  • A duplicate webhook does not fulfill twice; test payment never fulfills a real order.
  • A messaging failure retries the notification without creating another payment.

Request contract: Merchant API. Initial server setup: Quickstart. Uncertain outcomes: payment statuses.

Questions about this topic

Is this native Telegram payment?
No. The bot sends a URL button to external Bankemes checkout. This flow does not use Telegram sendInvoice, provider_token or Stars; Telegram’s digital-goods rules still apply.
Can I put an API token in a Mini App?
No. The Mini App calls your backend, which authenticates the user and creates the payment. Return checkout_url to the client, never the server secret.
Who receives the order if the link is forwarded?
The user your server bound to the order before creating the payment. A checkout URL must not reassign the order or expose another buyer’s data.
Should I create another payment if the bot sends no reply?
First check the saved payment and message queue. Telegram delivery failure does not prove non-payment. Reuse the existing Idempotency-Key when the API outcome is uncertain.

Next step