How to connect a crypto payment gateway to your Telegram bot

A Telegram bot can't take crypto by itself: it shows messages and buttons, and a payment gateway does the money part. Your server creates an order with the gateway, the bot sends the buyer a payment link, and the gateway tells your server when the money has arrived, so the bot knows it can deliver. Before you choose a gateway, check what the bot sells: Telegram leaves physical goods and services to outside payment providers, but digital goods sold inside Telegram have to be paid in Telegram Stars.

Start with what your bot sells

Telegram's rules for bots are platform terms rather than law, but your bot lives by them. As of October 2026, Telegram's Bot Platform Developer Terms split everything a bot can sell into two groups:

• Physical goods and services. Under section 6.1, Telegram does not process these payments, and the developer works directly with third-party payment providers. A bot that sells coffee beans with delivery is free to choose its provider, and a crypto gateway can be that provider.
• Digital goods and services. Under section 6.2, every such transaction must go through Telegram Stars only, the currency Telegram sells inside its apps. Telegram's payments documentation adds that this holds for sales inside Telegram whatever other websites you also sell through. An e-book sold in the bot belongs here.

This article is about the first group. If your bot sells digital goods, the payment runs through Telegram's own invoice in Stars, with the currency code XTR and no payment-provider token, and a crypto gateway has no role in that flow. How Stars compare with payment links and bot checkouts for a seller is laid out in how to accept crypto payments in Telegram with Stars, payment links and bots.

What happens between the "Buy" button and delivery

Take a bot that sells roasted coffee: a 1 kg bag costs 40 USDT, delivery included. Here is what happens when a buyer pays for it in crypto:

1. The buyer taps "Buy" in the bot. The bot passes the choice to your server: which bag, and which Telegram user is buying it.
2. Your server creates an order with the gateway. It sends the gateway's API the amount and currency, 40 USDT, along with the buyer's Telegram user ID and your own order number, so the payment can find its way back to the right chat.
3. The bot sends the buyer a payment link. The gateway answers with a link to its payment page, and the bot sends it as an ordinary message with a button. Telegram's built-in invoice isn't used here.
4. The buyer pays from their own wallet. The payment page shows the amount, the network and the address. On a phone, the buyer copies the address and amount into a wallet app, because the phone can't scan a QR code shown on its own screen.
5. The gateway sends your server a webhook. A webhook is a message from the gateway's server to yours, along the lines of "order 1042 is paid". It arrives by itself, so nobody has to keep asking.
6. Your server checks the webhook, and the bot delivers. The server confirms the message really came from the gateway, marks the order paid, and the bot writes to the buyer by their user ID: "Payment received, your coffee ships tomorrow."

The bot never decides that an order is paid. That decision lives on your server and rests only on the gateway's notification, never on what the buyer says in the chat.

At CryptumPay, step two is a single API call from your server with the amount and currency. The order number it returns gives a link to CryptumPay's payment page, and the bot can send that link in the chat as it is, with no widget to embed. The buyer needs no CryptumPay account: they open the link and pay from their own wallet.

Your own identifiers can travel with the order:

• Your user ID. It tells you which of your customers the order belongs to.
• Your internal order number. It matches the payment to the order in your own system.
• A free-form data string. It holds anything else you want attached to the order.

What makes a gateway fit a bot

Which payment system is best for a Telegram bot? The one that passes a few bot-specific checks for your setup:

• Orders created by API, with your data attached. If an order can't carry the buyer's Telegram user ID or your order number, a webhook arrives and you don't know which chat to answer.
• A payment page that works from a link. The buyer should open it straight from the chat and pay without signing up anywhere.
• Signed webhooks that get retried. A signature lets your server tell a real notification from a fake one, and retries cover the minutes your server was down.
• A plainly named "safe to deliver" status. The documentation should say in so many words which status means the money is in.
• A way to call it from your language. You need either an SDK for the language your bot is written in or a request-signing method described clearly enough to code yourself.
• The coins and networks your buyers already hold. A gateway that takes Bitcoin but not USDT, or the other way round, loses every buyer who holds the other one.
• The fee and who pays it. Look at the percentage per successful payment and at whether you can pass it on to the buyer.

Measured against this list, CryptumPay charges 1% per successful payment, down to 0.5% at higher volumes, and the fee can be passed on to the buyer. Its ready-made SDK is for Node.js; for any other language the request-signing algorithm is described step by step, so a server in Python or anything else calls the API directly. CryptumPay rejects a request older than one minute, so the server clock has to be in sync.

A bot is only one front end for a gateway, and the same API questions come up for a website or an app. A longer list for any integration is in what to check in a crypto payment API before you integrate it.

The webhook handler decides whether you lose money

Most of the risk in a bot payment sits in a few dozen lines on your server: the code that receives the gateway's webhook. Four rules keep that code safe:

• Check the signature before anything else. Without the check, anyone who learns the webhook address can send your server "order 1042 is paid" and get the coffee for free.
• Drop duplicates. The same event can arrive twice, so store each event's key and act on it once, or the bot ships two bags for one payment.
• Reply fast, then do the work. Answer with a success code as soon as the event is stored; a handler that replies only after finishing everything else can time out, and the gateway sends the event again.
• Deliver on the paid status only. A transfer spotted on the blockchain isn't money in your account yet, and a buyer returning from the payment page or tapping an "I've paid" button proves nothing.

CryptumPay sends a webhook at each step of a payment, from the moment the order is created to the moment the payment is finished. The webhook address has to be HTTPS with a valid certificate. Every webhook is signed in the X-Signature header, and a repeated event carries the same X-IDMP-Key header, which is how your server spots duplicates.

On any reply other than 2xx, CryptumPay retries, up to 12 attempts over about an hour. Its documentation names the moment to deliver outright: order status Paid (funds credited) or Crediting (crediting in progress, payment definitely received). Orders with the status In progress or Under review are not fulfilled, and the buyer landing on the success page doesn't count as payment: the status is checked on the server.

These rules are the minimum, and a real handler also has to cope with notifications that arrive late or out of order. If you are writing it yourself, go through how to process crypto payment webhooks and confirmations safely.

What the bot can tell the buyer while the payment goes through

A card payment is over in seconds, but a crypto payment has a pause between sending and confirmation. A buyer staring at a silent chat starts to worry, sends the money twice or writes to support. Webhooks for each step let the bot talk the buyer through it:

• Order created. The bot sends the link together with the exact amount and network: "Pay 40 USDT on TRON."
• Transfer spotted. The bot writes: "We can see your payment and are waiting for the network to confirm it."
• Paid. The bot confirms the payment and delivers, or says when the goods will ship.
• Anything that doesn't match the order. The bot says a person is checking the payment and holds the delivery until someone does.

How long the pause lasts depends on the coin and the network: a USDT transfer on a fast network can be confirmed in about a minute, while slower networks keep the buyer waiting longer. Whatever the coin, the bot should say roughly how long to expect before the buyer pays, not after.

The payment that doesn't match its order is the one to plan for in advance. A buyer whose exchange kept a withdrawal fee sends 39.5 USDT instead of 40, and someone has to decide whether the bag ships. Write the rule down before it happens, using how a business should handle crypto underpayments, overpayments and mistaken transfers.

Writing the payment part in Python or another language

The bot code and the payment code are separate jobs. A bot library such as python-telegram-bot or aiogram handles the chat side, and the gateway doesn't care which one you use.

Talking to the gateway takes two pieces of ordinary web code:

• A signed request that creates the order. Your server sends it when the buyer taps "Buy", and the answer carries the payment link the bot will send.
• A web endpoint that receives webhooks. It needs a public HTTPS address even if the bot itself polls Telegram for updates, because the gateway has to reach your server from outside.

Both can run in the same app on the same small server. If the gateway ships an SDK in your language, use it; if it doesn't, its documentation should describe request signing step by step, and you write that one function yourself.

Keep the server clock synced with an internet time service. If the gateway checks how old each signed request is, a clock that drifts by a minute makes valid requests look stale.

What the ready-made bots on GitHub actually do

Search GitHub for a Telegram crypto payment bot and you'll find two kinds of projects:

• Wrappers around a gateway's API. They save you writing the order and webhook code yourself, while the gateway still handles the payment and charges its fee.
• Self-hosted bots that watch a wallet. They check the blockchain themselves, so there's no gateway fee, but every job a gateway does lands on you, down to keeping the server that holds the keys safe.

Before you run either kind, check three things:

• The payment check. Read the code that marks an order paid and hold it against the four webhook rules above.
• The last update. A project nobody has touched in years may not match the current API of the gateway or the network it relies on.
• The keys. Never paste a private key or a seed phrase, the backup words for a wallet, into code you haven't read.

A self-hosted bot looks free, but the work and the risk move to you. Whether that pays off at your sales volume is a separate decision, weighed in should you self-host a crypto payment gateway or plug in a hosted one.

In short

A crypto gateway fits a Telegram bot that sells physical goods or services, while digital goods sold inside Telegram go through Stars. The bot is the shop window: your server creates the order, the bot sends the link, and only a signed webhook with a paid status lets the bot deliver. Pick the gateway that passes the bot-specific checks above, and spend the most care on the webhook handler, because that is where the money is kept or lost.

Other questions about bot payments

Can't I just take crypto through Telegram's own Payments API?

Telegram's Bot Payments API covers two cases: Stars for digital goods, and payments for physical goods through third-party providers you connect to the bot. A crypto gateway doesn't need that API at all. The bot sends an ordinary message with a link button, and the gateway's payment page and webhooks do the rest.

What if my shop is a Mini App rather than a chat bot?

A Mini App, a web app that opens inside Telegram, falls under the same split between physical and digital goods. On top of that, section 7 of Telegram's developer terms ties any cryptocurrency features of a Mini App to the TON blockchain. What that means for taking USDT is answered in whether a Telegram Mini App can take USDT or only Stars.

Can my bot take Bitcoin, not just USDT?

Yes, if the gateway you choose supports Bitcoin, so check its list of coins before you connect it. Bitcoin is slower: a new block arrives roughly every ten minutes on average, and depending on how many confirmations the gateway waits for, the buyer may wait from about ten minutes to an hour. A bot that takes Bitcoin should warn the buyer about the wait before they pay, so they don't send the coins twice.

Can a bot sell access to a private channel for crypto?

No: access to a channel is a digital service, and under section 6.2 of Telegram's developer terms a bot sells digital goods and services for Stars only. Telegram's payments FAQ answers the crypto question directly, and the answer is no. Taking payment on your own website doesn't change that either: Telegram requires Stars for digital sales inside its apps regardless of any sites, services or payment providers you have set up outside Telegram. The terms split sales by the kind of goods, physical goods and services in section 6.1 and digital ones in section 6.2.

Is it legal for my business to take crypto through a bot?

Telegram's terms only say what the platform allows; whether a business may accept crypto at all depends on the law of the country it operates in. The terms do say one thing about money: under section 6.4, taxes on income received through a bot are the developer's own responsibility. The question itself is answered in whether it is legal for a business to accept crypto payments.

This article is not legal or tax advice.