Skip to main content
A fatura é o documento: o que você está cobrando de um cliente, quanto, por qual período e até quando. O pagamento é a coleta: a tentativa de tirar esse dinheiro de um meio de pagamento. A diferença prática está numa pergunta só: existe algo a apresentar ao cliente antes de cobrar? Se sim, há fatura. Se não, o pagamento se basta.

​
Quando existe fatura e quando não existe

Sem fatura

Compra única direta: link de pagamento, checkout avulso, cobrança pela API. O pagamento é o documento financeiro — não há o que faturar antes.

Com fatura

Ciclo de assinatura, cobrança avulsa de um cliente, qualquer cobrança que precise de itens, vencimento, boleto com prazo ou histórico auditável.
O campo billing_reason da fatura diz de onde ela veio:
No Brasil, a fatura da Chargefy não substitui nota fiscal. Ela é um documento operacional de cobrança e conciliação. Para NF-e ou NFS-e, use o sistema fiscal apropriado e relacione o identificador pela sua integração ou por metadata.

​
O exemplo que explica a diferença

Uma assinatura mensal de R$ 149,00. O cartão do cliente falha na renovação de março e é aprovado dois dias depois, na retentativa. A fatura é uma só durante todo o mês de março: ela é o documento daquele ciclo. Os pagamentos são as tentativas de coletar o valor dela. O campo payment_intent da fatura aponta sempre para a tentativa mais recente. Compare com uma compra única de R$ 99,00 por link de pagamento: existe apenas o pagamento pi_*, com invoice: null. Não há ciclo, não há vencimento, não há documento a apresentar — o comprador clica, paga e a operação encerra.

​
Para que serve cada um

Na prática:
  • Liberar acesso ou entregar o pedido → escute o pagamento (payment.intent.succeeded) ou a fatura (invoice.paid), conforme o fluxo. Numa assinatura, invoice.paid é o sinal certo: ele significa que o ciclo inteiro foi quitado.
  • Mostrar ao cliente o que está sendo cobrado → é a fatura. Ela tem os itens de linha, o período de cada item, os descontos e o total.
  • Enviar uma cobrança com prazo → é a fatura. Ela tem due_date, hosted_invoice_url para o cliente pagar e collection_method: "send_invoice" para o caso em que o cliente paga por conta própria.
  • Saber se o dinheiro entrou agora → é o pagamento e o status dele.
  • Saber se ainda falta cobrar algo do cliente → é a fatura e o amount_remaining.
Numa assinatura, não conclua o ciclo pelo pagamento sozinho. Uma fatura pode ter mais de uma tentativa, e um pagamento aprovado que quitou parte do saldo não fecha o documento. Quem fecha o ciclo é invoice.paid — verifique amount_remaining.

​
Como os dois se ligam

O ponteiro vale nos dois sentidos: a fatura indica a tentativa mais recente em payment_intent, e o pagamento indica a fatura de origem em invoice. Num pagamento avulso, invoice é null.

​
Quem cria o quê

A fatura guarda um retrato do clienteQuando a fatura é gerada, ela captura customer_name, customer_email, customer_document e o endereço de cobrança daquele momento. Esse snapshot não muda depois, mesmo que o cadastro do cliente mude — o documento continua refletindo quem era o cliente quando a cobrança foi emitida. O pagamento não tem esse retrato: ele aponta para o cadastro atual.

​
Perguntas frequentes

Não. Compra única direta não gera fatura: o campo invoice do pagamento fica null. A fatura existe quando há um documento de cobrança a representar.
Sim. Cada tentativa de coletar o valor cria um pagamento, e payment_intent reflete a mais recente. O attempt_count conta as tentativas e o amount_remaining diz se ainda há saldo em aberto.
Não. São ciclos de vida separados: um pagamento cancelado deixa a fatura em open, pronta para nova tentativa. Para encerrar o documento sem receber, use POST /v1/invoices/{id}/void.
Os dois, com papéis diferentes. Guarde a fatura para representar o que o cliente deve, e o pagamento para acompanhar a tentativa em curso. Numa venda avulsa, só o pagamento existe.
Nas transações. A fatura diz quanto foi cobrado; o extrato diz quanto entrou depois das taxas e quando liquida — veja Pagamentos vs. Transações.

​
Próximos passos

Faturas

O objeto completo: ciclo de vida, itens de linha, página hospedada e ações.

Assinaturas

De onde vem a maior parte das faturas.

Pagamentos vs. cobranças

O processo da venda e cada tentativa dentro dele.

Objeto invoice

Contrato público completo da fatura.