Valores, datas e repetição

Valor monetário é string decimal

{ "amount": "100.00" }

Nunca 100.00 como número.

Um float em JSON perde precisão antes mesmo de chegar ao servidor: 0,1 não existe em ponto flutuante binário, e num extrato que soma milhares de linhas o erro se acumula até o total não bater.

Use decimal do seu lado também. Se a sua linguagem converte JSON em float automaticamente, force a leitura como string antes de somar.

Formato aceito: ^\d+(\.\d{1,2})?$ em BRL. Em cripto, a escala é a do ativo.

Datas

ISO-8601 em UTC, com Z:

2026-08-20T14:03:11Z

Vale para expiresAt, paidAt, createdAt, settlementDate e todos os outros.

Ativos

BRL, USD, USDT, BTC, ETH. O campo asset traz o código; a escala decimal varia por ativo, e é por isso que o valor é string.

Repetir uma chamada

Leituras (GET) são sempre seguras de repetir.

Escritas não são idempotentes por padrão: dois POST /charges iguais criam duas cobranças. Isso é intencional — duas vendas do mesmo valor no mesmo minuto são um caso real, e deduplicá-las automaticamente perderia uma.

O que fazer:

• guarde o id devolvido antes de qualquer retentativa;
• se a chamada falhou com timeout, consulte antes de repetir — a cobrança pode ter sido criada e a resposta ter se perdido no caminho;
• se falhou com 503, a operação não aconteceu e repetir é seguro.

Consultar em laço não é o caminho

Faça cache do saldo por alguns segundos: em fluxo normal ele não muda mais rápido que isso, e consultar em laço só consome o seu teto de requisições.

Para saber que algo aconteceu, use webhooks. Eles existem exatamente para você não precisar perguntar.