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 emget, itens de list e em data.object dos webhooks charge.*.
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.Valor capturado na menor unidade da moeda (centavos em
brl). Em faturamento padrão (captura automática), é
igual a amount.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.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.
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.*.ID da invoice (
inv_*) relacionada à cobrança (caso gerada a partir de
faturamento recorrente).O motivo resolvido da falha, num único grupo. Fica
null quando a cobrança
não terminou recusada. Veja Códigos de falha.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.true quando o valor capturado é positivo e amount_refunded alcança esse
valor. Em um estorno parcial, é false.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.Operações
Eventos
Mudanças nesse objeto disparam os seguintes eventos:charge.succeededcharge.failedcharge.updatedcharge.refundedcharge.dispute.createdcharge.dispute.updatedcharge.dispute.closedcharge.dispute.funds.withdrawncharge.dispute.funds.reinstated
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_intentacompanha o ciclo da cobrança e aponta para a Charge mais recente emlatest_charge.chargeregistra 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.
transactionregistra 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.

