Cobranças - Chargefy

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 diretamenteA charge é materializada pelo sistema quando um Payment Intent é 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.

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.

Objeto	Papel	Quem cria
`payment_intent`	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.

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.

Exemplo reduzido

{
  "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.

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.

{
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "installments": 1,
    "last4": "4242"
  },
  "type": "credit_card"
}

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

curl -G https://api.chargefy.io/v1/charges \
  -H "Authorization: Bearer {{API_KEY}}" \
  -d payment_intent=pi_123 \
  -d limit=10

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

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

Objeto charge

Schema público completo e cada campo retornado.

Payment Intents

O processo que materializa a charge ao ser confirmado.

Listar charges (API)

Filtros, cursor e shape da listagem.

Consultar charge (API)

Contrato do GET /v1/charges/{id}.

Códigos de falhas

O que payment_error (category, code, message) significa quando uma cobrança falha.

​Modelo conceitual

​Para que serve

​Anatomia da charge

​Exemplo reduzido

​Status

​Detalhes do meio de pagamento

​Consultar e listar

​Listar com filtros

​Webhooks

​Próximos passos

Objeto charge

Payment Intents

Listar charges (API)

Consultar charge (API)

Códigos de falhas

Modelo conceitual

Para que serve

Anatomia da charge

Exemplo reduzido

Status

Detalhes do meio de pagamento

Consultar e listar

Listar com filtros

Webhooks

Próximos passos