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

# Evento invoice.finalized

> Evento invoice.finalized.

## Evento `invoice.finalized`

Disparado na finalização de um rascunho, inclusive na criação finalizada por padrão pela API. Os itens, termos e dados do cliente já estão congelados. O objeto fica `open` ou `paid` quando não existe saldo a receber. Repetir a finalização não emite outro evento.

`data.object` usa o mesmo shape de [`GET /v1/invoices/:id`](https://docs.chargefy.io/api-reference/invoices/get).
O campo `data.object.hosted_invoice_url` é uma URL ativa da página pública
dessa invoice.

> [!NOTE]
>
> Compras avulsas seguem o fluxo de `payment_intent` e não têm invoice. A
> exceção é a compra por checkout criada com `invoice_creation: true`: a invoice
> nasce depois do pagamento, e este evento já chega com ela paga.

## Como processar

* Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.
* Use `data.object.id` (`inv_*`) como chave da invoice no seu sistema.
* Salve `status`, `due_date`, `amount_due_now`, `amount_remaining` e `hosted_invoice_url` para orientar a cobrança.
* Use `line_items` como retrato dos itens faturados; valores e períodos já estão fixos na criação.
* Use `customer`, `subscription` e `metadata` para correlacionar a invoice com seu cliente, assinatura ou pedido interno.
* Se `payment_intent` e `latest_charge` vierem `null`, isso apenas indica que nenhuma tentativa de pagamento foi criada ainda.

## Campos importantes

| Campo | O que observar |
| - | - |
| `data.object.status` | Normalmente `open` neste evento, pronta para pagamento. |
| `billing_reason` | Explica por que a invoice foi gerada: assinatura, atualização ou cobrança manual. |
| `collection_method` | Define se a cobrança será automática ou se o cliente deve pagar pelo link da invoice. |
| `hosted_invoice_url` | URL pública ativa para visualizar e pagar enquanto a invoice está `open`. |
| `payment_method_types` | Meios de pagamento permitidos nesta invoice. |
| `amount_due_now` / `amount_remaining` | Valores em centavos que ainda precisam ser pagos. |
| `line_items` | Retrato dos produtos, preços, períodos e quantidades cobradas. |
| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |

## Status e variações

| Campo | Valores relevantes |
| - | - |
| `status` | `open` indica fatura em aberto; `paid`, `void` e `uncollectible` aparecem em eventos posteriores. |
| `collection_method` | `charge_automatically` tenta cobrar um método salvo; `send_invoice` indica cobrança manual via link. |
| `allow_late_payment` | Quando `true`, a invoice pode aceitar pagamento após o vencimento conforme as regras de juros e multa. |

## Exemplo de payload

```json theme={"theme":"css-variables"}
{
  "id": "evt_caQXYiphJsdFvJx6",
  "object": "event",
  "created_at": "2026-05-19T18:00:00Z",
  "data": {
    "object": {
      "id": "inv_rEzHpCHGPCjXhwP9",
      "object": "invoice",
      "affiliates": [],
      "allow_late_payment": true,
      "amount_credit_balance_applied": 0,
      "amount_discount": 0,
      "amount_due": 9990,
      "amount_due_now": 9990,
      "amount_paid": 0,
      "amount_remaining": 9990,
      "amount_subtotal": 9990,
      "amount_tax": 0,
      "amount_total": 9990,
      "attempt_count": 0,
      "billing_reason": "subscription_cycle",
      "collection_method": "send_invoice",
      "created_at": "2026-05-19T18:00:00Z",
      "currency": "brl",
      "customer": "cus_c1TJCVCDL1k3m33H",
      "customer_billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "line2": "Conjunto 101",
        "postal_code": "01310-100",
        "state": "SP"
      },
      "customer_billing_name": "Cliente Exemplo",
      "customer_document": "12345678901",
      "customer_document_type": "cpf",
      "customer_email": "nome@email.com",
      "customer_name": "Cliente Exemplo",
      "default_payment_method": null,
      "description": "Assinatura Plano Pro - Maio/2026",
      "due_date": "2026-05-26T12:00:00Z",
      "ending_balance": 0,
      "finalized_at": "2026-05-19T18:00:00Z",
      "hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
      "interest": {
        "percent_per_month": 1
      },
      "interest_amount": null,
      "invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_rEzHpCHGPCjXhwP9.pdf",
      "late_fee": {
        "type": "fixed",
        "value": 200
      },
      "late_fee_amount": null,
      "latest_charge": null,
      "line_items": [
        {
          "id": "ili_XW34o11fuLirNLY8",
          "object": "invoice_line_item",
          "amount_discount": 0,
          "amount_subtotal": 9990,
          "amount_tax": 0,
          "amount_total": 9990,
          "currency": "brl",
          "description": "Plano mensal",
          "discountable": true,
          "metadata": {},
          "period_end": "2026-06-19T18:00:00Z",
          "period_start": "2026-05-19T18:00:00Z",
          "position": 0,
          "price": "price_EDJuX4wGB9qGLQHv",
          "price_data": null,
          "product": "prod_gkS8zPM2Q1fkET7N",
          "proration": false,
          "proration_details": {},
          "quantity": 1,
          "recurring_interval": "month",
          "recurring_interval_count": 1,
          "subscription_item": "si_adRx8RCQdJLMzKDt",
          "unit_amount": 9990
        }
      ],
      "livemode": true,
      "marked_uncollectible_at": null,
      "metadata": {},
      "next_payment_attempt": null,
      "number": "K7M2-0001",
      "paid_at": null,
      "paid_out_of_band": false,
      "payment_intent": "pi_Nw4zL8qJm2Vd7XkP",
      "payment_method_types": [
        "pix",
        "boleto",
        "credit_card"
      ],
      "payment_settings": {
        "payment_method_options": null
      },
      "starting_balance": 0,
      "statement_descriptor": "PLANO PRO",
      "status": "open",
      "subscription": "sub_Q8VBBrbJF5CYo12p",
      "surcharge_amount": 0,
      "updated_at": "2026-05-19T18:00:00Z",
      "voided_at": null
    }
  },
  "livemode": true,
  "organization": "org_17izqCSa1YTBX1vx",
  "request": {
    "id": "req_oFHjPyRzqfFDYK4t"
  },
  "type": "invoice.finalized"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.