Pagamentos em cripto no Telegram: faturas, webhooks e repasses
A API para comerciantes é a API de pagamentos do TgPay Crypto para bots e serviços. Crie um app, obtenha um token, emita faturas pelo código e receba webhooks de pagamento assinados. Um agente MCP compatível pode ajudar na integração. Pagamentos com o saldo da carteira são liquidados dentro do serviço; pagamentos pela blockchain seguem as regras de confirmação da rede escolhida.
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. Conecte-o em um cliente de agente compatível: o agente pode ler a documentação, solicitar a criação de um app, configurar webhooks e ajudar a escrever a integração. Você aprova o app no Telegram, revisa e testa o resultado.
- Passo 1
Envie o prompt ao agente
Use um cliente de agente com suporte a MCP remoto disponível para sua conta ou espaço de trabalho. O prompt também 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
Conclua e teste a integração
O agente recebe um token restrito e ajuda a configurar faturas, planos de assinatura e webhooks. Para obter a chave de assinatura dos webhooks, gere novamente o token principal no app e armazene-o com segurança no seu servidor.
O token do agente permite receber pagamentos e configurar webhooks. Ele não permite transferências, emissão de cheques ou reembolsos; essas ações exigem um token com as permissões correspondentes.
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 Crypto Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Adicione app.tgpaycrypto.com/mcp como servidor MCP remoto nas configurações do cliente. A disponibilidade e os nomes dos menus dependem do cliente e da sua conta.
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
Conecte app.tgpaycrypto.com/mcp em um cliente de agente com suporte a MCP remoto. Após sua aprovação no Telegram, o agente pode criar um app e ajudar na integração. Revise e teste o resultado antes de usar.
Compatível com a Crypto Bot API
Nomes de métodos conhecidos, formato {ok, result} e assinaturas HMAC dos webhooks. Atualize a URL da API e o token, depois teste os métodos usados na sua integração.
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.
A API para comerciantes usa nomes de métodos conhecidos, formato {ok, result}, valores em strings decimais e assinaturas HMAC. Atualize a URL da API e o token; o cabeçalho Crypto-Pay-API-Token também é aceito. Antes de migrar, consulte a documentação e teste os métodos e as criptomoedas que sua integração usa.
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 para faturas, planos de assinatura, saldos, estatísticas e configurações de webhooks. Esse token não permite transferências, emissão de cheques ou reembolsos. Essas ações exigem um token com as permissões correspondentes.
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