Taxas e limites da API para comerciantes

As faturas têm uma taxa da plataforma, descontada 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 1,5% do valor da fatura — uma alíquota única para todas as faturas, sem descontos por volume.

Duas regras importam mais que o número:

• A taxa é calculada e fixada no momento do pagamento. Uma mudança posterior na alíquota nunca mexe em uma fatura que já foi paga.
• A taxa é arredondada para baixo até a menor unidade do ativo, então uma fatura muito pequena pode não ter taxa nenhuma.

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.

Cobranças de assinatura também podem ter uma comissão do comerciante — atualmente 0%. Cada cobrança informa sua própria comissão no campo charge.fee do webhook subscription_charged.

Limites de transferência

transfer tem um máximo por transferência de US$ 25.000, expresso pelo equivalente em dólares americanos, e não por um valor separado para cada ativo. Também pode ser definido um mínimo por transferência; no momento, não há mínimo. Na integração, trate amount_too_big e, caso um mínimo seja introduzido, amount_too_small quando o valor for rejeitado por esses limites (os dois são 400). O máximo não se aplica a um ativo que no momento não tem cotação em dólar.

Um username desconhecido gera um pagamento pendente quando o modo de pagamentos permite; veja transferências e cheques.

Uma transferência também falha quando:

• o saldo do seu app é insuficiente naquele ativo,
• quem recebe nunca abriu o TgPay Crypto — 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 — informado com o mesmo 404 user_not_found.

Limite diário de pagamentos

O proprietário pode definir um limite para as últimas 24 horas nas configurações de pagamentos do app. Transferências, cheques e pagamentos feitos com o saldo do app compartilham esse limite. Se ele for excedido, a API retorna 403 daily_cap_exceeded; os lotes são verificados antes do primeiro pagamento. Os reembolsos não entram nesse limite. getMe retorna daily_payout_max_usd_cents e daily_payout_spent_usd_cents.

Restrições na conta do proprietário também podem bloquear transferências, cheques e reembolsos (403 verification_required); uma pausa temporária retorna 503 merchant_payouts_paused.

Limites de requisições

Os métodos que movimentam dinheiro têm limites de requisições por app, compartilhados entre todos os tokens dele e contados separadamente para cada método: createInvoice e createCheck permitem 60 por minuto; refundInvoice, 30 por minuto; transfer, 30 por minuto; e transferBatch, 10 por minuto. updateApp e createSubscriptionPlan também têm limites; veja a referência da API. Ao receber rate_limited, aumente o intervalo antes de tentar novamente.

Idempotência

O transfer exige um spend_id gerado por você; o createCheck e o refundInvoice aceitam um. Reutilizar o mesmo valor com os mesmos parâmetros 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 plataforma pode cobrar taxas sobre faturas e cobranças de assinatura. Uma troca automática opcional usa a cotação de câmbio. Ao adicionar fundos de uma carteira externa à carteira de quem paga, podem incidir taxas dessa carteira ou da rede.

⚠️ 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. A alíquota pode mudar, e uma constante desatualizada corrompe sua contabilidade em silêncio. Leia a taxa registrada na fatura sempre.