Pular para o conteúdo principal
Toda data na API da Chargefy é um instante absoluto em UTC — um ponto único na linha do tempo, não um dia no calendário de alguém. Isso vale para o que você envia e para o que você recebe. Na prática, estas regras resolvem quase tudo:
  • Para enviar um vencimento, prefira days_until_due. A Chargefy resolve o instante para você.
  • Se enviar due_date, mande o timestamp completo com Z ou offset numérico — 2026-08-10T12:00:00Z. Só a data (2026-08-10) devolve 400.
  • 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: 19990 representa R$ 199,90.
  • A API aceita hoje uma moeda, brl, sempre em minúsculas. Sem currency, vale a moeda padrão da organização.

Valores monetários e moeda

Envie inteiros na menor unidade da moeda

Campos como amount, unit_amount, fee_amount, net_amount e outros com sufixo _amount usam a menor unidade da moeda. Para brl, essa unidade é o centavo.
Não envie 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.
Ao converter um valor decimal recebido do usuário, arredonde uma única vez para a menor unidade da moeda (centavos em brl) antes de chamar a API. Depois disso, mantenha o valor inteiro em cálculos, persistência, requests e webhooks.

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
Se você está convertendo um dia civil em instante do seu lado, use meio-dia UTC. A seção seguinte explica por quê.

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 o days_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 como America/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 em send_invoice entra em atraso no vencimento.
  • Ciclos de assinatura — current_period_start e current_period_end são instantes, e a renovação acontece no instante do fim do período.
Se a multa de uma fatura entrou “às 21h de ontem” no seu relógio, é isso: o vencimento era meia-noite UTC e 24 horas se completaram ali.

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, com Z:
Ao exibir para um usuário, converta para o fuso de quem está lendo. Ao comparar, guardar ou fazer conta, use o instante como veio.

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