Primeiros passos para desenvolvedores

Crie um app no Mini App, copie o token de API uma vez e comece a chamar a API. Toda a configuração fica em Mais → API para comerciantes.

Passo a passo

1. Abra Mais → API para comerciantes e escolha Criar app.
2. Informe um Nome do app (por exemplo, “Minha Loja”) e, se quiser, uma URL de webhook (opcional).
3. Aceite os termos no formulário e toque em Criar app. Confirme com o PIN ou a biometria quando solicitado. Criar um app significa aceitar os termos da API para comerciantes — para que você pode e não pode usar a API.
4. Copie o token de API na hora. Ele é mostrado uma vez e nunca mais — o app guarda só um hash dele.
5. Mande sua primeira requisição com o token no cabeçalho TgPayCrypto-API-Token.

Sua primeira chamada

Aponte seu cliente para a base da API https://app.tgpaycrypto.com/pay/api e chame getMe para confirmar que o token funciona. getBalance devolve os saldos do seu app e getCurrencies, os ativos que você pode usar.

Os métodos de leitura são GET. Os métodos de escrita, como createInvoice, transfer, createCheck, deleteInvoice e deleteCheck, aceitam apenas POST. Os parâmetros podem ir como corpo JSON, como form-urlencoded ou como query params. Prefira o corpo da requisição para que valores e chaves de idempotência não apareçam nos logs de acesso às URLs.

Testnet

Monte a integração primeiro na rede de testes — a mesma API, o mesmo Mini App, fundos de teste sem valor real:

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Base da API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
Servidor MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Os apps e os tokens são separados: um token da testnet não funciona na mainnet, e vice-versa. Para obter fundos de teste, abra o Mini App da testnet e toque em Obter moedas de teste na tela inicial. Os fundos de teste são creditados como depósitos comuns; ativos de redes desativadas não são incluídos. O app mostra o que foi creditado e quando você poderá solicitar mais fundos. Você pode usar uma segunda conta do Telegram como o cliente que paga suas faturas de teste.

Depósitos e saques usam uma custódia simulada, sem transações reais na blockchain. Nunca envie fundos reais para um endereço de depósito da testnet. O contrato da API é o mesmo, mas os recursos disponíveis, as cotações e os limites podem diferir da mainnet. Quando terminar, crie um app de produção no @tgpaycryptobot e troque a URL base.

Gerenciando um app

Abra um app em API para comerciantes para ver o ID e o saldo dele. Nessa tela, você pode:

• Definir ou trocar a URL de webhook em Webhook e salvar.
• Escolher eventos extras de webhook — as opções de Eventos extras de webhook, na seção Webhook, permitem escolher tipos de evento além do invoice_paid (veja a referência de webhooks).
• Restringir quem a API pode pagar — em Configurações de pagamentos, Pagamentos pela API vem como Qualquer usuário em um app novo; mude para Só usuários da lista (e cadastre quem recebe) ou Desativado se a sua integração nunca paga ninguém — uma proteção para o caso de o token vazar (veja o modo de pagamentos).
• Criar tokens restritos — abra Acesso e tokens para criar tokens de API adicionais em Tokens restritos, cada um limitado aos escopos que você escolher (veja a referência da API).
• Rotacionar token — em Acesso e tokens, emite um token novo e invalida o antigo na hora. Use isso se um token vazou; o novo é mostrado uma vez só, como na criação.
• Excluir — primeiro retire o saldo disponível; caso contrário, a exclusão será rejeitada com app_has_balance. Resolva também os cheques em aberto e os pagamentos pendentes antes de excluir. O app sai da lista e seus tokens deixam de funcionar; o histórico de pagamentos é mantido.

Webhooks

Se você definir uma URL de webhook, o app faz POST de um corpo JSON assinado para ela:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

A assinatura vem no cabeçalho TgPayCrypto-API-Signature (com TgCryptoPay-API-Signature e Crypto-Pay-API-Signature como aliases de compatibilidade): HMAC-SHA256 sobre o corpo bruto, com chave igual ao SHA-256 do seu token de API principal. Verifique antes de confiar em qualquer coisa do payload.

As entregas são repetidas com backoff exponencial por um período prolongado, e o update_id continua o mesmo entre as tentativas — baseie sua deduplicação nele e faça seu handler idempotente.

O invoice_paid não exige ativação separada quando há uma URL de webhook configurada. Os outros tipos de evento — faturas expiradas, cheques resgatados, reembolsos, eventos de assinatura — são opcionais, pelas chaves de Eventos extras de webhook. A lista completa, os formatos de payload e a programação de novas tentativas estão na referência de webhooks.

⚠️ Guarde o token como uma chave privada

Ele autoriza pagamentos a partir do saldo do seu app. Mantenha no seu servidor, nunca em um app de celular, em um bundle de front-end ou em um arquivo de configuração commitado. Se você não tiver certeza se ele vazou, rotacione — a rotação é instantânea e não custa nada. E dê a cada servidor só o que ele precisa: um token restrito apenas ao escopo invoices pode criar e excluir faturas, mas não pode transferir fundos, criar cheques nem emitir reembolsos.