Taxas e limites da API para comerciantes

As faturas têm uma taxa da plataforma, tirada do que você recebe; as transferências e os cheques são limitados por valor. Os números abaixo são as configurações atuais, não termos de contrato — quando eles divergirem do que você vê, quem está certo é o app, e a fonte confiável são sempre as suas próprias faturas pagas.

A taxa da fatura

Quem paga sempre paga o valor de face da fatura. A taxa sai do lado do comerciante: o saldo do seu app é creditado com o valor líquido da taxa.

A taxa é de 3% do valor da fatura, e ela cai automaticamente conforme o seu volume de pagamentos dos últimos 30 dias:

Duas regras importam mais que o número:

• A taxa é resolvida e travada no momento do pagamento. Uma mudança posterior na alíquota nunca mexe em uma fatura que já foi paga.
• Sua alíquota pode mudar com o seu volume. Um volume de pagamentos maior em uma janela móvel de 30 dias pode mover você para uma faixa menor automaticamente. Você não pede nada e não tem o que configurar.

Para ver exatamente o que foi cobrado, leia fee_asset e fee_amount na fatura paga — no payload do webhook invoice_paid ou no getInvoices. Esse é o número que vale para a sua contabilidade.

Os reembolsos não devolvem a taxa: o que o refundInvoice manda para quem pagou sai do seu saldo, e a taxa não é devolvida — inclusive em um reembolso parcial.

As cobranças de assinatura também têm uma taxa do lado do comerciante; cada cobrança informa o próprio número no campo charge.fee do webhook subscription_charged.

Limites de transferência

O transfer tem um mínimo e um máximo por transferência, aplicados como uma estimativa equivalente em dólares pelas cotações do momento, e não como um número por ativo. Um valor fora dessa faixa é rejeitado com um erro explícito, então trate amount_too_small e amount_too_big na sua integração.

Uma transferência também falha quando:

• o saldo do seu app está curto naquele ativo,
• quem recebe não é usuário do app — um pagamento para um ID do Telegram desconhecido ou digitado errado dá erro, em vez de creditar uma carteira que ninguém vai abrir,
• a conta de quem recebe está bloqueada.

Limites de requisições

Os métodos que movimentam dinheiro têm limite de requisições por app (compartilhado entre todos os tokens dele): createInvoice e createCheck a 60 por minuto, refundInvoice e transfer a 30, transferBatch a 10. Os métodos de leitura são ilimitados. Uma integração bem-comportada nunca percebe; um laço de novas tentativas percebe — faça backoff no rate_limited em vez de martelar.

Idempotência

O transfer exige um spend_id gerado por você; o createCheck e o refundInvoice aceitam um. Reutilizar o mesmo valor repete o resultado original em vez de mover fundos uma segunda vez — então uma requisição que deu timeout pode ser repetida com segurança usando o mesmo spend_id, e só um pagamento genuinamente novo ganha um novo.

O que não custa nada

Não existe taxa de rede em lugar nenhum da API para comerciantes — faturas, transferências e cheques são todos liquidados dentro do app, fora da blockchain. A taxa da plataforma sobre as faturas é a única cobrança.

⚠️ Nunca calcule a taxa por conta própria

Não fixe uma porcentagem no código nem reconstrua o líquido a partir do valor de face. As faixas e as alíquotas mudam, e uma constante desatualizada corrompe sua contabilidade em silêncio. Leia a taxa registrada na fatura sempre.