Cobranças

Uma charge representa uma tentativa real de pagamento gerada a partir da confirmação de um payment_intent. Enquanto o intent identifica a cobrança e guarda as regras do fluxo financeiro, a Charge registra o resultado daquela tentativa específica — incluindo detalhes do método usado, erros de processamento e dados do recibo. Uma vez criado, o charge acompanha a evolução da cobrança: ele guarda 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. Você não cria charges diretamente — eles nascem automaticamente conforme 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_zNCybaRXvYnvYm6Z",
  "object": "charge",
  "amount": 9990,
  "amount_captured": 9990,
  "amount_refunded": 0,
  "billing_details": {
    "billing_address": {},
    "document": "12345678901",
    "document_type": "cpf",
    "email": "nome@email.com",
    "name": "Cliente Exemplo"
  },
  "captured": true,
  "created_at": "2026-05-19T18:00:00Z",
  "currency": "brl",
  "customer": "cus_pPNMG676rJAy4ihA",
  "description": "Assinatura do Plano Pro",
  "disputed": false,
  "invoice": "inv_hfimSARCgRX5fo3W",
  "livemode": true,
  "metadata": {},
  "paid": true,
  "payment_error": null,
  "payment_intent": "pi_ZZ4xAzWCoDk2j8Do",
  "payment_method": "pm_fMffWYPSifNPk2wG",
  "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": "https://receipts.chargefy.io/receipt/ch_zNCybaRXvYnvYm6Z",
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/refunds?charge=ch_zNCybaRXvYnvYm6Z"
  },
  "status": "succeeded",
  "updated_at": "2026-05-19T18:00:00Z"
}

string

Identificador único da cobrança. Usa o prefixo ch_*.

string

Sempre "charge".

integer

Valor total da cobrança em centavos.

integer

Valor capturado em centavos. Em faturamento padrão (captura automática), é igual a amount.

integer

Valor total reembolsado em centavos.

object

Dados cadastrais do comprador anexados à cobrança.

Show Campos de billing_details

object | null

Endereço de cobrança no momento do pagamento.

string | null

CPF ou CNPJ do comprador.

string | null

Tipo do documento do comprador.

Valor	Descrição
`cpf`	Documento de pessoa física.
`cnpj`	Documento de pessoa jurídica.

string | null

E-mail do comprador.

string | null

Nome do comprador.

boolean

Define se a cobrança foi capturada. Fica false em caso de transações apenas autorizadas.

string

Data de criação em formato ISO 8601.

string

Moeda em código ISO de 3 letras (ex: brl).

string | null

ID do comprador (cus_*) associado a esta cobrança, se houver.

string | null

Descrição amigável da cobrança.

boolean

Define se esta cobrança possui um chargeback ou contestação ativa aberta pelo comprador.

string | null

ID da invoice (inv_*) relacionada à cobrança (caso gerada a partir de faturamento recorrente).

boolean

true se gerado em produção; false se em testes.

object

Metadados customizados livre. Retorna {} quando vazio.

boolean

Define se a cobrança foi paga com sucesso.

object | null

O motivo resolvido da falha, num único grupo. Fica null quando a cobrança não terminou recusada. Veja Códigos de falha.

Show Campos de payment_error

string | null

Orientação da Chargefy para esta ocorrência: confirm_card_data, do_not_try_again ou try_again_later. null quando não existe orientação comprovada.

string | null

Categoria geral do erro.

Valor	Descrição
`issuer_declined`	O banco emissor recusou o pagamento.
`invalid`	Dados do cartão incorretos.
`blocked`	Recusa por restrição ou suspeita de fraude.
`processing_error`	Falha técnica ou de conectividade na rede.

string | null

Código padronizado do erro (ex: insufficient_funds, incorrect_cvc).

string | null

Mensagem técnica estável, em inglês, para logs e integrações.

string | null

Advice bruto da bandeira (ex.: merchant advice code), quando a rede enviou um. Diagnóstico; não é contrato estável.

string | null

Código bruto de recusa devolvido pela rede. Não é universal e deve ser interpretado junto de payment_method_details.card.brand.

string | null

ID do payment intent (pi_*) que deu origem a esta cobrança.

string | null

ID do método de pagamento (pm_*) utilizado para liquidar esta cobrança.

object

Snapshot detalhado e estruturado do método de pagamento utilizado.

Show Campos de payment_method_details

object

Presente apenas quando type é credit_card. Nesse caso, o objeto e todas as chaves abaixo são sempre retornados; valores sem evidência ficam null.

Show Campos de card

integer | null

Valor autorizado pela rede, em centavos.

string | null

Código de autorização devolvido para esta tentativa.

string | null

Bandeira do cartão (ex: visa, mastercard).

object

Resultado das verificações de endereço, CEP e CVC. Cada campo pode ser pass, fail, unavailable, unchecked ou null.

string | null

País do cartão quando informado diretamente, sem inferência por BIN.

integer | null

Mês de expiração do cartão.

integer | null

Ano de expiração do cartão.

string | null

Tipo de funding quando informado diretamente.

integer | null

Número de parcelas da cobrança.

string | null

Últimos 4 dígitos do cartão.

string | null

Rede usada no processamento quando informada diretamente. Não é inferida a partir da bandeira.

string | null

O tipo do método de pagamento usado.

Valor	Descrição
`credit_card`	Cartão de crédito.
`pix`	Pagamento instantâneo via PIX.
`boleto`	Boleto bancário.
`null`	O método não pôde ser identificado no histórico.

string | null

URL para o recibo de pagamento público hospedado pela Chargefy.

boolean

Define se a cobrança foi reembolsada total ou parcialmente.

object

Lista contendo o histórico de reembolsos aplicados a esta cobrança.

Show Campos de refunds

string

Sempre "list".

array

Lista de objetos refund (re_*).

boolean

Define se há mais reembolsos na paginação.

string

A URL de paginação dos reembolsos associados.

string

Estado da cobrança.

Valor	Descrição
`pending`	Aguardando confirmação do pagamento.
`processing`	Pagamento em processamento.
`succeeded`	Pagamento confirmado.
`failed`	A tentativa de pagamento falhou.
`canceled`	A cobrança foi cancelada.

string | null

Data da última atualização em formato ISO 8601.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

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

Como se relaciona

payment_intent acompanha o ciclo da cobrança e aponta para a Charge mais recente em latest_charge.
charge registra a tentativa concreta de cobrar o método e é somente leitura.
O mesmo Payment Intent pode ter várias Charges. A falha de uma Charge antiga não significa que a cobrança atual falhou; consulte o Payment Intent antes de rebaixar o estado do pedido.
transaction registra os movimentos financeiros gerados depois, incluindo parcelas, taxas, líquido e liquidação.

Lifecycle financeiro

Quando usar Payment Intent, Charge e Transaction.

Códigos de falha

Categorias e códigos públicos para tratar recusas.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Objeto charge

Operações

Eventos

Como se relaciona

Lifecycle financeiro

Códigos de falha

​Objeto charge

​Operações

​Eventos

​Como se relaciona

Lifecycle financeiro

Códigos de falha

Objeto charge

Operações

Eventos

Como se relaciona