- Para enviar um vencimento, prefira
days_until_due. A Chargefy resolve o instante para você. - Se enviar
due_date, mande o timestamp completo comZou offset numérico —2026-08-10T12:00:00Z. Só a data (2026-08-10) devolve400. - O fuso do Dashboard é preferência de cada pessoa da equipe, não da organização. Ele só muda o que aquela pessoa lê na tela e não participa de cobrança.
- Valores monetários são inteiros na menor unidade da moeda. Em BRL, isso
significa centavos:
19990representa R$ 199,90. - A API aceita hoje uma moeda,
brl, sempre em minúsculas. Semcurrency, vale a moeda padrão da organização.
Valores monetários e moeda
Envie inteiros na menor unidade da moeda
Campos comoamount, unit_amount, fee_amount, net_amount e outros com
sufixo _amount usam a menor unidade da moeda. Para brl, essa unidade é o
centavo.
199.90, "199,90" nem "R$ 199,90". Use um inteiro e faça a
formatação na moeda indicada pelo campo currency apenas na interface.
Moedas
O Dashboard abre os relatórios monetários na moeda padrão da organização. Quando o período apresenta outra moeda, o seletor permite consultar os totais por moeda. Vendas usam a moeda da cobrança. Recebíveis usam a moeda do saldo. A Chargefy processa hoje uma moeda:brl, o real brasileiro. O código
segue a ISO 4217 e aparece sempre em minúsculas em requests, responses e
webhooks.
Moeda padrão da organização. Toda organização tem um país (
country) e uma
moeda padrão (default_currency), definidos com a conta: hoje, BR e brl
para todas. Os dois aparecem no
objeto organization e são só de leitura.
Quando a request não informa currency num pagamento, numa fatura ou numa
prévia, vale a moeda padrão da organização em que a request atua. Preços e os
prices[] de um produto exigem currency.
Moeda do objeto pai. Valores dentro de um objeto, como itens, linhas da
fatura e descontos aplicados, estão na moeda do objeto que os contém. Um
pagamento de amount: 19990 com currency: "brl" tem todos os valores
aninhados em brl.
A lista pode crescer. Ao ler objetos, trate currency como texto: uma
moeda habilitada no futuro não muda o formato dos campos.
Para listar só os preços de uma moeda, use GET /v1/prices?currency=brl.
O campo
currency identifica a unidade do valor; ele não converte dinheiro.
amount: 19990 com currency: "brl" continua significando R$ 199,90 em
requests, responses e webhooks.Percentuais usam basis points
Campos terminados em_rate não são valores monetários. Eles usam basis
points:
Assim,
fee_amount: 399 significa R$ 3,99, enquanto fee_rate: 399 significa
3,99%. O nome do campo define a unidade.
Enviando um vencimento
due_date e days_until_due são mutuamente exclusivos e só valem quando
collection_method é send_invoice. Um dos dois é obrigatório nesse modo; em
charge_automatically os dois são recusados e a invoice fica sem vencimento.
days_until_due — o caminho recomendado
Quando a regra de negócio é “vence em N dias”, esse é o campo. Você não escolhe
horário, e o vencimento resultante já nasce no instante seguro.
POST /v1/invoices
0 vence hoje, 7 vence daqui a sete dias. A resposta devolve o due_date já
resolvido, ancorado ao meio-dia UTC do dia alvo.
due_date — quando o instante é seu
Use quando o vencimento vem de um contrato, de uma migração ou de um sistema que
já tem a data definida. O instante é preservado exatamente como enviado — a
Chargefy não move o horário que você escolheu.
POST /v1/invoices
O que é aceito
Erros comuns
Todos esses casos retornam
400 invalid_request com
error.param: "due_date".
A recusa é proposital. 2026-08-10 obrigaria o servidor a adivinhar de quem é
esse dia 10 — o seu, o do seu cliente, ou o do datacenter. Adivinhar erraria uma
parte dos casos em silêncio, e um vencimento errado só aparece depois de cobrar.
Por que uma data “muda” de dia
Um instante é um ponto único no tempo. A leitura dele depende de onde a pessoa está. O mesmo instante vira dias diferentes em relógios diferentes — e é aí que nasce a confusão de “o vencimento mudou sozinho”. Compare os dois horários possíveis para um vencimento no dia 10 de agosto:
Na primeira linha, o cliente em Manaus abre a fatura e lê 09/08 num
vencimento que você criou para o dia 10. Nada quebrou: meia-noite em UTC ainda é
ontem à noite em quase todo o Brasil.
Na segunda linha, todo mundo lê 10/08.
A âncora de meio-dia
Por isso, sempre que a Chargefy converte um dia civil em instante — o date-picker do Dashboard e odays_until_due — ancoramos em 12:00:00Z, não em
meia-noite.
Meio-dia deixa cerca de 12 horas de folga para cada lado. Todo fuso de UTC−12 a
UTC+11 lê o mesmo dia do calendário, o que cobre o mundo inteiro com margem — o
Brasil vai de UTC−2 a UTC−5. Meia-noite não tem folga nenhuma: qualquer
deslocamento para oeste já joga a leitura para o dia anterior.
Quando você envia due_date explícito, a escolha é sua e nós preservamos. A
recomendação de meio-dia continua valendo pelo mesmo motivo.
O fuso é de quem lê, não da cobrança
No Dashboard, cada pessoa escolhe o próprio fuso nas preferências da conta — um identificador IANA comoAmerica/Sao_Paulo. Duas pessoas da mesma equipe
podem ler o mesmo pagamento em relógios diferentes. A organização não tem fuso,
e a API não expõe essa preferência.
A cobrança não tem fuso. Vencimentos, ciclos de assinatura, jobs, webhooks e
todos os timestamps da API são instantes absolutos em UTC.
Trocar o seu fuso no Dashboard muda isto:
A última linha costuma surpreender: hosted e e-mail renderizam no fuso do
cliente, não no de quem opera o Dashboard. Faz sentido — quem está lendo
aquela tela é o comprador, e o que importa é o dia no relógio dele.
Nenhuma invoice carrega um snapshot de fuso. Isso é deliberado: mudar uma
preferência de tela nunca pode reinterpretar dinheiro que já foi cobrado.
O que mais conta em UTC
Vencimento não é o único lugar onde tempo vira regra de negócio. Tudo abaixo conta períodos de 24 horas absolutas, sem calendário e sem fuso:- Multa e juros — “1 dia de atraso” é 24 horas depois do instante do vencimento, não a virada do dia no seu relógio.
- Lembretes da régua de cobrança — os offsets são contados a partir do mesmo instante.
past_due— uma assinatura emsend_invoiceentra em atraso no vencimento.- Ciclos de assinatura —
current_period_startecurrent_period_endsão instantes, e a renovação acontece no instante do fim do período.
Exceção: boleto_due_date
Um campo foge do padrão, e vale conhecer para não se confundir.
boleto_due_date, em POST /v1/payment-intents/:id/regenerate_boleto, aceita
dia civil no formato YYYY-MM-DD, de hoje em diante no calendário de
Brasília. Sem ele, o boleto de uma fatura vence com a fatura, inclusive hoje;
fatura já vencida e os demais casos vencem 3 dias depois de hoje. É o vencimento impresso no boleto, um documento que existe no
calendário bancário brasileiro — não um instante.
O due_date que volta dentro de payment_data, na resposta e nos webhooks de
checkout, é o vencimento registrado para aquele boleto. Ele não segue a âncora de
meio-dia descrita acima.
Formato dos timestamps
Todo timestamp devolvido pela API é RFC 3339 em UTC, comZ:
Próximos passos
Criar uma invoice
Vencimento, multa, juros e envio da fatura.
Como funciona uma assinatura
Ciclos, régua de cobrança e faturas recorrentes.
Erros
Como ler
code, message e param.Criar um preço
Defina
unit_amount e currency de um produto.Moeda da venda e moeda do saldo
A cobrança, a fatura e o estorno usam a moeda da venda. No extrato, cada lançamento usa a moeda do saldo da organização que recebe o valor. O campocurrency do lançamento indica a unidade de amount, fee_amount, net_amount e dos itens de taxa.
Use GET /v1/transactions?currency=brl para filtrar o extrato. Some net_amount por moeda ao conciliar várias páginas. O campo exchange_rate representa a taxa da moeda da venda para a do saldo e retorna null hoje.
