> ## 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.

# Pagamentos vs. invoices

> A diferença entre pagamento e fatura na Chargefy: o documento de cobrança de um cliente e a coleta do dinheiro, com exemplos de quando cada um existe.

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.

|                            | Pagamento (`payment_intent`)   | Fatura (`invoice`)                                     |
| -------------------------- | ------------------------------ | ------------------------------------------------------ |
| Responde                   | "Essa cobrança foi paga?"      | "O que estou cobrando desse cliente?"                  |
| Conteúdo                   | Valor, moeda, método, desfecho | Itens, período, vencimento, saldo, snapshot do cliente |
| Cliente                    | Opcional                       | Obrigatório                                            |
| Tem itens de linha?        | Não                            | Sim (`line_items`)                                     |
| Tem página e PDF próprios? | Não                            | Sim (`hosted_invoice_url`, `invoice_pdf_url`)          |
| Prefixo do ID              | `pi_`                          | `inv_`                                                 |
| Quantos por cobrança       | Um por tentativa de coleta     | Um documento, que pode acumular várias tentativas      |

## Quando existe fatura e quando não existe

<CardGroup cols={2}>
  <Card title="Sem fatura" icon="bolt">
    Compra única direta: link de pagamento, checkout avulso, cobrança pela API.
    O pagamento é o documento financeiro — não há o que faturar antes.
  </Card>

  <Card title="Com fatura" icon="file-invoice">
    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.
  </Card>
</CardGroup>

O campo `billing_reason` da fatura diz de onde ela veio:

| `billing_reason`      | Quando acontece                                           |
| --------------------- | --------------------------------------------------------- |
| `subscription_create` | Primeira fatura, no momento em que a assinatura é criada. |
| `subscription_cycle`  | Renovação periódica, a cada novo ciclo.                   |
| `subscription_update` | Ajuste de itens ou valor de uma assinatura existente.     |
| `manual`              | Cobrança avulsa criada por você via `POST /v1/invoices`.  |

<Note>
  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`.
</Note>

## 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.

| Momento                      | A fatura                                                     | O pagamento                                 |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Ciclo de março abre          | `inv_BYR7yMS5PKoyPEiG` nasce `open`, com `amount_due: 14900` | ainda não existe                            |
| Primeira cobrança            | continua `open`, `attempt_count: 1`                          | `pi_FwR94SrqRiPsQ9m8` é criado e confirmado |
| Cartão recusa                | continua `open`, `amount_remaining: 14900`                   | volta a `requires_payment_method`           |
| Retentativa dois dias depois | continua `open`, `attempt_count: 2`                          | novo pagamento é criado e confirmado        |
| Cartão aprova                | vira `paid`, `amount_remaining: 0`, `paid_at` preenchido     | fica `succeeded`                            |

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`.

<Warning>
  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`.
</Warning>

## Como os dois se ligam

```json theme={"theme":"css-variables"}
{
  "id": "inv_BYR7yMS5PKoyPEiG",
  "object": "invoice",
  "amount_due": 14900,
  "amount_remaining": 0,
  "billing_reason": "subscription_cycle",
  "customer": "cus_rvaJTZBW2D3zPbhi",
  "latest_charge": "ch_Q7xW4pL9kR3sTM2n",
  "payment_intent": "pi_FwR94SrqRiPsQ9m8",
  "status": "paid",
  "subscription": "sub_nCyEAQahY4bHDV9H",
  "...": "demais campos da fatura"
}
```

```json theme={"theme":"css-variables"}
{
  "id": "pi_FwR94SrqRiPsQ9m8",
  "object": "payment_intent",
  "amount": 14900,
  "customer": "cus_rvaJTZBW2D3zPbhi",
  "invoice": "inv_BYR7yMS5PKoyPEiG",
  "latest_charge": "ch_Q7xW4pL9kR3sTM2n",
  "status": "succeeded",
  "...": "demais campos do pagamento"
}
```

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ê

| Objeto               | Nasce de                                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| Fatura de assinatura | O ciclo de faturamento, automaticamente                                                                         |
| Fatura avulsa        | Você, com `POST /v1/invoices`                                                                                   |
| Pagamento de fatura  | A cobrança da fatura — automática (`charge_automatically`) ou disparada por você (`POST /v1/invoices/{id}/pay`) |
| Pagamento avulso     | Você, com `POST /v1/payment-intents`, ou o checkout                                                             |

<Info>
  **A fatura guarda um retrato do cliente**

  Quando 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.
</Info>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Todo pagamento tem uma fatura?">
    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.
  </Accordion>

  <Accordion title="Uma fatura pode ter vários pagamentos?">
    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.
  </Accordion>

  <Accordion title="Cancelar o pagamento cancela a fatura?">
    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`.
  </Accordion>

  <Accordion title="Qual dos dois eu guardo no meu banco?">
    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.
  </Accordion>

  <Accordion title="Onde vejo o que entrou na conta depois de a fatura ser paga?">
    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](/payments/payments-vs-transactions).
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Faturas" icon="file-invoice" href="/payments/invoices">
    O objeto completo: ciclo de vida, itens de linha, página hospedada e ações.
  </Card>

  <Card title="Assinaturas" icon="arrows-rotate" href="/payments/subscriptions">
    De onde vem a maior parte das faturas.
  </Card>

  <Card title="Pagamentos vs. cobranças" icon="receipt" href="/payments/payments-vs-charges">
    O processo da venda e cada tentativa dentro dele.
  </Card>

  <Card title="Objeto invoice" icon="cube" href="/api-reference/invoices/object">
    Contrato público completo da fatura.
  </Card>
</CardGroup>