> ## 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?".
**Você não cria charges diretamente**
A charge é **materializada pelo sistema** quando um [Payment Intent](/payments/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.
## Como os recursos se relacionam
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.
| Origem | Acontecimento | Resultado |
| ---------------- | ----------------------------- | --------------------------------------------------------------------- |
| `payment_intent` | Primeira confirmação | Cria uma `charge` para a primeira tentativa. |
| `payment_intent` | Nova tentativa | Cria outra `charge`; as tentativas anteriores continuam no histórico. |
| `charge` | Quando as referências existem | Aponta para `customer`, `invoice` e `payment_method`. |
| Objeto | Papel | Quem cria |
| --------------------------------------------- | ------------------------------------------------------ | --------------------------------- |
| [`payment_intent`](/payments/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. |
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.
## 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](/payments/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 resolvido da recusa num único grupo (`advice_code`, `category`, `code`, `message`, `network_*`); `null` fora de falha. |
| `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={"theme":"css-variables"}
{
"id": "ch_KcZiDLwHUEqkbCCD",
"object": "charge",
"amount": 9990,
"amount_captured": 9990,
"amount_refunded": 0,
"billing_details": {},
"captured": true,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"customer": "cus_3NP4KNpBQZv2qEEf",
"description": null,
"disputed": false,
"invoice": "inv_51QnAA8AASWAWEtg",
"livemode": false,
"metadata": {},
"paid": true,
"payment_error": null,
"payment_intent": "pi_4JAceVEdXxjxxUhD",
"payment_method": "pm_kcawKpM895cTPTtm",
"payment_method_details": {
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/charges/ch_KcZiDLwHUEqkbCCD/refunds"
},
"status": "succeeded",
"updated_at": "2026-05-16T14:09:27Z"
}
```
## Status
A charge percorre estes estados durante o ciclo de cobrança:
| Status | Significado | `paid` | Próximo passo |
| ------------ | ---------------------------------------------- | ------- | -------------------------------------------------------- |
| `pending` | Tentativa criada, ainda não enviada. | `false` | Aguarde o início do processamento. |
| `processing` | Resultado ainda não conclusivo. | `false` | Aguarde o webhook; não crie outra tentativa por timeout. |
| `succeeded` | Cobrança aprovada. | `true` | Concilie valores e entregue o produto ou serviço. |
| `failed` | Tentativa recusada ou rejeitada antes da rede. | `false` | Leia `payment_error`. |
| `canceled` | Tentativa cancelada ou autorização revertida. | `false` | Nenhuma cobrança ocorreu; a autorização foi liberada. |
`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.
## 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.
```json Cartão theme={"theme":"css-variables"}
{
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
}
```
```json PIX theme={"theme":"css-variables"}
{
"type": "pix"
}
```
```json Boleto theme={"theme":"css-variables"}
{
"type": "boleto"
}
```
Cada campo do cartão aparece sempre. Quando a informação não foi confirmada
pela resposta da tentativa, o valor é `null`. A Chargefy não deduz `country`,
`funding`, `network` ou emissor a partir do BIN e nunca devolve PAN, primeiros
dígitos, CVC ou fingerprint no objeto Charge.
## Motivo da falha
Quando a tentativa termina recusada, `payment_error` traz a leitura final da
Chargefy num único grupo: `category`, `code` e `message` dizem o que houve;
`advice_code` orienta o próximo passo; e `network_advice_code`/
`network_decline_code` preservam a evidência bruta da rede quando ela existe.
A resolução é nossa: um cartão roubado pode ter sido recusado pela rede com o
código bruto `43`, e a categoria final é `blocked` porque o tratamento correto
é interromper novas tentativas. Consulte
[Códigos de falha](/api-reference/charges/failure-codes) para o catálogo
completo.
`payment_error.network_decline_code` é um diagnóstico bruto e não universal.
O mesmo código pode ter leitura diferente por bandeira. Ausência do código
significa que não recebemos evidência suficiente — não inventamos um valor
para preencher o campo.
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.
## 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`. |
| `created_at[gte]`, `created_at[gt]`, `created_at[lte]`, `created_at[lt]` | Intervalo de criação em ISO 8601. |
| `payment_method_type` | `credit_card`, `pix` ou `boleto`. |
| `card_brand` | `visa`, `mastercard`, `amex` ou `elo`. |
| `card_installments` | Quantidade de parcelas, de `1` a `12`. |
| `payment_error_category` | Categoria de tratamento da falha. |
| `payment_error_code` | Código Chargefy estável. |
| `network_decline_code` | Código bruto da rede; combine com `card_brand`. |
```bash Charges de um intent theme={"theme":"css-variables"}
curl -G https://api.chargefy.io/v1/charges \
-H "Authorization: Bearer {{API_KEY}}" \
-d payment_intent=pi_4JAceVEdXxjxxUhD \
-d limit=10
```
```bash Só as aprovadas de um cliente theme={"theme":"css-variables"}
curl -G https://api.chargefy.io/v1/charges \
-H "Authorization: Bearer {{API_KEY}}" \
-d customer=cus_3NP4KNpBQZv2qEEf \
-d status=succeeded
```
```bash Consultar uma charge theme={"theme":"css-variables"}
curl https://api.chargefy.io/v1/charges/ch_KcZiDLwHUEqkbCCD \
-H "Authorization: Bearer {{API_KEY}}"
```
## 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.). |
| `charge.refunded` | Um reembolso alterou o retrato da charge. |
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.
## Próximos passos
Schema público completo e cada campo retornado.
O processo que materializa a charge ao ser confirmado.
Filtros, cursor e shape da listagem.
Contrato do `GET /v1/charges/{id}`.
O que `payment_error` (`category`, `code`, `message`) significa quando uma
cobrança falha.