Telegram Stars Refunds, the 21-Day Hold and Payout Rules Every Seller Should Know

The 21-day holding period

When a user pays you in Stars, the amount appears in your balance immediately but is not withdrawable for 21 days. The rule is set by Telegram and applies to all sellers: bots, channels, Mini Apps and payment platforms. It exists for three reasons:

• Refund window: gives sellers and Telegram time to process legitimate refunds before funds leave the system.
• Fraud prevention: stolen cards and abusive purchases are usually detected within this window.
• App store compliance: in-app purchases can be reversed by Apple or Google; the hold aligns Stars payouts with that reality.

Telegram Stars Payment Platform reflects the rule in your ledger: each payment carries an availability date, your dashboard shows a *maturing* balance and an *available* balance, and withdrawal requests can only draw on the available part.

How to think about cash flow

The hold is not a one-time delay, it is a pipeline. If you sell every day, after three weeks you also unlock funds every day. The practical consequences:

1. Expect your first payout about three weeks after your first sale.
2. From then on, withdraw on a fixed schedule (weekly or monthly) rather than chasing each matured payment.
3. Keep prices and campaigns steady; spiky sales mean spiky availability.
4. If you need working capital for the first month, treat Stars as receivables, not cash.

Refunds: how they work

Any Stars payment can be refunded in full by the seller. Through the Bot API the call is refundStarPayment(user_id, telegram_payment_charge_id); on a payment platform it is a button in the dashboard. Key facts:

• The buyer receives the Stars back in their Telegram balance, not dollars. They can spend them elsewhere.
• Refunds are full (the entire payment); partial refunds are not supported.
• You can refund after delivery; it is a seller decision, so publish a refund policy.
• Refunded Stars are deducted from your balance, maturing first if they had not yet matured.
• Telegram may also refund on its own in cases of fraud or store-level chargebacks, which is exactly what the 21-day hold is for.

Subscriptions and refunds

Stars subscriptions renew every 30 days. Users can cancel at any time from their Telegram settings; the current period stays active until it expires. Sellers can cancel or restore a subscription with editUserStarSubscription. A refund of a subscription payment follows the same rules as a one-off payment.

Minimum payout amounts

Step-by-step instructions are in How to withdraw Telegram Stars to TON.

Record keeping

Whether for taxes or disputes, keep for each payment: date, amount in Stars, payer reference, invoice/payload, the telegram_payment_charge_id, and for each payout the on-chain transaction reference. A platform ledger does this automatically; with your own bot, store it in your database and export monthly.

Frequently misunderstood points

• "My balance shows X but I can only withdraw Y": the difference is Stars younger than 21 days or reserved by pending withdrawal requests.
• "The buyer asked for a card refund": Stars refunds return Stars. The buyer can spend them on any Telegram product; cash refunds are not possible for Stars.
• "Can I speed up the hold?": no, the 21 days are enforced by Telegram for everyone.
• "Does the 3% fee apply to refunded payments?": on Telegram Stars Payment Platform the fee is applied at withdrawal on what you actually withdraw, so refunded Stars are not charged.