Evento setup.intent.succeeded

Evento `setup.intent.succeeded`

Disparado quando um setup_intent é confirmado e o método fica salvo para o customer. Use este evento para concluir localmente o fluxo de salvamento e liberar cobranças futuras com o payment_method retornado. O setup intent não cobra valor; ele apenas prepara o método para uso posterior. data.object usa o mesmo shape do objeto setup_intent. data.previous_attributes mostra o estado anterior, normalmente antes de payment_method ser preenchido e status mudar para succeeded.

O método salvo também pode gerar eventos de payment.method.*. Faça upsert pelo pm_* e pelo seti_* para que a ordem de chegada dos webhooks não afete sua sincronização.

Quando acontece

Situação	Como aparece no payload
Confirmação do setup intent concluiu	`data.object.status: "succeeded"`.
Método foi salvo para uso futuro	`payment_method` traz o `pm_*`.
Customer recebeu o método salvo	`customer` traz o `cus_*`.
Estado anterior mudou para concluído	`previous_attributes.status` mostra o status anterior.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Marque o setup intent (seti_*) como concluído no seu sistema.
Salve o payment_method (pm_*) associado ao customer.
Libere o fluxo que dependia de método salvo, como trial, assinatura ou cobrança futura.
Não registre pagamento recebido a partir deste evento; setup intents não movem dinheiro.

Campos importantes

Campo	O que observar
`data.object.status`	Sempre vem como `succeeded` neste evento.
`payment_method`	Método salvo e pronto para uso futuro.
`customer`	Customer a quem o método pertence.
`last_setup_error`	Deve vir `null` quando a confirmação foi concluída.
`data.previous_attributes`	Valores anteriores dos campos alterados.
`metadata`	Objeto livre para correlacionar com seu sistema.
`updated_at`	Horário da conclusão do setup intent.

Status possíveis

Valor	Descrição
`requires_payment_method`	Ainda não há método definido.
`requires_confirmation`	Há método definido, aguardando confirmação.
`processing`	A confirmação está em andamento.
`succeeded`	O método foi salvo e definido como padrão do customer.
`canceled`	O setup intent foi encerrado sem salvar o método.

Exemplo de payload

{
  "id": "evt_ne5d6DQ7LFEhMByu",
  "object": "event",
  "created_at": "2026-05-16T18:32:00Z",
  "data": {
    "object": {
      "id": "seti_ckYF4vdJAj2PgA4n",
      "object": "setup_intent",
      "canceled_at": null,
      "cancellation_reason": null,
      "client_secret": "seti_ckYF4vdJAj2PgA4n_secret_14c5c090160d4a97cfec9c2987c924a696aa602ae1eeec69",
      "created_at": "2026-05-16T18:30:00Z",
      "customer": "cus_3j6ns6HQC5jwx469",
      "last_setup_error": null,
      "latest_attempt": "setatt_L6ZmE4rSCaYzP5wJ",
      "livemode": true,
      "metadata": {},
      "next_action": null,
      "payment_method": "pm_BeaqCMy8BKhxmbHU",
      "payment_method_types": [
        "credit_card"
      ],
      "status": "succeeded",
      "updated_at": "2026-05-16T18:32:00Z",
      "usage": "off_session"
    },
    "previous_attributes": {
      "payment_method": null,
      "status": "processing"
    }
  },
  "livemode": true,
  "organization": "org_w7nwfSkAyiKxfGGV",
  "request": {
    "id": null
  },
  "type": "setup.intent.succeeded"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento setup.intent.succeeded