Skip to main content
O pagamento é a venda inteira. A cobrança é cada tentativa de tirar o dinheiro do meio de pagamento. Uma venda pode precisar de várias tentativas até dar certo — e é exatamente por isso que os dois objetos existem separados.
Você nunca cria uma cobrançaA cobrança é materializada pelo sistema quando um pagamento é confirmado. Para cobrar alguém, você cria e confirma um pagamento; a cobrança aparece como consequência e o pagamento aponta a mais recente em latest_charge.

​
O exemplo que explica a diferença

Uma compra de R$ 99,00 no cartão. O comprador erra o CVV, o banco recusa, ele corrige e a segunda tentativa passa. No fim: um pagamento, duas cobranças. O latest_charge do pagamento aponta para a segunda. A primeira continua no histórico, com o código e a mensagem da recusa — é ela que responde “por que o cartão do cliente não passou”.
Uma recusa não encerra o pagamento. Ele volta para requires_payment_method e o mesmo objeto aceita nova confirmação, com o cartão corrigido ou com outro cartão. O limite é de 10 tentativas por pagamento — cada tentativa executada vira uma cobrança.

​
Para que serve cada um

Use o pagamento para

Decidir se libera o pedido, o acesso ou a assinatura. É o objeto que carrega o desfecho da venda e o que você guarda no seu banco.

Use a cobrança para

Investigar uma tentativa: qual cartão foi usado, qual bandeira, qual o código da recusa, quanto foi capturado, quanto já foi reembolsado.
Na prática:
  • Liberar o produto → escute payment.intent.succeeded e olhe o status do pagamento. Nunca some cobranças para descobrir se a venda foi paga.
  • Explicar uma recusa ao cliente → abra a cobrança em latest_charge e leia payment_error. O catálogo de códigos de falha diz o que cada motivo significa e se vale tentar de novo.
  • Reembolsar → o reembolso acontece sobre a cobrança, não sobre o pagamento. É a cobrança que tem amount_captured, amount_refunded e a lista de refunds.
  • Mostrar histórico financeiro → liste as cobranças do cliente; cada linha é uma tentativa datada, com valor e desfecho.

​
Como os dois se ligam

O ponteiro vale nos dois sentidos: o pagamento indica a tentativa mais recente em latest_charge, e toda cobrança aponta de volta em payment_intent. Para ver todas as tentativas de um pagamento, liste as cobranças filtrando por payment_intent.

​
Estados que não são a mesma coisa

Os dois objetos têm um campo status, e eles não significam a mesma coisa.
Um pagamento em requires_payment_method com uma cobrança failed no histórico não é uma venda perdida — é uma venda que ainda pode ser paga. Tratar as duas situações como iguais é o erro mais comum de quem concilia pela cobrança em vez do pagamento.

​
Perguntas frequentes

Sim. Enquanto ninguém confirmou o pagamento — ou quando ele foi cancelado antes de qualquer tentativa — não existe cobrança alguma. latest_charge fica null.
Não. Toda cobrança nasce da confirmação de um pagamento e aponta para ele em payment_intent.
Sim. Cada tentativa executada é uma cobrança própria, mesmo que o pagamento e o ID pi_* continuem os mesmos.
Guarde o pagamento (pi_*) como relação principal do seu pedido: ele é estável durante todo o ciclo. As cobranças você alcança a partir dele quando precisar investigar.

​
Próximos passos

Cobranças

O objeto completo: campos, status, detalhes do método e motivo da falha.

Pagamentos vs. transações

Como a cobrança aprovada vira dinheiro no seu extrato.

Códigos de falha

O que cada recusa significa e quando vale tentar de novo.

Reembolsar um pagamento

Como devolver dinheiro a partir da cobrança.