Evento payment.method.detached

Evento `payment.method.detached`

Disparado quando um payment_method deixa de ser o método padrão do customer. A credencial salva não é apagada. Use este evento para remover o vínculo local entre o customer e o método salvo. O objeto em data.object continua representando o payment method, mas o campo customer vem null. data.object usa o mesmo shape do objeto payment_method. Desanexar não revela nem remove dados sensíveis do cartão; o payload mantém apenas os dados seguros para identificação.

Não trate este evento como falha de cobrança. Ele indica uma mudança de vínculo entre customer e método salvo.

Quando acontece

Situação	Como aparece no payload
Método desanexado de um customer	`data.object.customer` vem `null`.
Método deixa de ser padrão para cobranças futuras	O `pm_*` continua em `data.object.id`, mas sem customer ligado.
Dados de cobrança deixam de ter contexto do customer	Campos de `billing_details` podem vir `null`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (pm_*) para localizar o método salvo.
Remova o vínculo local entre o método e o customer anterior, se ele ainda estiver ativo.
Mantenha histórico de cobranças antigas que referenciam o pm_*.
Atualize telas de método padrão para não sugerirem que esse cartão ainda está ligado ao customer.

Campos importantes

Campo	O que observar
`data.object.id`	Payment method desanexado.
`customer`	Vem `null` após a desanexação.
`card.brand` / `card.last4`	Identificação segura do cartão.
`billing_details`	Dados de cobrança remanescentes no objeto.
`type`	Tipo do método; atualmente `credit_card`.
`updated_at`	Última atualização pública conhecida do método.

Tipos de método

Valor	Descrição
`credit_card`	Cartão de crédito.

Exemplo de payload

{
  "id": "evt_BHSNY1dTLtzqE1u2",
  "object": "event",
  "created_at": "2026-05-16T18:50:00Z",
  "data": {
    "object": {
      "id": "pm_Wgh47m2tnA937ZQu",
      "object": "payment_method",
      "billing_details": {
        "address": null,
        "email": null,
        "name": "Cliente Exemplo",
        "phone": null
      },
      "card": {
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2030,
        "last4": "4242"
      },
      "created_at": "2026-05-16T18:32:00Z",
      "customer": null,
      "livemode": true,
      "metadata": {},
      "type": "credit_card",
      "updated_at": null
    }
  },
  "livemode": true,
  "organization": "org_v6969crEMLMNWTfe",
  "request": {
    "id": null
  },
  "type": "payment.method.detached"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payment.method.detached