Skip to main content
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.*. 
{
  "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"
}
​
id
string
Identificador único da cobrança. Usa o prefixo ch_*.
​
object
string
Sempre "charge".
​
amount
integer
Valor total da cobrança em centavos.
​
amount_captured
integer
Valor capturado em centavos. Em faturamento padrão (captura automática), é igual a amount.
​
amount_refunded
integer
Valor total reembolsado em centavos.
​
billing_details
object
Dados cadastrais do comprador anexados à cobrança.
​
captured
boolean
Define se a cobrança foi capturada. Fica false em caso de transações apenas autorizadas.
​
created_at
string
Data de criação em formato ISO 8601.
​
currency
string
Moeda em código ISO de 3 letras (ex: brl).
​
customer
string | null
ID do comprador (cus_*) associado a esta cobrança, se houver.
​
description
string | null
Descrição amigável da cobrança.
​
disputed
boolean
Define se esta cobrança possui um chargeback ou contestação ativa aberta pelo comprador.
​
invoice
string | null
ID da invoice (inv_*) relacionada à cobrança (caso gerada a partir de faturamento recorrente).
​
livemode
boolean
true se gerado em produção; false se em testes.
​
metadata
object
Metadados customizados livre. Retorna {} quando vazio.
​
paid
boolean
Define se a cobrança foi paga com sucesso.
​
payment_error
object | null
Dados do erro caso o pagamento tenha falhado.
​
payment_intent
string | null
ID do payment intent (pi_*) que deu origem a esta cobrança.
​
payment_method
string | null
ID do método de pagamento (pm_*) utilizado para liquidar esta cobrança.
​
payment_method_details
object
Snapshot detalhado e estruturado do método de pagamento utilizado.
​
receipt_url
string | null
URL para o recibo de pagamento público hospedado pela Chargefy.
​
refunded
boolean
Define se a cobrança foi reembolsada total ou parcialmente.
​
refunds
object
Lista contendo o histórico de reembolsos aplicados a esta cobrança.
​
status
string
Estado da cobrança: pending, processing, succeeded, failed ou canceled.
​
updated_at
string | null
Data da última atualização em formato ISO 8601.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload carrega o objeto charge completo em data.object.