Evento payment.method.attached

Evento `payment.method.attached`

Disparado quando um payment_method vira o método padrão de um customer, incluindo confirmações de setup_intent. Use este evento para refletir que um método salvo passou a estar ligado a um customer. O objeto em data.object traz a credencial salva com dados não sensíveis do cartão e o campo customer preenchido. data.object usa o mesmo shape do objeto payment_method. Anexar um método não expõe número completo do cartão nem código de segurança.

Em fluxos de salvamento, eventos de criação e anexação podem chegar próximos um do outro. Faça upsert pelo pm_* e processe cada evento de forma idempotente.

Quando acontece

Situação	Como aparece no payload
Método anexado a um customer	`data.object.customer` traz o `cus_*`.
Setup intent conclui com sucesso	O método salvo pode ser anexado ao customer do setup intent.
Método passa a ser usado em cobranças futuras	O `payment_method` fica disponível como credencial salva do customer.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (pm_*) como chave do método salvo.
Atualize o customer local indicado em data.object.customer.
Exiba o cartão por card.brand, card.last4, card.exp_month e card.exp_year.
Não espere dados sensíveis do cartão no payload; eles não são retornados.

Campos importantes

Campo	O que observar
`data.object.id`	Payment method anexado.
`customer`	Customer ao qual o método está ligado.
`type`	Tipo do método; atualmente `credit_card`.
`card.brand` / `card.last4`	Dados seguros para exibir o cartão salvo.
`billing_details`	Dados de cobrança associados ao método.
`metadata`	Objeto livre para correlação com seu sistema.

Tipos de método

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

Exemplo de payload

{
  "id": "evt_UaG8gDsS2XePQ58P",
  "object": "event",
  "created_at": "2026-05-16T18:32:00Z",
  "data": {
    "object": {
      "id": "pm_WGY4pVDhyrE78sQg",
      "object": "payment_method",
      "billing_details": {
        "address": null,
        "email": "nome@email.com",
        "name": "Cliente Exemplo",
        "phone": null
      },
      "card": {
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2030,
        "last4": "4242"
      },
      "created_at": "2026-05-16T18:32:00Z",
      "customer": "cus_5b9V85bnfjP6MQmE",
      "livemode": true,
      "metadata": {},
      "type": "credit_card",
      "updated_at": null
    }
  },
  "livemode": true,
  "organization": "org_QYQbGEa6q5TEyVoq",
  "request": {
    "id": null
  },
  "type": "payment.method.attached"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento payment.method.attached