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 em um toque.
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 callback assinado no momento do pagamento.
- 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 que qualquer pessoa pode usar, a partir do saldo do seu app.
- 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 gastam dele.
- Todo evento que importa pode ser enviado ao seu servidor como um webhook assinado.
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 caem. Quem paga ainda pode bancar uma fatura de uma carteira externa — o depósito cai na carteira da própria pessoa e a fatura é liquidada de lá automaticamente; do seu lado, parece exatamente uma fatura paga como qualquer outra.
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. Você pode apontar uma integração existente do Crypto Bot
para a gente mudando a base da URL e o token — os formatos de requisição e
resposta não mudam.
O cabeçalho de token canônico é TgPayCrypto-API-Token, 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
Quem tiver o token consegue transferir o saldo do seu app para fora. 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.