Pagamentos em cripto no Telegram: faturas, webhooks e repasses
A API para comerciantes é a API de pagamentos do TG Crypto Pay para bots e serviços. Crie um app no bot, obtenha um token, emita faturas pelo código e receba um webhook assinado assim que forem pagas. Ou passe a URL do servidor MCP ao seu agente de IA para ele fazer a integração. Os pagamentos acontecem dentro da carteira, sem taxa de rede nem espera por confirmações.
URL base da API — app.tgpaycrypto.com/pay/api · rede de testes — testnet.tgpaycrypto.com
Do token ao primeiro pagamento em quatro etapas
O processo habitual de uma API de pagamentos: criar a fatura, mostrar o link e aguardar o evento.
Crie um app
No bot, abra Mais → API para comerciantes e informe um nome e a URL do webhook. O token aparece uma única vez: guarde-o no seu servidor.
Crie uma fatura
Uma requisição POST ao createInvoice: valor em cripto ou moeda fiduciária, descrição e prazo. A resposta traz o link de pagamento.
Mostre o link ao usuário
Use um botão ou link no seu bot: o usuário paga com o saldo da carteira com um toque.
Processe o webhook
Seu servidor recebe invoice_paid com assinatura HMAC-SHA256. Verifique a assinatura, elimine duplicatas pelo update_id e entregue o produto.
Seu agente de IA pode fazer a integração
A API para comerciantes tem um servidor MCP. Passe uma URL ao agente: ele lê a documentação, cria o app, configura o webhook e escreve o código. Sem terminal nem cópia manual do token.
- Passo 1
Envie o prompt ao agente
Use um chat com agente: Claude Code, claude.ai, Claude Desktop, ChatGPT ou outro cliente MCP. O mesmo prompt está no app, em Mais → API para comerciantes, na opção de conectar um agente de IA.
- Passo 2
Aprove o app no Telegram
O agente envia um link t.me. O bot mostra o que está sendo solicitado, e você aprova com um botão. O link só funciona uma vez; nada é criado antes da sua aprovação.
- Passo 3
O agente conclui a configuração
Ele recebe um token restrito e conclui a integração de faturas, planos de assinatura e webhook. A chave de assinatura do webhook fica com você no app.
O token do agente permite receber pagamentos e configurar o webhook, mas não transferir, emitir cheques ou reembolsar. A saída de saldo continua sob seu controle, com o token completo no app.
Saiba mais sobre a conexão do agente na documentaçãoConnect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Nas configurações de conectores, adicione um conector personalizado e cole app.tgpaycrypto.com/mcp
https://testnet.tgpaycrypto.com/mcp
Taxas e limites
Os valores vêm do catálogo público de limites do app, consultado quando esta página foi gerada. Os valores atuais estão no app.
O que a API para comerciantes oferece
O app tem saldo próprio, separado da sua carteira: pagamentos de faturas entram nele; pagamentos a usuários e cheques saem dele.
Faturas e reembolsos
Valor fixo em cripto, preço em moeda fiduciária ou valor livre escolhido por quem paga. Reembolsos totais ou parciais, inclusive para pagadores anônimos.
Assinaturas
O usuário aprova o plano uma vez. Depois, a cobrança acontece automaticamente a cada período, com um evento para cada cobrança.
Transferências e cheques
Pagamentos a usuários do Telegram com o saldo do app e cheques: links que qualquer pessoa pode resgatar.
Webhooks
invoice_paid é enviado sempre. Eventos de expiração de fatura, resgate de cheque, reembolso e assinatura são ativados separadamente para cada app.
Rede de testes
A mesma API e o mesmo Mini App no @tgpaycrypto_testnet_bot. Um botão na tela inicial libera moedas de teste uma vez por hora.
Agente de IA e MCP
Passe app.tgpaycrypto.com/mcp ao seu agente: ele cria o app, configura o webhook e escreve a integração. Você aprova o app com um botão no bot.
Compatível com a Crypto Bot API
Os mesmos nomes de métodos, formato {ok, result} e esquema de assinatura de webhooks. Troque a URL base e o token; o código continua igual.
Controle sobre o token
Tokens com permissões restritas, rotação imediata, opção de pagar apenas a usuários da lista ou desativar pagamentos e limite diário de pagamentos em caso de vazamento do token.
Dúvidas sobre a API
Saiba mais sobre tokens, assinaturas de webhook, testes e migração de outra API.
A criação de um app pode exigir a verificação de identidade concluída, conforme a política vigente. Se houver um erro de verificação, conclua essa etapa no app e tente novamente.
O cabeçalho TgPayCrypto-API-Signature contém o HMAC-SHA256 do corpo da requisição, usando o SHA-256 do token principal como chave. Compare a assinatura usando os bytes originais do corpo. Só entregue o produto ou marque a fatura como paga depois de validar a assinatura.
Sim. A API para comerciantes reproduz os métodos da Crypto Bot API, o formato {ok, result}, valores em strings decimais e o esquema de assinatura. Troque a URL base e o token; o cabeçalho Crypto-Pay-API-Token também é aceito.
A rede de testes usa a mesma API e o mesmo Mini App: bot @tgpaycrypto_testnet_bot e URL base testnet.tgpaycrypto.com/pay/api. O botão de moedas de teste na tela inicial libera 1.000 USDT, 1.000 GRAM e 0,01 BTC uma vez por hora. Tokens da rede principal e de testes não são intercambiáveis.
O agente recebe um token restrito: cria faturas e planos de assinatura, consulta saldo e estatísticas e configura a URL do webhook. Transferências, cheques e reembolsos exigem o token completo, que fica com você.
Documentação pública da API para comerciantes
Referência dos métodos, descrição OpenAPI e guias passo a passo em docs.tgpaycrypto.com.
Configure os pagamentos em uma noite
Crie um app no @tgpaycryptobot ou passe o link do servidor MCP ao seu agente de IA e aprove o app com um botão.
Abrir o bot