> ## 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. cobranças

> A diferença entre pagamento e cobrança na Chargefy: o processo da venda e cada tentativa concreta de mover dinheiro, com exemplos de quando usar cada um.

O **pagamento** é a venda inteira. A **cobrança** é cada tentativa de tirar o
dinheiro do meio de pagamento. Uma venda pode precisar de várias tentativas até
dar certo — e é exatamente por isso que os dois objetos existem separados.

|                  | Pagamento (`payment_intent`)         | Cobrança (`charge`)                       |
| ---------------- | ------------------------------------ | ----------------------------------------- |
| Responde         | "Essa venda foi paga?"               | "Essa tentativa deu certo?"               |
| Quantidade       | Um por venda                         | Um por tentativa executada                |
| Quem cria        | Você, pela API ou pelo checkout      | O sistema, ao confirmar o pagamento       |
| Muda de estado?  | Sim, ao longo do ciclo               | Não: cada tentativa é um registro fechado |
| Prefixo do ID    | `pi_`                                | `ch_`                                     |
| Escrita pela API | Criar, confirmar, capturar, cancelar | Nenhuma — é somente leitura               |

<Info>
  **Você nunca cria uma cobrança**

  A cobrança é materializada pelo sistema quando um pagamento é confirmado. Para
  cobrar alguém, você cria e confirma um pagamento; a cobrança aparece como
  consequência e o pagamento aponta a mais recente em `latest_charge`.
</Info>

## O exemplo que explica a diferença

Uma compra de R\$ 99,00 no cartão. O comprador erra o CVV, o banco recusa, ele
corrige e a segunda tentativa passa.

| Momento                  | O pagamento                                                    | A cobrança                                       |
| ------------------------ | -------------------------------------------------------------- | ------------------------------------------------ |
| Comprador clica em pagar | `pi_FwR94SrqRiPsQ9m8` nasce em `requires_confirmation`         | ainda não existe                                 |
| Primeira confirmação     | vai para `processing`                                          | nasce `ch_FC8rQHJ2hP5guUY6`                      |
| Banco recusa             | volta para `requires_payment_method`, com `last_payment_error` | `ch_FC8rQHJ2hP5guUY6` fica `failed`, para sempre |
| Comprador corrige o CVV  | o **mesmo** `pi_FwR94SrqRiPsQ9m8` é confirmado de novo         | nasce `ch_Q7xW4pL9kR3sTM2n`                      |
| Banco aprova             | vai para `succeeded`                                           | `ch_Q7xW4pL9kR3sTM2n` fica `succeeded`           |

No fim: **um pagamento, duas cobranças**. O `latest_charge` do pagamento aponta
para a segunda. A primeira continua no histórico, com o código e a mensagem da
recusa — é ela que responde "por que o cartão do cliente não passou".

<Note>
  Uma recusa **não** encerra o pagamento. Ele volta para
  `requires_payment_method` e o mesmo objeto aceita nova confirmação, com o
  cartão corrigido ou com outro cartão. O limite é de **10 tentativas por
  pagamento** — cada tentativa executada vira uma cobrança.
</Note>

## Para que serve cada um

<CardGroup cols={2}>
  <Card title="Use o pagamento para" icon="arrow-right-arrow-left">
    Decidir se libera o pedido, o acesso ou a assinatura. É o objeto que carrega
    o desfecho da venda e o que você guarda no seu banco.
  </Card>

  <Card title="Use a cobrança para" icon="magnifying-glass">
    Investigar uma tentativa: qual cartão foi usado, qual bandeira, qual o
    código da recusa, quanto foi capturado, quanto já foi reembolsado.
  </Card>
</CardGroup>

Na prática:

* **Liberar o produto** → escute `payment.intent.succeeded` e olhe o `status` do
  pagamento. Nunca some cobranças para descobrir se a venda foi paga.
* **Explicar uma recusa ao cliente** → abra a cobrança em `latest_charge` e leia
  `payment_error`. O [catálogo de códigos de falha](/api-reference/charges/failure-codes)
  diz o que cada motivo significa e se vale tentar de novo.
* **Reembolsar** → o reembolso acontece **sobre a cobrança**, não sobre o
  pagamento. É a cobrança que tem `amount_captured`, `amount_refunded` e a lista
  de `refunds`.
* **Mostrar histórico financeiro** → liste as cobranças do cliente; cada linha é
  uma tentativa datada, com valor e desfecho.

## Como os dois se ligam

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

```json theme={"theme":"css-variables"}
{
  "id": "ch_Q7xW4pL9kR3sTM2n",
  "object": "charge",
  "amount": 9900,
  "paid": true,
  "payment_intent": "pi_FwR94SrqRiPsQ9m8",
  "status": "succeeded",
  "...": "demais campos da cobrança"
}
```

O ponteiro vale nos dois sentidos: o pagamento indica a tentativa mais recente
em `latest_charge`, e toda cobrança aponta de volta em `payment_intent`. Para
ver **todas** as tentativas de um pagamento, liste as cobranças filtrando por
`payment_intent`.

## Estados que não são a mesma coisa

Os dois objetos têm um campo `status`, e eles não significam a mesma coisa.

| Pagamento                                                                                                                        | Cobrança                                                   |
| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `requires_capture`, `succeeded`, `canceled` | `pending`, `processing`, `succeeded`, `failed`, `canceled` |
| Descreve o que **falta** para a venda ser paga                                                                                   | Descreve o desfecho **daquela** tentativa                  |
| Volta atrás: uma recusa devolve o pagamento a `requires_payment_method`                                                          | Nunca volta atrás: `failed` é definitivo naquele registro  |

<Warning>
  Um pagamento em `requires_payment_method` com uma cobrança `failed` no
  histórico **não** é uma venda perdida — é uma venda que ainda pode ser paga.
  Tratar as duas situações como iguais é o erro mais comum de quem concilia pela
  cobrança em vez do pagamento.
</Warning>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Um pagamento pode existir sem nenhuma cobrança?">
    Sim. Enquanto ninguém confirmou o pagamento — ou quando ele foi cancelado
    antes de qualquer tentativa — não existe cobrança alguma. `latest_charge`
    fica `null`.
  </Accordion>

  <Accordion title="Uma cobrança pode existir sem pagamento?">
    Não. Toda cobrança nasce da confirmação de um pagamento e aponta para ele em
    `payment_intent`.
  </Accordion>

  <Accordion title="Um Pix regenerado cria uma cobrança nova?">
    Sim. Cada tentativa executada é uma cobrança própria, mesmo que o pagamento
    e o ID `pi_*` continuem os mesmos.
  </Accordion>

  <Accordion title="Devo guardar o ID da cobrança ou do pagamento no meu banco?">
    Guarde o **pagamento** (`pi_*`) como relação principal do seu pedido: ele é
    estável durante todo o ciclo. As cobranças você alcança a partir dele quando
    precisar investigar.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobranças" icon="receipt" href="/payments/charges">
    O objeto completo: campos, status, detalhes do método e motivo da falha.
  </Card>

  <Card title="Pagamentos vs. transações" icon="scale-balanced" href="/payments/payments-vs-transactions">
    Como a cobrança aprovada vira dinheiro no seu extrato.
  </Card>

  <Card title="Códigos de falha" icon="triangle-exclamation" href="/api-reference/charges/failure-codes">
    O que cada recusa significa e quando vale tentar de novo.
  </Card>

  <Card title="Reembolsar um pagamento" icon="rotate-left" href="/payments/refund-payment">
    Como devolver dinheiro a partir da cobrança.
  </Card>
</CardGroup>