Cobranças

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.

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

Exemplo reduzido

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

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

{
  "type": "pix"
}

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

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

curl -G https://api.chargefy.io/v1/charges \
  -H "Authorization: Bearer {{API_KEY}}" \
  -d customer=cus_3NP4KNpBQZv2qEEf \
  -d status=succeeded

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

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.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Como os recursos se relacionam

Para que serve

Anatomia da charge

Exemplo reduzido

Status

Detalhes do meio de pagamento

Motivo da falha

Consultar e listar

Listar com filtros

Webhooks

Próximos passos

Objeto charge

Payment Intents

Listar charges (API)

Consultar charge (API)

Códigos de falhas

​Como os recursos se relacionam

​Para que serve

​Anatomia da charge

​Exemplo reduzido

​Status

​Detalhes do meio de pagamento

​Motivo da falha

​Consultar e listar

​Listar com filtros

​Webhooks

​Próximos passos

Objeto charge

Payment Intents

Listar charges (API)

Consultar charge (API)

Códigos de falhas

Como os recursos se relacionam

Para que serve

Anatomia da charge

Exemplo reduzido

Status

Detalhes do meio de pagamento

Motivo da falha

Consultar e listar

Listar com filtros

Webhooks

Próximos passos