Faturas
Criar uma fatura
Cria uma invoice.
O valor de cada item e a soma de preço × quantidade devem caber em o teto da moeda (
Obrigatórios:
999999999 na menor unidade em brl), antes de descontos e juros. Valores acima retornam 400 amount_too_large, com param indicando o campo ou a coleção de itens.
Por padrão, cria e finaliza a invoice na mesma operação, preservando a resposta com hosted_invoice_url. Ela fica open quando há valor a receber, ou paid quando o total é zero ou o crédito do cliente cobre a dívida. Uma falha na finalização desfaz a criação.
Envie finalize: false para criar um rascunho (draft). Nesse estado, você pode editar os termos e itens, sem número definitivo, link público, consumo de crédito, pagamento ou envio de e-mail. Quando estiver pronto, finalize a fatura. Os dados financeiros e o retrato do cliente ficam fixos na finalização.
Uma invoice finalizada com valor a receber tem seu payment_intent em requires_payment_method. A cobrança acontece quando o cliente paga pela página hospedada, quando você chama pay ou issue_boleto, ou pela cobrança automática da assinatura.
Finaliza a invoice na criação. Envie
false para salvar um rascunho sem link público.customer e a cobrança em si (line_items ou amount).
Todo o resto tem padrão ou é resolvido pela Chargefy — inclusive o vencimento:
sem due_date nem days_until_due, vale o prazo padrão configurado em
Configurações → Assinaturas e faturamento → Faturas.
Sem line_items nem amount o request falha com 400; se os dois forem
enviados, line_items prevalece e amount é ignorado. Dentro de cada item de
line_items, a regra é estrita: exatamente um de price ou price_data
— os dois juntos ou nenhum dá erro 400.
Para uma cobrança avulsa (com vencimento, multa/juros e URL de fatura
para o cliente), envie due_date, defina late_fee/interest quando quiser
penalidades por atraso, e deixe delivery: "chargefy" para que a Chargefy
envie a fatura por email e cuide dos lembretes. Use amount quando a cobrança
não tiver produtos.
A resposta inclui hosted_invoice_url, uma URL pública ativa em
billing.chargefy.io/invoice/:token. Compartilhe esse campo quando quiser que o
cliente visualize ou pague a invoice manualmente. O token pertence à invoice
criada, pode ser renovado pela Chargefy, e não é um payment_link
reutilizável.
Plano fixo no cartão:
payment_method_options.credit_card.installments.plan com type: "fixed_count", interval: "month" e count entre 2 e o limite de parcelas configurado (máximo 12). O principal deve comportar pelo menos R$ 7,00 por parcela. Sem esse campo, não fixa um parcelamento na fatura.Dias antes do vencimento para lembrar. Inteiro não negativo; sem o campo, usa a configuração da organização.
Dias após o vencimento para lembrar. Inteiro não negativo; sem o campo, usa a configuração da organização.
Comissões de afiliados para vínculos ativos: cada item contém
affiliation (aff_*) e
affiliate_fee_rate, inteiro de 1 a 10000 pontos-base (3000 = 30%).
Os percentuais incidem em paralelo sobre o valor líquido da venda antes das
comissões de afiliados; a soma não pode ultrapassar 10000. Até 8 afiliados em venda
direta ou 7 com plataforma. Envie [] para remover a seleção.
Veja Comissões de afiliados.Valor total na menor unidade da moeda (centavos em
brl) (inteiro ≥ 0), quando a cobrança não tem
produtos. Vira um item de linha único com quantity: 1 e a description
enviada no top-level. Considerado apenas quando line_items está ausente ou
vazio.O teto depende da moeda. Em brl, o máximo é 999999999 na menor unidade. Acima do teto, a API retorna 400 amount_too_large com param e maximum_amount. Quando o valor já está associado a uma moeda, a resposta inclui currency.Itens da invoice, para cobranças com produtos. Obrigatório quando você não
envia
amount; deve ser um array não-vazio. Todos os itens usam a mesma
moeda da invoice.Moeda da fatura. Quando há uma assinatura vinculada, a fatura usa a moeda da
assinatura. Para faturas avulsas, vale a moeda comum dos itens ou, se eles
não informarem a moeda, a moeda padrão da organização. Uma divergência
retorna
400 currency_mismatch e indica o campo em error.param.Aceita hoje: brl. Maiúsculas valem como minúsculas (BRL é lido como brl); outra moeda retorna 400 com code: "unsupported_currency". Veja Moedas.Subscription (
sub_*) à qual a invoice pertence. É obrigatória quando
collection_method é charge_automatically, porque o worker de cobrança
automática processa invoices de assinatura. Para cobrança avulsa, use
send_invoice e compartilhe hosted_invoice_url.Vencimento como instante absoluto em RFC 3339, com
Z ou offset numérico
(ex.: 2026-06-10T12:00:00Z ou 2026-06-10T09:00:00-03:00). O instante é
preservado exatamente como enviado.Só é válido com collection_method igual a send_invoice, e é mutuamente
exclusivo com days_until_due — envie um ou outro. Sem nenhum dos dois, o
vencimento usa o prazo padrão da organização (Configurações → Assinaturas e faturamento → Faturas).Formatos recusados com 400:Número de dias, a partir da criação, até o vencimento. Só é válido com
collection_method igual a send_invoice, e é mutuamente exclusivo com
due_date.O vencimento resultante é ancorado ao meio-dia UTC do dia alvo: 0 vence hoje,
7 vence daqui a sete dias. A resposta devolve o due_date já resolvido.Descrição da invoice, exibida na fatura. Com
amount, também vira a
descrição do item de linha único.Permite pagamento após o vencimento (multa/juros acumulam, lembretes
continuam até o limite). Padrão:
true quando há late_fee ou interest;
senão, o padrão configurado na organização (Configurações → Assinaturas e faturamento → Faturas).Meios de pagamento permitidos na página da invoice. Padrão: os métodos
habilitados no checkout da organização (todos, quando não configurado).
Payment method salvo (
pm_*) escolhido como padrão desta invoice. Precisa
pertencer ao customer e estar válido. Ao pagar sem payment_method
explícito, a Chargefy tenta usar o padrão da invoice, depois o padrão da
subscription, e por fim o padrão do customer.O que a Chargefy resolve sozinha
payment_method_types— herdam os métodos habilitados no checkout da organização.allow_late_payment,late_fee,intereste o vencimento — campos omitidos seguem os padrões da organização (Configurações → Assinaturas e faturamento → Faturas);late_fee/interestcomnullexplícito desligam o encargo. Comlate_feeouinterestdefinidos,allow_late_paymentviratrueautomaticamente.- Envio e lembretes — com
delivery: "chargefy", a fatura é enviada por email na criação quando já está vencendo e os lembretes seguintes são agendados. - Snapshot do customer — nome, email, documento e endereço de cobrança são copiados do customer no momento da criação.
hosted_invoice_url— gerada (e renovada quando expira) pela Chargefy.amount→ item de linha — o valor avulso vira um item único comquantity: 1e adescriptionda invoice.

