O que é a API para comerciantes?
A API para comerciantes é a API de pagamentos do app para empresas e bots. Você cria um app, recebe um token de API e usa esse token para cobrar usuários do Telegram, mandar pagamentos para eles e consultar seu saldo — tudo do seu próprio código.
É o lado de desenvolvedor do mesmo produto que os usuários veem: uma fatura que você cria pela API é a fatura que eles pagam com o saldo após confirmar o pagamento.
O que dá para fazer com ela
- Faturas — crie um pedido de pagamento (um valor fixo em cripto, um preço em moeda fiduciária ou um valor livre escolhido por quem paga), mande o link para quem vai pagar e receba um webhook assinado após o pagamento, se uma URL de webhook estiver configurada.
- Reembolsos — devolva o valor de uma fatura paga, no todo ou em parte, para quem pagou — inclusive quem pagou anonimamente.
- Transferências — mande cripto do saldo do seu app para um usuário do Telegram, uma a uma ou até 100 em lote.
- Cheques — emita links resgatáveis com fundos do saldo do app, para qualquer pessoa ou para destinatários definidos, conforme suas configurações de pagamentos.
- Assinaturas — cobrança recorrente: os usuários aprovam um plano uma vez e são cobrados automaticamente a cada período.
- Saldos, moedas, cotações e estatísticas — endpoints de leitura para a sua própria contabilidade.
Como as peças se encaixam
- Seu app tem um saldo, separado da sua carteira pessoal.
- As faturas pagas pelos usuários creditam esse saldo do app.
- As transferências e os cheques usam esse saldo.
- Os eventos de pagamento disponíveis podem ser enviados ao seu servidor como um webhook assinado quando você configura a URL e escolhe os eventos que deseja receber.
Os pagamentos são liquidados dentro do app, e não on-chain: sem taxa de rede, sem
confirmações para esperar, e os fundos ficam utilizáveis no instante em que
são creditados. Quem paga também pode usar uma carteira externa para adicionar os fundos necessários à fatura, quando essa opção estiver disponível. O depósito é creditado na carteira da própria pessoa; o pagamento automático exige saldo suficiente, ausência de restrições de saída e prazo de pagamento válido. Do seu lado, confirme que a fatura está com status paid antes de entregar o pedido.
Compatível com o Crypto Bot
A API espelha a do Crypto Bot de propósito: mesmos nomes de método, mesmo
envelope {ok, result}, mesmos valores em string decimal, mesmo esquema de
assinatura de webhook. Para adaptar uma integração existente, altere a URL base e o token, depois teste os métodos que você usa com base na nossa referência. Assim como o Crypto Bot, mantemos uma
testnet com bot e URL base separados.
O cabeçalho de token canônico é TgPayCrypto-API-Token; o
TgCryptoPay-API-Token, de antes de 07/09/2026, ainda funciona, e
Crypto-Pay-API-Token é aceito como alias, para as bibliotecas cliente
existentes continuarem funcionando sem mudança.
⚠️ Seu token de API é uma chave de gastos
O token principal autoriza pagamentos conforme o modo de pagamentos e os limites do app. Mantenha-o no servidor, fora de apps cliente e de repositórios, e rotacione no momento em que suspeitar de vazamento. Para servidores que não precisam de acesso total, crie um token restrito limitado aos escopos que eles realmente usam — veja a referência da API.
A seguir
Este artigo foi útil?
Obrigado pelo retorno.