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

# Overview

> O objeto Charge

Um `charge` (cobrança) representa uma tentativa real de pagamento gerada a partir da confirmação de um `payment_intent`. Enquanto o intent encapsula a intenção e as regras do fluxo financeiro, o objeto charge registra o resultado efetivo da transação no adquirente ou gateway — guardando detalhes específicos do método de pagamento usado (como os últimos 4 dígitos do cartão, banco do Pix ou código de barras do boleto), erros de processamento e dados do recibo de pagamento.

Uma vez criado, o charge acompanha a evolução financeira da cobrança: ele armazena o status de captura (em fluxos de pré-autorização e captura manual), o controle de reembolsos totais ou parciais através da lista de `refunds`, e eventuais contestações (`disputes`) abertas pelo comprador final. Desenvolvedores não criam charges diretamente; eles nascem automaticamente à medida que as tentativas de pagamento são executadas no sistema.

## Objeto charge

Este é o formato completo retornado em `get`, itens de `list` e em `data.object` dos webhooks `charge.*`.

```json theme={}
{
  "id": "ch_123",
  "object": "charge",
  "amount": 9990,
  "amount_captured": 9990,
  "amount_refunded": 0,
  "billing_details": {
    "billing_address": {},
    "document": "12345678901",
    "document_type": "cpf",
    "email": "ada@example.com",
    "name": "Ada Lovelace"
  },
  "captured": true,
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "customer": "cus_123",
  "description": "Assinatura do Plano Pro",
  "disputed": false,
  "invoice": "inv_123",
  "livemode": true,
  "metadata": {},
  "paid": true,
  "payment_error": null,
  "payment_intent": "pi_123",
  "payment_method": "pm_123",
  "payment_method_details": {
    "credit_card": {
      "brand": "visa",
      "last4": "4242"
    },
    "type": "credit_card"
  },
  "receipt_url": "https://receipts.chargefy.io/receipt/ch_123",
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/refunds?charge=ch_123"
  },
  "status": "succeeded",
  "updated_at": "2026-05-19T18:00:00Z"
}
```

<ResponseField name="id" type="string">
  Identificador único da cobrança. Usa o prefixo `ch_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"charge"`.
</ResponseField>

<ResponseField name="amount" type="integer">
  Valor total da cobrança em centavos.
</ResponseField>

<ResponseField name="amount_captured" type="integer">
  Valor capturado em centavos. Em faturamento padrão (captura automática), é igual a `amount`.
</ResponseField>

<ResponseField name="amount_refunded" type="integer">
  Valor total reembolsado em centavos.
</ResponseField>

<ResponseField name="billing_details" type="object">
  Dados cadastrais do comprador anexados à cobrança.

  <Expandable title="Campos de billing_details">
    <ResponseField name="billing_address" type="object | null">Endereço de cobrança no momento do pagamento.</ResponseField>
    <ResponseField name="document" type="string | null">CPF ou CNPJ do comprador.</ResponseField>
    <ResponseField name="document_type" type="string | null">Tipo do documento (`cpf` ou `cnpj`).</ResponseField>
    <ResponseField name="email" type="string | null">E-mail do comprador.</ResponseField>
    <ResponseField name="name" type="string | null">Nome do comprador.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="captured" type="boolean">
  Define se a cobrança foi capturada. Fica `false` em caso de transações apenas autorizadas.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em formato ISO 8601.
</ResponseField>

<ResponseField name="currency" type="string">
  Moeda em código ISO de 3 letras (ex: `brl`).
</ResponseField>

<ResponseField name="customer" type="string | null">
  ID do comprador (`cus_*`) associado a esta cobrança, se houver.
</ResponseField>

<ResponseField name="description" type="string | null">
  Descrição amigável da cobrança.
</ResponseField>

<ResponseField name="disputed" type="boolean">
  Define se esta cobrança possui um chargeback ou contestação ativa aberta pelo comprador.
</ResponseField>

<ResponseField name="invoice" type="string | null">
  ID da invoice (`inv_*`) relacionada à cobrança (caso gerada a partir de faturamento recorrente).
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` se gerado em produção; `false` se em testes.
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadados customizados livre. Retorna `{}` quando vazio.
</ResponseField>

<ResponseField name="paid" type="boolean">
  Define se a cobrança foi paga com sucesso.
</ResponseField>

<ResponseField name="payment_error" type="object | null">
  Dados do erro caso o pagamento tenha falhado.

  <Expandable title="Campos de payment_error">
    <ResponseField name="category" type="string | null">Categoria coarse do erro (ex: `issuer_declined`, `invalid`, `blocked`).</ResponseField>
    <ResponseField name="code" type="string | null">Código padronizado do erro (ex: `insufficient_funds`, `incorrect_cvv`).</ResponseField>
    <ResponseField name="message" type="string | null">Mensagem amigável descrevendo o erro.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_intent" type="string | null">
  ID do payment intent (`pi_*`) que deu origem a esta cobrança.
</ResponseField>

<ResponseField name="payment_method" type="string | null">
  ID do método de pagamento (`pm_*`) utilizado para liquidar esta cobrança.
</ResponseField>

<ResponseField name="payment_method_details" type="object">
  Snapshot detalhado e estruturado do método de pagamento utilizado.

  <Expandable title="Campos de payment_method_details">
    <ResponseField name="boleto" type="object | null">Dados do boleto gerado.</ResponseField>
    <ResponseField name="credit_card" type="object | null">Dados estruturados se o tipo for cartão de crédito (ex: marca, últimos 4 dígitos).</ResponseField>
    <ResponseField name="pix" type="object | null">Dados do Pix utilizado.</ResponseField>
    <ResponseField name="type" type="string">O tipo do método de pagamento usado (`credit_card`, `pix` ou `boleto`).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="receipt_url" type="string | null">
  URL para o recibo de pagamento público hospedado pela Chargefy.
</ResponseField>

<ResponseField name="refunded" type="boolean">
  Define se a cobrança foi reembolsada total ou parcialmente.
</ResponseField>

<ResponseField name="refunds" type="object">
  Lista contendo o histórico de reembolsos aplicados a esta cobrança.

  <Expandable title="Campos de refunds">
    <ResponseField name="object" type="string">Sempre `"list"`.</ResponseField>
    <ResponseField name="data" type="array">Lista de objetos refund (`re_*`).</ResponseField>
    <ResponseField name="has_more" type="boolean">Define se há mais reembolsos na paginação.</ResponseField>
    <ResponseField name="url" type="string">A URL de paginação dos reembolsos associados.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="string">
  Estado da cobrança: `pending`, `processing`, `succeeded`, `failed` ou `canceled`.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em formato ISO 8601.
</ResponseField>

## Operações

* [Consultar códigos de falha](/api-reference/charges/failure-codes)
* [Consultar cobrança](/api-reference/charges/get)
* [Listar cobranças](/api-reference/charges/list)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`charge.succeeded`](/api-reference/webhooks/charge.succeeded)
* [`charge.failed`](/api-reference/webhooks/charge.failed)
* [`charge.updated`](/api-reference/webhooks/charge.updated)
* [`charge.refunded`](/api-reference/webhooks/charge.refunded)
* [`charge.dispute.created`](/api-reference/webhooks/charge.dispute.created)
* [`charge.dispute.updated`](/api-reference/webhooks/charge.dispute.updated)
* [`charge.dispute.closed`](/api-reference/webhooks/charge.dispute.closed)

O payload carrega o objeto `charge` completo em `data.object`.