Payments

How payments work in Telegram

Telegram allows bots to accept payments directly within the chat. The user sees an invoice, taps "Pay," and enters their card details (or pays using Telegram Stars)—all without leaving the messenger app.

To enable payments, you need to:

Connect a payment provider (Sberbank, YooKassa, Stripe, etc.) or use Telegram Stars.
Add the "Invoice" block to the scenario and configure the product.

Connecting a payment provider

Obtain a payment token from your chosen provider via @BotFather → Payments.
In the builder, click "Payments" in the header.
Select the provider from the list and enter the token you obtained.
Specify the mode: LIVE (real payments) or TEST (test payments).
Save the connection.

A single connection is used for all bots in the account.

"Invoice" block

The "Invoice" block sends a payment invoice to the user.

Product source

Mode	Description
Manual	Enter the name, description, photo, currency, and price details directly in the block. Upon the first send, the product is automatically saved to the catalog.
From catalog	Select a product from the bot's catalog. All data is populated automatically.
From variable	Specify a variable containing the product ID; the product is determined dynamically at runtime. Useful for catalogs where the user selects the product.

Payment provider

Mode	Description
Token	Paste the payment token from @BotFather directly. Leave blank for Telegram Stars (XTR) payments.
Provider	Select from the connected providers — the token will be inserted automatically.

Invoice settings

Setting	Description
Success node	Where to navigate after successful payment
Error node	Where to navigate in case of error or timeout
Result variable	Variable name for storing payment data (default: successful)
Timeout	Duration (in minutes) the invoice remains active
Request name / phone / email	Additional data from the payer

Successful payment variables

After a successful payment, transaction data is stored in the result variable. If the variable is named successful:

Variable	Value
`{{successful.currency}}`	Currency code (e.g., RUB)
`{{successful.total_amount}}`	Amount in kopecks/cents
`{{successful.telegram_payment_charge_id}}`	Telegram transaction ID
`{{successful.provider_payment_charge_id}}`	Provider transaction ID
`{{successful.order_info.name}}`	Payer's name
`{{successful.order_info.phone_number}}`	Payer's phone number
`{{successful.order_info.email}}`	Payer's email

Telegram Stars (XTR)

Telegram Stars is Telegram's internal currency. Users pay with Stars without linking a bank card. To accept Stars:

Leave the provider token field blank (in "Token" mode).
Set the currency to XTR.
Prices are set in Stars (using whole numbers).

Product Catalog

Go to "Products" in the builder's header to manage your catalog:

Create products with a name, description, photo, price, and currency.
Products are available in the "Invoice" block → "From Catalog" mode.
Statistics are tracked for each product: number of orders and total revenue.

Tips

Start development in TEST mode — test payments are not included in statistics and are not actually processed.
After a successful payment, use payment variables to send the user a confirmation containing order details.
Use an error node to prompt the user to try again or choose a different payment method.

External Payment Providers

In addition to the built-in Telegram Payments, you can accept payments via external payment systems (Tinkoff, FreeKassa, YooKassa, Payeer, Cryptomus, Stripe, PayPal, Robokassa, CryptoBot, WebMoney, etc.). The user clicks a button in the chat, proceeds to the payment page, and—upon confirmation—the bot automatically executes the specified command.

Connecting an External Provider

In the builder, click "Payments" in the header.
Go to the "External Providers" tab.
Click "Connect" next to the desired provider.
Enter the required details (API keys, merchant IDs, etc.) — the specific fields depend on the provider. 5. Select LIVE (real payments) or TEST mode.
Save the connection.

Once connected, you will see a Webhook URL—you need to enter this in your payment provider's dashboard to receive payment notifications.

"Payment Link" Button

To accept payments via an external provider, add an inline button with the 💳 Payment Link action to any block containing a keyboard.

Setting	Description
Provider	Select from the list of connected external providers
Amount	Payment amount. Supports variables: `{{order_sum}}`
Currency	Payment currency (RUB, USD, EUR, etc.)
Description	Payment description text. Supports variables
Success command	Node to execute after a successful payment
Error command	Node to execute in case of an error (optional)
Variable prefix	Name of the result variable group (default: payment)

When the user clicks the button, they receive a URL and proceed to the payment page. Once the provider confirms the payment, the bot automatically sends the message defined in the success command.

External Payment Variables

Following a successful or failed payment, payment data is recorded in variables. If the variable prefix is payment:

Variable	Value
`{{payment.id}}`	Internal payment ID
`{{payment.amount}}`	Amount
`{{payment.currency}}`	Currency
`{{payment.status}}`	Status: paid, failed, pending
`{{payment.order_id}}`	Order ID
`{{payment.paid_at}}`	Payment date/time
`{{payment.description}}`	Payment description

Canvas Visualization

On the "Payment Link" button builder canvas, visual connections are created:

Green arrow (💳 … ✓) — path for successful payment
Yellow arrow (💳 … ✗) — path in case of an error

Tips for External Providers

Ensure the Webhook URL is correctly specified in the provider's dashboard.
Use TEST mode for debugging — test payments are not actually processed.
After a successful payment, use {{payment.*}} variables to generate a receipt or confirmation.
Add an error-handling action to notify the user of the failed attempt.

Payment History

The "Payments" tab in the builder (found under the "More" menu in the header—look for the icon showing a banknote and a downward arrow) displays all payments initiated via the "💳 Payment Link" button, regardless of the provider or status. This serves as a log of transactions actually processed through external payment systems. ### Top-level cards

The tab header displays four metrics calculated based solely on completed payments—regardless of the selected status filter:

Card	What it shows
Total payments	Number of successfully completed payments, accounting for active filters (excluding status)
Total amount	Total payment volume for those same payments
Payments today	Number of payments completed today
Amount today	Total payment volume for today

Table Columns

Column	Description
Dates	Payment creation date and payment date (if paid) — each on a separate line
Order ID	Unique order ID generated by the payment provider; below: internal `#id` and description
User	Avatar, Telegram first/last name, language flag, Premium star, clickable `@username`, and `#chat_id`
Amount	`amount` + currency (uppercase)
Provider	Logo and name of the payment system from "Payment Providers"
Payload	Additional data passed with the payment (first 3 keys; full JSON on hover)
Status	Color-coded badge: paid / pending / failed / expired / refunded

Filters

The same filter types available in "Subscriptions" apply here, affecting both the table and the metrics at the top (except for the status filter, which applies only to the table):

Bot — current bot, all bots owned by the user, or a specific one from the list.
ID — exact internal payment ID.
Order ID — search by partial order ID.
Chat ID — exact user chat_id.
Last Name / Username — search by Telegram user fields.
Amount (min/max) — range based on amount.
Currency — RUB, USD, EUR, etc.
Created (min/max) — range based on payment creation date.
Paid (min/max) — range based on payment date.
Status — pending, paid, failed, expired, refunded.
Sorting — by ID, amount, creation date, or payment date; ascending or descending. When sorting by paid_at, unpaid payments always appear at the end.