Skip to main content
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 da organização no Dashboard não participa de cobrança. Ele só muda o que a sua equipe lê na tela.
  • Valores monetários são inteiros na menor unidade da moeda. Em BRL, isso significa centavos: 19990 representa R$ 199,90.
  • brl é a moeda padrão das contas Chargefy e aparece em minúsculas nos contratos públicos.

​
Valores monetários e moeda

​
Envie valores inteiros em centavos

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 para reais apenas na interface.
Ao converter um valor decimal recebido do usuário, arredonde uma única vez para centavos antes de chamar a API. Depois disso, mantenha o valor inteiro em cálculos, persistência, requests e webhooks.

​
BRL é a moeda padrão

Todas as contas Chargefy usam BRL como moeda padrão. Nos contratos públicos, o código segue ISO 4217 em minúsculas: brl. Alguns endpoints exigem currency; outros herdam a moeda de um preço, assinatura ou pagamento relacionado. Siga o contrato de cada endpoint e, quando o campo for enviado, use 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.

​
Os dois fusos que não se misturam

A palavra “fuso” aparece em dois lugares do produto, e eles não se comunicam. O fuso do Dashboard é dashboard_settings.timezone na organização — um identificador IANA como America/Sao_Paulo. Ele existe para que a sua equipe leia horários no relógio dela. É preferência de exibição, para todos os membros da organização. 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 fuso do Dashboard muda isto: A última linha costuma surpreender: hosted e e-mail renderizam no fuso do cliente, não no da sua organização. 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/checkout-sessions/:id/confirm e em POST /v1/payment-intents/:id/regenerate-boleto, aceita dia civil no formato YYYY-MM-DD (padrão: 3 dias depois da confirmação). É 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.