Guia · Telegram Stars

Faturas de Telegram Stars (XTR) em bots: o fluxo de pagamento para desenvolvedores, passo a passo

Venda de bens digitais por Stars em um bot: sendInvoice com XTR, a resposta a pre_checkout_query em 10 segundos, successful_payment, armazenamento do ID da cobrança e uma lista de verificação para o lançamento.

Publicado:

Faturas de Telegram Stars (XTR) em bots: o fluxo de pagamento para desenvolvedores, passo a passo

Seu bot vende algo digital, como uma assinatura, conteúdo, solicitações de IA ou itens de jogo? Então o pagamento é somente em Telegram Stars. Este artigo percorre o fluxo da fatura de Telegram Stars (XTR) do ponto de vista de um desenvolvedor, seguindo a documentação oficial da API de bots. Para saber por que precisa ser Stars, veja bens digitais em bots somente via Stars.

O fluxo em resumo

PassoO que o bot fazO que o Telegram envia
1sendInvoice com currency = XTR—
2Aguardapre_checkout_query
3answerPreCheckoutQuery (em até 10 segundos)—
4Aguardasuccessful_payment
5Armazena o ID da cobrança e entrega os bens—

Passo 1: crie a fatura

Há duas formas:

  • Fatura do bot: o método sendInvoice. Como os bens são digitais, provider_token é uma string vazia e o campo currency é XTR. A fatura pode ir para um chat privado, um grupo ou um canal.
  • Fatura inline: se o seu bot oferece suporte ao modo inline, inputInvoiceMessageContent permite que os usuários compartilhem a fatura com amigos, grupos e canais. O botão Pagar pode ser usado várias vezes.

Passo 2: escolha o comportamento de encaminhamento

O parâmetro start_parameter controla isso:

  1. Fatura multichat: as cópias encaminhadas mantêm um botão Pagar, então vários usuários podem pagar. Faturas inline são sempre multichat.
  2. Fatura de chat único: pagável somente no chat para o qual foi enviada; as cópias encaminhadas mostram um botão de link direto para o bot.

Observe que uma fatura de chat único enviada no chat privado com o seu bot pode ser paga somente uma vez. De qualquer forma, o seu bot sempre decide se aceita um novo pagamento.

Passo 3: pré-pagamento

O usuário (comprando Stars antes, se necessário) toca em Pagar. Seu bot recebe um pre_checkout_query com os detalhes do pedido e deve responder com answerPreCheckoutQuery em até 10 segundos, ou a transação é cancelada. Se recusar, informe um motivo compreensível; o Telegram o mostra ao usuário.

Passos 4–5: pagamento e entrega

Quando o pagamento é concluído, chega uma mensagem successful_payment. Só então você deve entregar, porque responder a pre_checkout_query não garante que o pagamento foi efetivado. Armazene o telegram_payment_charge_id; você vai precisar dele para reembolsos.

Antes de entrar no ar

  • Ative a verificação em duas etapas na conta que controla o bot.
  • Disponibilize os termos via /terms e o suporte via /support e /paysupport.
  • Esteja preparado para disputas e reembolsos com refundStarPayment. Saiba mais em reembolsos de Stars e /paysupport.
  • Mantenha o servidor estável e faça backup dos dados de pagamento.

Como testar

O ambiente de testes dedicado do Telegram permite testar pagamentos em Stars de graça. Quando tudo funcionar, mude para produção.

O lado da compra de Stars

Seus usuários compram Stars no aplicativo ou pelo @PremiumBot, e a PayStars os vende por USDT. Se o seu próprio serviço precisar comprar Stars automaticamente, a API da PayStars e a visão geral da API explicam isso.

Perguntas frequentes

Posso aceitar cripto ou outra moeda em vez de Stars?

Não. Bens e serviços digitais dentro de aplicativos do Telegram são pagos somente em Stars.

Como testo os pagamentos?

Conecte seu bot ao ambiente de testes dedicado do Telegram, onde os pagamentos em Stars podem ser testados de graça.

Como faço um reembolso?

Com o método refundStarPayment na API de bots.

Fontes

Compre Stars e Premium com dólar (USDT)

Via chave de API: preço Fragment, 0% (site: 5%).

Começar