Evento payment.intent.canceled

Evento `payment.intent.canceled`

Disparado quando um payment_intent chega ao estado canceled. data.object usa o mesmo shape de GET /v1/payment-intents/:id, agora com status: "canceled", canceled_at preenchido e cancellation_reason quando houver motivo registrado. Use este evento para encerrar a tentativa no seu sistema, atualizar a operação de negócio relacionada e impedir novas tentativas de captura naquele intent.

O cancelamento é uma transição de estado. Quando o payload traz data.previous_attributes, use esse diff para auditoria; o estado final continua sendo o objeto completo em data.object.

Quando acontece

Situação	Como aparece no payload
Cancelamento via API	`request.id` costuma vir preenchido e `cancellation_reason` ecoa o motivo enviado.
A sessão de checkout expirou	`cancellation_reason` vem como `expired`. Chega junto com `checkout.session.expired`; os dois são a mesma decisão.
Você cancelou dizendo que o comprador desistiu	`abandoned`. Só chega assim se você enviou esse motivo — a Chargefy nunca escreve `abandoned`.
Intent ainda não concluído foi cancelado	`status` passa para `canceled` e `canceled_at` recebe o horário da transição.
Havia estado anterior registrado	`data.previous_attributes.status` mostra o status antes do cancelamento.

Um código PIX ou boleto que vence sem pagamento não emite este evento: a expiração encerra apenas aquela tentativa e o intent volta a requires_payment_method, comunicado por payment.intent.updated. Cancelamento é sempre uma decisão — sua, do checkout que expirou ou de uma fatura anulada.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Atualize o pagamento local usando data.object.id (pi_*) e status: "canceled".
Trate o cancelamento como estado final para este intent: não libere pedido e não tente capturar depois.
Use cancellation_reason para auditoria, suporte e mensagens internas.
Use data.previous_attributes para saber quais campos mudaram sem perder o estado final em data.object.
Use metadata, customer e invoice para localizar o pedido ou fatura correspondente.

Campos importantes

Campo	O que observar
`data.object.status`	Sempre vem como `canceled` neste evento.
`canceled_at`	Horário em que o intent foi cancelado.
`cancellation_reason`	Motivo do cancelamento, quando informado.
`data.previous_attributes`	Valores anteriores dos campos alterados na transição.
`amount_received`	Valor recebido antes do cancelamento; no exemplo, `0`.
`amount_capturable`	Valor ainda capturável; deve ser tratado como indisponível após o cancelamento.
`latest_charge`	Última tentativa de cobrança, quando houve confirmação antes do cancelamento.
`next_action`	Pode vir `null` quando a próxima ação deixou de ser válida com o cancelamento.
`metadata`	Ecoa os metadados enviados na criação para correlacionar com seu pedido.

Status possíveis

Neste evento, data.object.status é canceled. O status anterior, quando incluído, aparece em data.previous_attributes.status.

Valor	Descrição
`canceled`	O intent foi cancelado e não deve seguir para confirmação, captura ou pagamento.

Motivos possíveis de data.object.cancellation_reason, quando preenchido. Informados por você na chamada de cancelamento:

Valor	Descrição
`duplicate`	Cobrança duplicada.
`fraudulent`	Cobrança suspeita de fraude.
`requested_by_customer`	Cancelamento solicitado pelo comprador.
`abandoned`	O comprador saiu do fluxo. Só aparece se você enviou esse motivo.

Gerados pela Chargefy, apenas leitura:

Valor	Descrição
`automatic`	A Chargefy encerrou a tentativa por uma regra interna, sem causa mais específica.
`expired`	O prazo da tentativa acabou — é o motivo de uma sessão de checkout expirada.
`failed_invoice`	A cobrança da fatura não foi concluída.
`void_invoice`	A fatura foi cancelada.

Cada motivo afirma exatamente uma coisa, e você pode confiar nisso. expired significa que um prazo acabou — não é preciso cruzar com o histórico do seu sistema para descobrir o que houve. E abandoned só chega até você se você o enviou: a Chargefy nunca escreve esse valor.

O que a expiração de um código não emite

A expiração automática de um PIX ou boleto pendente não passa por este evento:

Evento	É emitido quando o código vence?
`payment.intent.updated`	Sim: o intent volta a `requires_payment_method` com `next_action: null`, pronto para um novo código no mesmo intent.

| payment.intent.canceled | Não. Cancelamento fica reservado a decisões: cancelamento direto, expiração da sessão de checkout ou fatura anulada. | Essa é a sequência lógica do lifecycle. A entrega HTTP ainda pode ser duplicada ou chegar fora de ordem; aplique as regras de entrega de webhooks.

Exemplo: sessão de checkout expirada com PIX pendente

{
  "id": "evt_1LCLr9utjoKhRz8E",
  "object": "event",
  "created_at": "2026-05-16T18:40:00Z",
  "data": {
    "object": {
      "id": "pi_zNBcq719x9t488wG",
      "object": "payment_intent",
      "amount": 7500,
      "amount_capturable": 0,
      "amount_details": {
        "amount": 7500,
        "installment_interest_amount": 0,
        "principal_amount": 7500,
        "surcharge_amount": 0
      },
      "amount_received": 0,
      "canceled_at": "2026-05-16T18:40:00Z",
      "cancellation_reason": "expired",
      "capture_method": "automatic",
      "client_secret": "pi_zNBcq719x9t488wG_secret_032e92502f11edc93c5c910c774ecc5a25fa69c0cc214726",
      "confirmation_method": "automatic",
      "created_at": "2026-05-16T18:34:58Z",
      "currency": "brl",
      "customer": null,
      "installment_interest_amount": 0,
      "installments": null,
      "invoice": null,
      "last_payment_error": null,
      "latest_charge": "ch_FEPwAwKn16ts9bMp",
      "livemode": true,
      "metadata": {},
      "next_action": null,
      "payment_method": null,
      "payment_method_options": {},
      "payment_method_types": [
        "pix"
      ],
      "principal_amount": 7500,
      "status": "canceled",
      "surcharge_amount": 0,
      "updated_at": "2026-05-16T18:40:00Z"
    }
  },
  "livemode": true,
  "organization": "org_9tksQGHwN7YqG72v",
  "request": {
    "id": null
  },
  "type": "payment.intent.canceled"
}

Páginas relacionadas

Cancelar Payment Intent

Estados canceláveis e motivos aceitos pela API.

Objeto Payment Intent

Semântica completa de cancelamento, status e expiração.

Encerrar uma tentativa

Idempotência, tentativa ativa e proteção contra eventos antigos.

Entrega e ordem

Duplicação, retries e eventos fora de ordem.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payment.intent.canceled