> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Datas, fusos e moedas
> Como enviar timestamps, valores monetários e moedas na API.
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.
| Valor em reais | Inteiro enviado |
| -------------- | --------------- |
| R\$ 0,01 | `1` |
| R\$ 10,00 | `1000` |
| R\$ 199,90 | `19990` |
```json theme={"theme":"css-variables"}
{
"amount": 19990,
"currency": "brl"
}
```
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**:
| Percentual | Inteiro enviado |
| ---------- | --------------- |
| 1% | `100` |
| 3,99% | `399` |
| 100% | `10000` |
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.
```json POST /v1/invoices theme={"theme":"css-variables"}
{
"collection_method": "send_invoice",
"customer": "cus_HYsoex1XSBJMuU8a",
"days_until_due": 7
}
```
`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.
```json POST /v1/invoices theme={"theme":"css-variables"}
{
"collection_method": "send_invoice",
"customer": "cus_HYsoex1XSBJMuU8a",
"due_date": "2026-08-10T12:00:00Z"
}
```
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
| Valor enviado | Resultado |
| --------------------------- | -------------------------------------------------------- |
| `2026-08-10T12:00:00Z` | Aceito. |
| `2026-08-10T09:00:00-03:00` | Aceito — mesmo instante do exemplo acima. |
| `2026-08-10` | `400`. Nomeia um dia civil sem dizer de qual calendário. |
| `2026-08-10T12:00:00` | `400`. Parece um instante, mas não tem fuso. |
| `2026-02-30T12:00:00Z` | `400`. Não é uma data real. |
### Erros comuns
| Valor enviado | Por que falha | Como corrigir |
| ---------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| `2026-08-10` | Informa um dia, mas não um instante nem um fuso. | Use `days_until_due` ou envie `2026-08-10T12:00:00Z`. |
| `2026-08-10T12:00:00` | Tem horário, mas não informa o fuso. | Acrescente `Z` ou um offset numérico, como `-03:00`. |
| `2026-02-30T12:00:00Z` | A data não existe no calendário. | Envie um timestamp RFC 3339 válido. |
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:
| Instante | São Paulo (UTC−3) | Manaus (UTC−4) | Tóquio (UTC+9) |
| ---------------------- | ----------------- | -------------- | -------------- |
| `2026-08-10T00:00:00Z` | **09/08**, 21h | **09/08**, 20h | 10/08, 9h |
| `2026-08-10T12:00:00Z` | 10/08, 9h | 10/08, 8h | 10/08, 21h |
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:
| O que muda | O que não muda |
| -------------------------------------------- | ------------------------------------------------ |
| Datas e horas exibidas no Dashboard. | O `due_date` já gravado em cada invoice. |
| Como a sua equipe lê relatórios e listas. | Qualquer timestamp devolvido pela API. |
| O dia mostrado no date-picker de vencimento. | O instante que o date-picker grava. |
| — | Quando a régua de cobrança dispara. |
| — | Quando multa e juros passam a contar. |
| — | O que o cliente vê na fatura hosted e no e-mail. |
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`:
```json theme={"theme":"css-variables"}
"created": "2026-08-03T14:22:07Z"
```
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
Vencimento, multa, juros e envio da fatura.
Ciclos, régua de cobrança e faturas recorrentes.
Como ler `code`, `message` e `param`.
Defina `unit_amount` e `currency` de um produto.