Guia · PayStars

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:

API PayStars para desenvolvedores: o fluxo completo para vender Stars e Premium no seu bot

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.

ParteO que faz
AcessoCabeçalho X-API-Key; as chaves são criadas no painel
SaldoUSD, recarregado com USDT (TON, BEP20 ou TRC20)
PreçoPreço do Fragment × 1,05, arredondado para cima até o centavo
Limite10 requisições por segundo por chave
TransparênciaUm 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

  1. Mantenha a chave da API em uma variável de ambiente do servidor, não no código.
  2. Execute todo o fluxo com um pedido real pequeno de 50 Stars.
  3. 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

Compre Stars e Premium com dólar (USDT)

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

Começar