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 3% do valor da fatura antes de aplicar as faixas por volume. Sua alíquota depende das faixas configuradas e do volume de faturas pagas nos últimos 30 dias:

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.
• 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, expressos em equivalente em dólares, em vez de um valor separado para cada ativo. Trate amount_too_small e amount_too_big na sua integração quando um valor for rejeitado por esses limites.

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 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.

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: 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. As faixas e as alíquotas mudam, e uma constante desatualizada corrompe sua contabilidade em silêncio. Leia a taxa registrada na fatura sempre.