Payments in a Telegram Bot: Taking Money Step by Step

Payments are where mistakes cost money and surface late. Here are the options and the mandatory minimum.

The options

Telegram built-in payments. You connect a payment provider and the user pays without leaving the messenger. The shortest path for the user and therefore the highest completion rate. Requires a connected provider and works on its terms.

Telegram Stars. The platform’s internal currency. For some digital goods and services inside the messenger it is the required method under platform rules. Covered in Stars.

An external payment page. The bot hands over a link, payment happens on the provider side, confirmation arrives by webhook. Maximum freedom in logic, discounts and accounting; one step longer for the user.

How to choose: digital goods inside the messenger means Stars; physical goods or services mean built-in payments or an external page; complex logic and accounting mean an external page.

The flow that works

The order of steps, and violating it creates most of the problems:

1. Create the order in your database with a pending status, before showing an invoice.
2. Issue the invoice carrying the order identifier.
3. Wait for confirmation from the payment system. This is a separate event, not a button press.
4. Check that the order is not already paid. If it is, exit doing nothing.
5. Mark it paid and deliver.
6. Tell the user.

The critical part is step 4. Without it, a repeated confirmation delivers the product a second time.

Payment confirmation

The key idea: pressing the pay button is not payment. The fact is the confirmation from the payment system.

What follows:

Confirmation is asynchronous. The user may close the chat and confirmation arrives a minute later. Delivery logic must not depend on the user being in the conversation.

Confirmation can arrive twice. Normal retry behaviour, not a fault. Hence the idempotency requirement.

Confirmation must be verified. Data arriving from outside has to be authenticated by whatever mechanism the provider offers. Taking the request body at its word is not acceptable.

Amount and currency are checked against the order you recorded at creation time, not against what arrived.

Idempotency

In full: processing the same payment again must change nothing.

How that is done in practice:

• The order has a stable identifier passed to the payment system and returned in the confirmation.
• Before delivery, the current order status is checked. Paid means exit.
• The status change and the delivery happen in one transaction, so you never end up with “status updated, product not delivered”.

The same principle in general terms is on the blog: idempotent pipelines.

What else to plan for

• Refunds. At minimum a manual procedure and clarity about what happens to delivered access.
• Abandoned orders. The user started and never paid. Those should expire rather than linger forever.
• Logs of every payment event. Resolving a dispute needs history, not memory.
• Environment separation. Test payments and live payments must not share a database.
• Accounting. Find out what your bookkeeping needs before launch, not after the first month of sales.

What this looks like on a real project: a course sales bot. On Stars: its own article. The overview is in the Telegram bots guide.