Accept Payments in Telegram: Stars and Card Providers

Guide

1. 1

   Two rails: Stars and cards

   The Payment block sends a real Telegram invoice from inside a flow. The person pays without leaving the chat, and the flow continues down one of the block's two exits: Paid or Not paid.

   

   Each block runs on one of two rails:

   • Telegram Stars — Telegram's own in-app currency, currency code XTR. No provider, no keys, no webhooks. The price is a whole number of Stars. Telegram expects Stars for digital goods sold inside Telegram.
   • Card — a real-money charge through a payment provider such as Stripe, connected to your bot in @BotFather. One setup, then every card block on that bot uses it.
2. 2

   Add the block

   Press the + button on the canvas and pick Payment. The same menu appears if you drag a connection out of a block's exit and drop it on empty canvas — then the new block arrives already wired.

   

   On the canvas the node shows the product title, a Stars or Card badge and the price, so a flow's price list is readable without opening anything.

3. 3

   Telegram Stars need no setup

   Click the block and the editor opens on the right. Payment method sits at the top — leave it on Telegram Stars.

   

   Four fields matter:

   • Product title — up to 32 characters. It is the headline on the invoice.
   • Description — up to 255 characters. What the buyer gets.
   • Price (Stars) — a whole number, at least 1.
   • Wait for payment, seconds (optional) — how long the flow holds the invoice open. Leave it empty to wait indefinitely.

   Currency is locked to XTR here; there is nothing to type.

   One limit to plan around: title, description and price are literal text. Variables are not filled in inside them, so one block sells one thing at one price. Two prices means two blocks.

4. 4

   Cards need a provider token

   Switch Payment method to Card and the editor spells out the one-time setup.

   

   Price changes meaning on this rail: it is the smallest unit of the currency, so 999 with Currency USD is $9.99.

   The token belongs to the bot, not to the block. In Telegram: @BotFather → /mybots → your bot → Payments → connect a provider. Then, in FlowCastle, open Settings → Bots → your bot and paste it into Card payments (provider token).

   

   The tag flips from Not connected to Connected once you save, and the bot restarts to pick the token up. Stars ignore all of this.

5. 5

   Wire both exits

   Paid is the happy path: send the file, hand over the link, add a tag, subscribe the buyer to a sequence.

   Not paid runs when the person sends a message instead of paying. Tapping a button does not count as giving up — the flow keeps waiting for the invoice.

   Worth knowing: nothing fires on its own when the timer runs out. The timeout only ends the wait; it does not run the Not paid branch by itself. So do not write "we'll remind you in 15 minutes" on that branch — write it as an answer to the message the person just sent.

6. 6

   Record the sale

   The Payment block collects money. It does not write an order. To get the sale onto the Orders page and into the contact's card, put an Action block on the Paid exit with a Create Order action (amount and currency). That block is also the natural home for Add tag and a Notify by tag message to yourself.

7. 7

   Test before you deploy

   Press Test and walk the flow. Nobody is charged: the test chat shows a mock invoice headed Test mode — simulated payment with a Pay … (test) button. Tap it to walk the Paid branch; type a message instead to walk Not paid. Then publish it — Test and Deploy Your Bot covers the rest.

8. 8

   What the block will not do

   • No subscriptions. One-time charges only. There is no recurring billing in the Payment block today, on either rail.
   • No refunds. FlowCastle has no refund action or button. Card refunds happen in your provider's dashboard.
   • Not in Operations. A scheduled operation has nobody to invoice, so payment blocks only run in chat flows.
9. 9

   When to use Stripe or YooKassa instead

   Charging someone inside the chat is this block's job — do not install a module for that. Reach for the Stripe or YooKassa modules when the money is collected somewhere else: a hosted checkout page, a card subscription, or a webhook telling your bot that an invoice raised outside Telegram was paid. Modules: Connect Sheets, AI, Payments and More covers installing them.

10. 10

    Start from the template

    Sell with Telegram Stars is this article as a working flow: a product card, a 100-Star invoice, delivery on payment, and a retry loop on the other exit. Install it, then change the price and the copy.

11. 11

    Next up

    Your bot can take money. Now let it answer in its own words: The AI Chat Agent Node.