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

# Cobranças

> O registro de cada tentativa de mover dinheiro — somente leitura, materializado pela confirmação de um Payment Intent.

Uma **charge** é o registro de uma tentativa concreta de mover dinheiro: uma cobrança feita sobre um meio de pagamento. Ela guarda **o que foi cobrado** e **o que efetivamente entrou** — valor, moeda, se foi pago, se foi capturado e, quando algo dá errado, o código e a mensagem da falha. É o objeto que responde à pergunta "essa cobrança aconteceu, deu certo?".

<Info>
  **Você não cria charges diretamente**

  A charge é **materializada pelo sistema** quando um [Payment Intent](/features/payment-intents) é confirmado. Para cobrar alguém, você cria e confirma um `payment_intent` — a charge aparece como consequência. O recurso é **somente leitura**: você consulta (`GET`) e lista (`GET`), nunca cria, atualiza ou remove via API.
</Info>

## Modelo conceitual

Cada `payment_intent` pode produzir **uma ou mais charges** ao longo das suas tentativas de cobrança (uma recusa seguida de nova tentativa, por exemplo). Cada charge aponta de volta para o intent que a originou e, quando existem, para o `customer`, a `invoice` e o `payment_method` envolvidos.

```mermaid theme={}
flowchart LR
  PI[Payment Intent] -- confirma --> C1[Charge tentativa 1]
  PI -- nova tentativa --> C2[Charge tentativa 2]
  C2 -.-> CU[Customer]
  C2 -.-> IN[Invoice]
  C2 -.-> PM[Payment Method]
```

| Objeto                                        | Papel                                                  | Quem cria                         |
| --------------------------------------------- | ------------------------------------------------------ | --------------------------------- |
| [`payment_intent`](/features/payment-intents) | O processo de cobrar: intenção + ciclo de confirmação. | Você (`POST` + confirm).          |
| `charge`                                      | A tentativa pública resultante de mover dinheiro.      | O sistema, ao confirmar o intent. |

<Note>
  O detalhe interno de processamento financeiro fica **fora** do contrato público. Na API, a charge é o objeto canônico para conciliar tentativas de cobrança.
</Note>

## Para que serve

Use charges para:

* consultar a tentativa de cobrança que aprovou ou falhou;
* reconciliar valor, moeda, status e método usado;
* exibir histórico financeiro para o seu cliente;
* ligar um pagamento aprovado ao `payment_intent`, à `invoice` ou ao `customer`;
* reagir aos webhooks `charge.succeeded`, `charge.failed` e `charge.updated`;
* inspecionar a tentativa apontada por `latest_charge` em um [Payment Intent](/features/payment-intents).

## Anatomia da charge

| Campo                    | Tipo             | Descrição                                                                          |
| ------------------------ | ---------------- | ---------------------------------------------------------------------------------- |
| `amount`                 | `integer`        | Valor da tentativa, **em centavos**.                                               |
| `amount_captured`        | `integer`        | Valor efetivamente capturado, em centavos. `0` enquanto nada foi capturado.        |
| `currency`               | `string`         | Moeda em 3 letras minúsculas (`brl`).                                              |
| `status`                 | `string`         | `pending`, `processing`, `succeeded`, `failed` ou `canceled`.                      |
| `paid`                   | `boolean`        | `true` quando a charge foi paga.                                                   |
| `captured`               | `boolean`        | `true` quando o valor já foi capturado.                                            |
| `disputed`               | `boolean`        | `true` quando a charge está em disputa.                                            |
| `payment_error`          | `object \| null` | Motivo da recusa (`category`, `code`, `message`); `null` em charges bem-sucedidas. |
| `billing_details`        | `object`         | Dados de cobrança capturados no momento (nome, endereço). `{}` quando vazio.       |
| `payment_method_details` | `object`         | Detalhes do meio usado; o conteúdo varia por tipo. `{}` quando vazio.              |
| `receipt_url`            | `string \| null` | URL do comprovante; `null` quando não há.                                          |
| `description`            | `string \| null` | Descrição livre da charge.                                                         |
| `customer`               | `string \| null` | Customer cobrado (`cus_*`).                                                        |
| `invoice`                | `string \| null` | Invoice relacionada (`inv_*`).                                                     |
| `payment_intent`         | `string \| null` | Intent que originou a charge (`pi_*`).                                             |
| `payment_method`         | `string \| null` | Método de pagamento usado (`pm_*`).                                                |
| `metadata`               | `object`         | Pares chave→valor livres. `{}` quando vazio.                                       |

O schema público completo, com cada campo retornado, está em [Objeto charge](/api-reference/charges).

### Exemplo reduzido

```json theme={}
{
  "id": "ch_123",
  "object": "charge",
  "amount": 9990,
  "amount_captured": 9990,
  "captured": true,
  "currency": "brl",
  "customer": "cus_123",
  "invoice": "inv_123",
  "paid": true,
  "payment_intent": "pi_123",
  "payment_method": "pm_123",
  "status": "succeeded"
}
```

## Status

A charge percorre estes estados durante o ciclo de cobrança:

| Status       | Significado                                                         |
| ------------ | ------------------------------------------------------------------- |
| `pending`    | Tentativa criada, aguardando confirmação ou processamento.          |
| `processing` | Cobrança em processamento (típico de meios assíncronos).            |
| `succeeded`  | Cobrança aprovada. `paid = true`.                                   |
| `failed`     | Cobrança recusada, expirada ou não concluída. Veja `payment_error`. |
| `canceled`   | Tentativa cancelada antes de ser concluída.                         |

<Tip>
  `status = succeeded` indica que a cobrança foi aprovada, mas é `captured`/`amount_captured` que revelam se o dinheiro já foi capturado. Para fluxos de autorização + captura, confira os dois.
</Tip>

## Detalhes do meio de pagamento

`payment_method_details` é polimórfico: o campo `type` indica o meio (`credit_card`, `pix`, `boleto`) e o sub-objeto correspondente traz os detalhes daquele tipo.

<CodeGroup>
  ```json Cartão theme={}
  {
    "card": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2030,
      "installments": 1,
      "last4": "4242"
    },
    "type": "credit_card"
  }
  ```

  ```json PIX theme={}
  {
    "type": "pix"
  }
  ```

  ```json Boleto theme={}
  {
    "type": "boleto"
  }
  ```
</CodeGroup>

<Note>
  Dados de instrumento financeiro chegam mascarados: o cartão sai como `brand` + `last4`, nunca o número completo. Já o CPF/CNPJ do comprador, quando presente em `billing_details`, sai por inteiro — o parceiro precisa dele para emissão de nota e conciliação.
</Note>

## Consultar e listar

A charge é **somente leitura**. As únicas operações são:

| Operação             | Verbo | URL                |
| -------------------- | ----- | ------------------ |
| Consultar uma charge | `GET` | `/v1/charges/{id}` |
| Listar charges       | `GET` | `/v1/charges`      |

Tentar criar uma charge com `POST /v1/charges` retorna `400` — cobre-se criando e confirmando um `payment_intent`.

### Listar com filtros

A listagem é por **cursor** (`starting_after`, `ending_before`, `limit` de `1` a `100`), em ordem decrescente de criação. Você pode filtrar por:

| Filtro           | Casa com                                                      |
| ---------------- | ------------------------------------------------------------- |
| `payment_intent` | Charges de um intent (`pi_*`).                                |
| `invoice`        | Charges de uma invoice (`inv_*`).                             |
| `customer`       | Charges de um customer (`cus_*`).                             |
| `payment_method` | Charges de um método (`pm_*`).                                |
| `status`         | `pending`, `processing`, `succeeded`, `failed` ou `canceled`. |

<CodeGroup>
  ```bash Charges de um intent theme={}
  curl -G https://api.chargefy.io/v1/charges \
    -H "Authorization: Bearer {{API_KEY}}" \
    -d payment_intent=pi_123 \
    -d limit=10
  ```

  ```bash Só as aprovadas de um cliente theme={}
  curl -G https://api.chargefy.io/v1/charges \
    -H "Authorization: Bearer {{API_KEY}}" \
    -d customer=cus_123 \
    -d status=succeeded
  ```

  ```bash Consultar uma charge theme={}
  curl https://api.chargefy.io/v1/charges/ch_123 \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</CodeGroup>

## Webhooks

Mudanças na charge disparam eventos cujo `data.object` carrega o objeto `charge` completo. Eventos de update também trazem `data.previous_attributes` com os valores anteriores dos campos alterados.

| Evento             | Quando dispara                                        |
| ------------------ | ----------------------------------------------------- |
| `charge.succeeded` | A tentativa foi aprovada.                             |
| `charge.failed`    | A tentativa foi recusada ou não concluída.            |
| `charge.updated`   | Algum campo da charge mudou (captura, disputa, etc.). |

<Warning>
  Reaja aos webhooks em vez de fazer polling. Ao receber `charge.succeeded` ou `charge.failed`, consulte a charge pelo `id` do payload para conciliar com o seu pedido — `metadata` é o caminho para correlacionar com o seu sistema.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Objeto charge" icon="receipt" href="/api-reference/charges">
    Schema público completo e cada campo retornado.
  </Card>

  <Card title="Payment Intents" icon="bullseye" href="/features/payment-intents">
    O processo que materializa a charge ao ser confirmado.
  </Card>

  <Card title="Listar charges (API)" icon="list" href="/api-reference/charges/list">
    Filtros, cursor e shape da listagem.
  </Card>

  <Card title="Consultar charge (API)" icon="magnifying-glass" href="/api-reference/charges/get">
    Contrato do `GET /v1/charges/{id}`.
  </Card>

  <Card title="Códigos de falhas" icon="circle-xmark" href="/api-reference/charges/failure-codes">
    O que `payment_error` (`category`, `code`, `message`) significa quando uma cobrança falha.
  </Card>
</CardGroup>