Telegram Stars

How the payer pays#

1. On the checkout the payer chooses Telegram Stars and sees the amount in Stars before going further.
2. Continue to Telegram creates a payment link. On a phone, Open in Telegram opens it in the app; on a computer the payer scans the QR code with the phone that has Telegram, or copies the link.
3. Telegram shows your store's name and the order reference, and the payer confirms. A payer short of Stars can top up right there in Telegram.
4. The payment arrives within seconds and you receive order.paid. The checkout updates by itself.

The payment comes from one of VelPay's Telegram bots. Your store name, not VelPay, is the title of the invoice the payer confirms.

Amount and links#

• The checkout converts the amount due into Stars at VelPay's rate, rounded up, when the link is created. You are credited the order's value.
• A link stays payable for 30 minutes, or until the order expires if that is sooner. After that the checkout offers Get a new link as long as the order is open.
• A new link replaces the order's older one, which Telegram then refuses. A payment the payer had already confirmed on the old link still counts.
• Each link pays once, for the exact amount. If someone pays the same link twice, the second payment goes back to them in Stars automatically.

Limits#

• Per order: from 1 USD (or the equivalent) unless your account has different limits.
• Telegram caps one payment at 10,000 Stars, which is about 130 USD at the current rate. Larger orders don't offer Stars.
• Orders outside the range don't show Stars; if Stars is the only method you allow, the API answers 400 amount_too_small.

Showing Stars first#

If your customers are on Telegram (a bot, a channel, a Mini App), list it first: "methods": ["stars", "crypto"] on POST /orders shows the methods in that order and preselects Stars. "methods": ["stars"] offers only Stars.

Settlement#

Telegram holds Stars for 21 days before they can be withdrawn, so Stars payments settle to your available balance 21 days after they are paid. Your dashboard shows the exact schedule for your account.

Payment support in Telegram#

Telegram requires every bot that takes payments to answer /paysupport. When a payer sends it, the bot tells them which store their last payment went to, with the order reference and the Support URL for payers from your workspace settings, and asks them to contact you. Keep that link current.

Refunds and Telegram reversals#

Refunds you make with POST /orders/:id/refunds are paid in USDT on Tron to a wallet address the payer gives you, or on another network if you pass network; they don't go back as Stars. Tell your customers this in your refund policy.

If Telegram itself gives a payment's Stars back to the payer, that works like a card chargeback: you receive dispute.opened and dispute.closed (lost) for the order, and the amount plus the dispute fee is taken from your balance.

Testing#

In test mode no Telegram invoice is created and the link can't be paid in Telegram. Use Simulate payment on the checkout; it sends the same events. See testing.