Limites

Os tetos desta página são valores, não campos. Eles mudam raramente e, quando mudarem, entram no changelog.

Taxas

A taxa padrão é de R$ 1,50 fixos por PIX, sem percentual, a mesma para toda cobrança, qualquer que seja a integração. Não há mensalidade.

Cobrança em cripto (USDT ou USDC em BSC, Polygon, Arbitrum ou Optimism) tem taxa própria: 4% + US$ 0,50 por venda, já incluindo os custos do provedor e da rede, com mínimo de US$ 5 por cobrança. Ver Cobrança em cripto.

Cobrança internacional (cartão em euro, dólar ou libra) tem taxa de 20% por venda, sem valor fixo, e a vigente da sua conta vem em GET /v1/rates. Ver Cartão internacional.

• Quem tem taxa negociada paga a taxa negociada.
• A taxa é congelada na criação da cobrança: mudança de tabela não altera cobranças já criadas.
• GET /v1/rates (permissão read) devolve a taxa vigente da conta da chave:

{
  "pix": {
    "percent_bps": 0,
    "fixed_cents": 150
  },
  "withdrawal": { "fixed_cents": 500 },
  "voucher": {
    "percent_bps": 600,
    "fixed_usd_cents": 0,
    "reserve_bps": 1000,
    "reserve_days": 90,
    "settlement_days": 14
  },
  "negotiated": false,
  "updated_at": "2026-10-17T03:00:00.000Z"
}

negotiated é true quando a conta tem taxa própria. settlement_days é o prazo de liquidação do voucher, fixo em 14 dias. Percentuais em basis points e valores em centavos, sempre inteiros. A consulta funciona também com a conta pendente de KYC ou suspensa.

Chamadas por minuto

O limite é por chave de API e separado por tipo de chamada:

Chaves emitidas por integrações parceiras (conexão OAuth do LeztyBot) escrevem até 600 por minuto.

A janela é fixa de 60 segundos, e não deslizante: o contador zera na virada do minuto.

Toda resposta traz três headers com o estado do balde:

• X-RateLimit-Limit: o teto da classe.
• X-RateLimit-Remaining: quantas chamadas sobram nesta janela.
• X-RateLimit-Reset: o instante em que o contador zera, em segundos desde a época Unix.

Estourou, a resposta é 429 rate_limited com o header Retry-After em segundos. Espere esse tempo antes da próxima tentativa. Não faça backoff cego: o Retry-After já é o número certo, e insistir antes dele só gasta mais 429.

Dois usos que costumam bater no teto e não precisam: pesquisar o status de uma cobrança em laço apertado (use webhooks) e listar tudo de novo a cada minuto (use os filtros de data).

Tamanho do corpo

O corpo de uma requisição em /v1 vai até 256 KB. Acima disso a requisição é cortada antes de chegar no handler.

Na prática só metadata chega perto: ela aceita no máximo 20 chaves, cada chave até 40 caracteres, cada valor até 500 caracteres, e 4 KB no total. Uma lista de itens vai até 50 entradas.

Faixas de valor

Valor de uma cobrança PIX: de R$ 3,00 a R$ 100.000,00. Em centavos, de 300 a 10000000. Fora disso é 400 amount_too_small ou 400 amount_too_large. Em cobrança voucher o valor é na menor unidade da moeda local e o piso depende da moeda: MXN 7000, CLP 380000, COP 1300000 e PEN 1400 (perto de R$ 20). Veja Cobrança em moeda local.

A taxa nunca pode consumir a cobrança inteira. Um valor tão baixo que o líquido ficaria zero também responde 400 amount_too_small, mesmo estando acima de R$ 3,00.

Valor de um saque: mínimo de R$ 1,00, e o valor mais a taxa precisam caber no saldo disponível. Pode existir ainda um limite diário na sua conta, em valor e em quantidade; quando bate, a resposta é 409 daily_limit_exceeded com o limite e o usado em details.

Cobrança internacional: o mínimo é 500 centavos da moeda cobrada (5,00 euros, dólares ou libras).

Faixa de prazo

O prazo de expiração pedido na criação da cobrança vai de 5 minutos a 30 dias, em segundos: de 300 a 2592000. O padrão é uma hora. Fora da faixa é 400 invalid_expires_in.

Esse prazo é um pedido, e o processador pode encurtá-lo ou estendê-lo. A data que vale é a que volta na resposta. Detalhes em Expiração.

Próximo passo

Fundamentos fechados. Siga para Cobranças, o recurso principal da API.

Referência: Cria uma cobrança (PIX, voucher, cripto, cartão ou carteira).