Pular para o conteúdo principal
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 sinaliza em disputed quando o comprador abre uma disputa — o caso em si vive no objeto dispute. 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.*.
string
Identificador único da cobrança. Usa o prefixo ch_*.
string
Referência do pagamento seguida da sequência da tentativa: J9N6R8-001. É gerada na criação e não muda. A sequência começa em 001, inclui cobranças com falha ou canceladas e cresce além de 999 sem truncamento. Atualizar a mesma cobrança não cria outro número. Os endpoints usam o id.
string
Sempre "charge".
integer
Valor total da cobrança na menor unidade da moeda (centavos em brl).
integer
Valor capturado na menor unidade da moeda (centavos em brl). Em faturamento padrão (captura automática), é igual a amount.
integer
Total na menor unidade da moeda (centavos em brl) dos estornos nos estados pending, requires_action e succeeded. Estornos que falham ou são cancelados saem do total.
object
Dados cadastrais do comprador anexados à cobrança.
string | null
Data em que o cancelamento deste boleto foi pedido ao banco. Se o banco não responder, a Chargefy repete o pedido sozinha. Enquanto a confirmação não chega, o boleto ainda pode ser pago e o estado permanece pendente. O pagamento recebido sempre é registrado.
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
Indica se esta cobrança já foi contestada. Fica true quando a disputa abre e continua true depois que ela é encerrada, ganha ou perdida. Para saber se a disputa ainda está em andamento ou se a cobrança aceita refund, use status e is_charge_refundable do dispute. O acompanhamento do caso, o dinheiro que sai e volta e a decisão final vivem no dispute e chegam pelos eventos charge.dispute.*.
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.
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. Uma cobrança de cartão pode vir com payment_method: null: é o caso do cartão de uso único ou não suportado para cobranças futuras (single_use_card), cobrado diretamente sem ficar salvo. payment_method_details continua trazendo o snapshot do cartão usado.
object
Snapshot detalhado e estruturado do método de pagamento utilizado.
string | null
URL para o recibo de pagamento público hospedado pela Chargefy.
boolean
true quando o valor capturado é positivo e amount_refunded alcança esse valor. Em um estorno parcial, é false.
object
Presente apenas com expand[]=refunds na consulta ou expand[]=data.refunds na listagem. Contém até 10 estornos, do mais recente ao mais antigo. O campo é omitido nos eventos de cobrança e no latest_charge expandido de um pagamento.
string
Estado da cobrança.
string | null
Data da última atualização em formato ISO 8601.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos: Nos eventos charge.*, o payload carrega o objeto charge completo em data.object. Nos eventos charge.dispute.*, data.object carrega o objeto dispute — a cobrança contestada fica na referência charge do dispute.

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.