Referência da API para comerciantes

As convenções que todos os métodos compartilham, mais os métodos de catálogo somente leitura. Páginas método a método: faturas e reembolsos, transferências e cheques, assinaturas, webhooks.

A API é compatível com o Crypto Bot: uma integração existente do Crypto Bot funciona mudando só a base da URL e o token. Tudo além desse contrato está marcado como extensão abaixo.

Uma especificação OpenAPI 3.1 legível por máquina de toda a API — cada método, objeto, nome de erro e webhook — é publicada junto com estas páginas: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Use com geradores de código, clientes de API ou suas ferramentas de IA.

URL base e autenticação

Todos os métodos ficam em https://crypto.tgpaybot.com/pay/api/<methodName>.

Autentique cada requisição com o token no cabeçalho TgCryptoPay-API-Token (Crypto-Pay-API-Token é aceito como alias de compatibilidade; se os dois forem enviados, vale o canônico). Um token ausente, inválido ou revogado — ou um token de um app excluído — devolve 401 unauthorized.

O token tem o formato <app_id>:<secret> e é mostrado uma vez, na criação ou na rotação; o servidor guarda só o hash dele. Veja primeiros passos para desenvolvedores.

Tokens e escopos

Dois tipos de credencial autenticam do mesmo jeito:

• O token principal — acesso total a todos os métodos, e a única chave que assina webhooks.
• Os tokens restritos (extensão) — até 10 ativos por app, criados em Mais → API para comerciantes, em Tokens restritos, cada um com uma etiqueta e um subconjunto de escopos. Revogar um é instantâneo e não mexe nos outros; rotacionar o token principal também não mexe neles.

Escopo	Métodos que ele libera
(qualquer token válido)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

Os escopos são cumulativos e independentes — invoices não implica read, então um servidor que só cria faturas pode ter um token que não lê nada. Chamar um método que o token não cobre devolve 403 scope_required. O getMe informa os scopes do token atual (null para o token principal) e o token_name, então você sempre consegue conferir o que tem em mãos.

Requisições e respostas

• Os métodos de leitura são GET, com parâmetros na query string. Os métodos que movimentam dinheiro são apenas POST — parâmetros como corpo JSON, form-urlencoded ou query params (em caso de conflito, vale o corpo); multipart/form-data é rejeitado.
• Toda resposta é JSON com o mesmo envelope: sucesso {"ok": true, "result": …}, erro {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. Faça a lógica pelo error.name — ele é a string estável legível por máquina.
• Um caso de borda: um valor de query com tipo inválido em um método GET (por exemplo, offset=abc) devolve HTTP 422 com um corpo {"detail": …} fora do envelope. Mande valores de query bem tipados.

Valores

• Os valores em cripto são strings decimais em unidades de moeda inteira ("10.5") — nunca números JSON. As respostas também trazem amount_minor (extensão): o valor inteiro em unidades menores, como string, porque inteiros na escala de wei estouram um Number do JavaScript.
• Os decimals de cada ativo vêm do getCurrencies — baseie sua matemática de valores nisso, em vez de fixar no código.
• Os valores em moeda fiduciária têm no máximo 2 casas decimais.
• As cotações são strings de ponto fixo, nunca números.

Paginação

Os métodos de lista (getInvoices, getChecks, getTransfers, getSubscriptions) aceitam offset (padrão 0) e count (padrão 100, máx. 1000; getSubscriptions máx. 500) e devolvem {"items": […]}, dos mais novos para os mais antigos. Os filtros por ID (invoice_ids, check_ids, transfer_ids) são listas de inteiros separadas por vírgula. Os carimbos de tempo, em toda a API, são strings ISO 8601.

Idempotência: spend_id

Os métodos que movimentam dinheiro aceitam uma chave spend_id gerada por quem chama (de 1 a 64 caracteres): obrigatória no transfer e em cada item do transferBatch, opcional no createCheck e no refundInvoice (extensão — use mesmo assim). Repetir com a mesma chave e os mesmos parâmetros repete o resultado original em vez de mover fundos duas vezes, então uma requisição que deu timeout sempre pode ser repetida com segurança. A mesma chave com parâmetros diferentes devolve 409 idempotency_conflict; uma nova tentativa enquanto a original ainda está executando devolve 409 idempotency_in_progress.

Limites de requisições

Por app, compartilhados entre todos os tokens dele; ultrapassar devolve 429 rate_limited:

Método	Limite
createInvoice, createCheck	60 por minuto
refundInvoice, transfer	30 por minuto
transferBatch	10 por minuto

Os métodos de leitura não têm limite. Durante manutenções da plataforma, os métodos de escrita devolvem 503 maintenance enquanto os de leitura continuam funcionando.

Métodos de catálogo e de conta

getMe

GET /pay/api/getMe — sem parâmetros. Devolve a identidade do app: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (os tipos de webhook estendidos que o app ativou) e os campos de introspecção do token scopes / token_name descritos acima.

getBalance

GET /pay/api/getBalance — sem parâmetros. Devolve um array com uma linha por ativo suportado, mesmo zerado: currency_code, available (saldo que dá para gastar), onhold (fundos reservados nos seus cheques em aberto) e amount_minor.

getCurrencies

GET /pay/api/getCurrencies — sem parâmetros. A lista que vale sobre o que a API suporta: linhas de cripto (is_blockchain: true) e as moedas fiduciárias em que as faturas podem ser precificadas (is_fiat: true). Cada linha traz code, name, decimals e a flag is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — sem parâmetros. Cotações de cripto para moeda fiduciária: source, target, rate (uma string de ponto fixo) e is_valid — false significa que a tabela inteira vem de um cache velho; trate essas cotações como indicativas.

getStats

GET /pay/api/getStats — start_at / end_at opcionais (ISO 8601; a janela padrão são as últimas 24 horas). Devolve volume (valor em dólares das faturas pagas na janela), conversion (pagas/criadas, em porcentagem), unique_users_count, created_invoice_count, paid_invoice_count e os limites efetivos da janela. Uma data que não dá para interpretar devolve 400 invalid_date.

Erros que todo método pode devolver

HTTP	error.name	Quando
401	unauthorized	token ausente, inválido ou revogado
403	scope_required	o token não tem o escopo do método
400	invalid_request	parâmetros inválidos ou impossíveis de interpretar (POST)
429	rate_limited	limite de requisições ultrapassado
503	maintenance	manutenção da plataforma (métodos de escrita)
500	internal_error	erro inesperado do servidor

Os erros específicos de cada método estão na página do método.