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.
2. Informe um Nome do app (por exemplo, “Minha Loja”) e, se quiser, uma URL de webhook.
3. Toque em Criar app.
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 TgCryptoPay-API-Token.

Sua primeira chamada

Aponte seu cliente para a base da API https://crypto.tgpaybot.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 que movimentam dinheiro — createInvoice, transfer, createCheck e os equivalentes de exclusão — são apenas POST, de propósito: valores e chaves de idempotência não têm o que fazer em logs de acesso. Os parâmetros podem ir como corpo JSON, como form-urlencoded ou como query params.

Gerenciando um app

Cada cartão de app em API para comerciantes mostra o ID e o saldo do app, e deixa você:

• Definir ou trocar a URL de webhook e salvar.
• Escolher eventos extras de webhook — com uma URL de webhook definida, as chaves de Eventos extras de webhook deixam você optar por tipos de evento além do invoice_paid (veja a referência de webhooks).
• Criar tokens restritos — tokens de API adicionais em Tokens restritos, cada um limitado aos escopos que você escolher (veja a referência da API).
• Rotacionar token — 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 — o app para de autenticar, mas o saldo e o histórico de pagamentos são preservados. Excluir um app nunca faz o dinheiro dele sumir.

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 TgCryptoPay-API-Signature (com Crypto-Pay-API-Signature como alias de compatibilidade): HMAC-SHA256 sobre o corpo bruto, com chave igual ao SHA-256 do seu token de API. 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 é sempre entregue. 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 sem o escopo payouts cria faturas, mas nunca consegue tirar o seu saldo.