invoice (fatura) representa a cobrança periódica de uma assinatura ou de itens cobrados manualmente de um cliente. Ela centraliza as informações de valores devidos e pagos, os itens cobrados, os descontos aplicados e as referências aos recursos financeiros que permitem o pagamento, como o payment_intent e o customer.
Na Chargefy, as invoices são geradas automaticamente pelo ciclo de faturamento de uma assinatura (subscription_cycle, subscription_create ou subscription_update) ou podem ser criadas de forma avulsa (manual) para cobranças específicas. Compras avulsas diretas (one-off) não geram invoices — essas passam direto pelos payment_intents para manter o fluxo leve e limpo.
Uma invoice pode estar em draft enquanto você revisa os itens e termos. O rascunho não é exibido ao comprador e retorna number, finalized_at, hosted_invoice_url e invoice_pdf_url como null. Na API, a criação continua finalizada por padrão; envie finalize: false para optar pelo rascunho. O painel salva inicialmente como rascunho.
Ao finalizar, a invoice recebe número e retrato atual do cliente, aplica o crédito disponível uma única vez e fica open ou paid. Itens, valores, vencimento e retrato do cliente ficam definitivos. A partir daí, corrija a cobrança cancelando a invoice e criando outra.
O campo hosted_invoice_url é a página pública dessa invoice em billing.chargefy.io/invoice/:token. O token é opaco e vale 30 dias desde a emissão; quando você recupera a invoice pela API, a resposta traz uma URL ativa. Abrir não renova o prazo. A página expirada permite solicitar outro acesso pelo e-mail cadastrado, sem alterar a dívida. Enquanto a invoice está open, essa página pode receber pagamento pelos métodos permitidos em payment_method_types. Depois que a invoice é paga, cancelada ou marcada como incobrável, uma URL ativa continua servindo para visualização do estado da fatura, sem aceitar novo pagamento.
Essa URL pertence a uma invoice específica. Ela não é um payment_link: payment links são URLs reutilizáveis de oferta que materializam checkout sessions novas a cada clique.
Data Object
Este é o formato retornado emcreate, get, itens de list e nos webhooks de fatura. invoice.deleted retorna apenas { id, object: "invoice", deleted: true }.
Condições de comissão de afiliado registradas: cada item contém
affiliation e
affiliate_fee_rate em pontos-base; [] indica ausência de comissão de afiliado.
Esta seleção não comprova recebimento: o pagamento registra o resultado de
cada participante. Encerrar uma parceria retira sua participação nas
próximas cobranças e preserva os valores e as parcelas já divididos.Valor devido na menor unidade da moeda (centavos em
brl). É imutável após a criação da invoice.Valor total na menor unidade da moeda (centavos em
brl), equivalente a amount_subtotal - amount_discount + amount_tax + surcharge_amount. Juros de parcelamento não entram no total.Quantas tentativas de pagamento esta fatura acumulou, do ponto de vista da
régua de recuperação. A primeira tentativa conta como
1; depois dela, apenas
as retentativas automáticas incrementam.Cobrar a fatura manualmente — por POST /v1/invoices/:id/pay ou pelo painel —
não move a régua. Isso é proposital: uma cobrança manual não deve consumir
as tentativas automáticas que ainda restam ao cliente.Por isso o valor não é o tamanho de payments.data[]. Uma tentativa manual
cria um pagamento sem contar, e uma retentativa que a régua pula — porque a
recusa anterior foi de um tipo que repetir não resolve — conta sem criar
pagamento nenhum.Payment method (
pm_*) escolhido para esta invoice. Quando a invoice é paga
sem payment_method explícito, a ordem de resolução é: payment_method do
request, default_payment_method da invoice, default_payment_method da
subscription, e default_payment_method do customer.URL pública ativa onde o cliente pode ver a invoice. Enquanto a invoice
está
open, a página também permite pagamento pelos métodos em
payment_method_types. O token da URL é opaco e pode ser renovado pela
Chargefy; não tente montá-lo manualmente.Valor de juros acumulado no momento da resposta, na menor unidade da moeda (centavos em
brl).Valor de multa acumulado no momento da resposta, na menor unidade da moeda (centavos em
brl).Data e hora ISO 8601 da próxima tentativa automática de cobrança.É
null quando a régua de recuperação terminou e sempre null quando
collection_method é send_invoice, já que nesse modo a Chargefy não cobra
automaticamente.Número legível da fatura, sequencial por cliente (ex:
K7M2-0001). Cada cliente
recebe um prefixo próprio e a numeração reinicia nele. Sempre presente: atribuído
na criação da fatura a partir do prefixo do cliente.true quando a invoice foi marcada como paga por um recebimento fora da
Chargefy, como dinheiro em espécie ou transferência direta, por
POST /v1/invoices/{id}/pay
com paid_out_of_band. Nenhuma cobrança liquidou essa invoice: não há
transação, taxa nem repasse associados ao valor.ID do payment intent (
pi_*) da invoice. Nasce junto com ela, na emissão,
sempre que há valor a receber, e fica em requires_payment_method até uma
tentativa ser armada nele (página hospedada, pay ou cobrança automática).
Cada tentativa é uma charge dentro desse mesmo intent. null apenas em
invoices sem nada a cobrar (valor zero).Condição de parcelamento congelada desta invoice — a mesma estrutura do
objeto Subscription, porém aplicada:
toda tentativa de pagamento desta invoice cobra exatamente o plano congelado
aqui, sem recálculo em retentativas.
payment_method_options vem null
numa invoice cobrada à vista. O plano é sempre { type: "fixed_count", interval: "month", count: 2..12 }.Repasse de tarifa pago pelo comprador, na menor unidade da moeda (centavos em
brl), já incluído em
amount_total. Só aparece numa invoice de compra por checkout com
has_surcharge; nas demais é 0. Veja Repassar a tarifa de venda ao
comprador.Operações
Eventos
Mudanças nesse objeto disparam os seguintes eventos: O payload sempre carrega o objetoinvoice completo em data.object.
