API PayStars para desenvolvedores: o fluxo completo para vender Stars e Premium no seu bot
Como a API REST da PayStars funciona de ponta a ponta: X-API-Key, verificação de nome de usuário, cotações em USD com max_usd, pedidos idempotentes, o erro 409 price_changed e a verificação de TxId, como plano de integração.
Publicado: · Atualizado:

Quer vender Telegram Stars e Premium no seu próprio bot, loja ou aplicativo? A API PayStars oferece uma interface HTTPS e um saldo em USD compartilhado com o site. Em vez de repetir a referência da API, este artigo mostra como montar a integração do início ao fim.
A arquitetura em resumo
Seu sistema faz três coisas: abastece o saldo com USDT, consulta um preço e cria um pedido. Todo o resto, inclusive a entrega pelo fluxo oficial de compra do Telegram, acontece do lado da PayStars.
| Parte | O que faz |
|---|---|
| Acesso | Cabeçalho X-API-Key; as chaves são criadas no painel |
| Saldo | USD, recarregado com USDT (TON, BEP20 ou TRC20) |
| Preço | Preço do Fragment × 1,05, arredondado para cima até o centavo |
| Limite | 10 requisições por segundo por chave |
| Transparência | Um TxId público para cada pedido concluído |
Etapa 1: abastecer o saldo
POST /usd/invoice com um valor e uma rede ("ton", "bsc" ou "trc20") retorna um valor exato válido por 30 minutos. O mínimo é 0,1 USDT.
Etapa 2: verificar o destinatário
POST /api/v1/check-username verifica o destinatário e retorna um token de verificação de curta duração. Isso evita pagamentos para nomes de usuário que não existem: se o cliente errar a digitação, você descobre antes de qualquer cobrança.
Etapa 3: obter e limitar o preço
POST /api/v1/usd/quote retorna o preço atual (usd) e o acréscimo (markup_percent: 5). O preço acompanha o mercado, então:
- solicite uma cotação atualizada antes de cada pedido;
- informe max_usd igual ao valor cotado;
- sempre envie currency: "USD", caso contrário será usada a preferência salva da conta.
Etapa 4: criar o pedido
POST /api/v1/stars/buy ou /api/v1/premium/buy. Toda requisição deve levar uma Idempotency-Key, para que, se a conexão cair e você tentar de novo, não seja cobrado duas vezes. Guarde a chave junto com o ID do pedido no seu banco de dados.
Etapa 5: acompanhar o estado
GET /api/v1/order/{id} e /api/v1/orders informam os estados e o histórico. A maioria dos pedidos é entregue em minutos. Um pedido concluído recebe um TxId que você e seu cliente podem conferir no registro público da PayStars.
Tratando os erros corretamente
- 409 price_changed significa que o preço ficou acima de max_usd e nada foi cobrado. Obtenha uma nova cotação e mostre ao cliente o preço atualizado.
- Limite de requisições: não ultrapasse 10 requisições por segundo; adicione uma fila ou espera progressiva.
- Novas tentativas: sempre reutilize a mesma Idempotency-Key.
Antes de entrar em produção
- Mantenha a chave da API em uma variável de ambiente do servidor, não no código.
- Execute todo o fluxo com um pedido real pequeno de 50 Stars.
- Mostre aos clientes o TxId deles, o que gera confiança.
Documentação completa e guias de início rápido: API de Stars da PayStars e preços em USD da API. Para pagamentos no bot, veja bens digitais em bots são pagos apenas em Stars.
Perguntas frequentes
Existe um ambiente de testes?
Não há um ambiente de testes separado; teste com pedidos reais pequenos (50 Stars) durante a integração.
Quais linguagens de programação funcionam?
Qualquer linguagem que consiga fazer requisições HTTPS. Há guias de início rápido para Python, Node.js e PHP.
Como abasteço o saldo?
Com USDT em TON, BEP20 ou TRC20, mínimo de 0,1 USDT; cada fatura tem um valor exato válido por 30 minutos.
Fontes
Related pages
Compre Stars e Premium com dólar (USDT)
Via chave de API: preço Fragment, 0% (site: 5%).
More news
Telegram Stars e Premium no Uzbequistão: pague com cartão ou com USDTComprar Telegram Stars ou Premium no Uzbequistão: Uzcard e Humo pelo @StarKerakBot, USDT em paystars.uz/uz/, os caminhos oficiais do app e as regras locais que você precisa conhecer.Ler →
Como premiar vencedores de concursos com Telegram Stars ou Premium: um guia para organizadoresEntrega de Telegram Stars ou Premium aos vencedores do seu questionário, concurso ou hackathon: orçamento, coleta de @usernames, entrega pelo PayStars e um relatório de acompanhamento.Ler →
Perguntas frequentes do PayStars: dúvidas comuns sobre acesso, recargas em USDT e pedidos de Stars e PremiumAs perguntas mais comuns sobre o PayStars em uma página: entrar com o Telegram, recarregar com USDT (TON, BEP20 ou TRC20), pedir Stars e Premium, prazos de entrega, segurança e a API.Ler →