Evento setup.intent.created

Evento `setup.intent.created`

Disparado quando um setup_intent é criado via POST /v1/setup-intents. Use este evento para registrar o início de um fluxo que vai coletar e salvar um método de pagamento para uso futuro, sem cobrar nada no momento. Ele é comum em trials, cobranças sob demanda e cadastros que precisam guardar o cartão antes da primeira cobrança. data.object usa o mesmo shape do objeto setup_intent. O client_secret autoriza a confirmação no browser do comprador; trate esse valor como sensível e evite registrá-lo em logs.

Um setup intent criado ainda não significa que o método foi salvo. Aguarde setup.intent.succeeded para considerar a coleta concluída.

Quando acontece

Situação	Como aparece no payload
Setup intent criado pela API	`data.object.id` traz o novo `seti_*`.
Fluxo ainda aguarda método	`status: "requires_payment_method"`.
Customer já foi definido	`customer` traz o `cus_*`; caso contrário, pode vir `null`.
Apenas cartão é aceito no fluxo atual	`payment_method_types` contém `credit_card`.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (seti_*) para acompanhar o fluxo de salvamento.
Guarde metadata para conciliar esse setup intent com o cadastro ou pedido interno.
Não marque o método como salvo até receber setup.intent.succeeded.
Use client_secret apenas no fluxo autorizado do comprador; não exponha esse valor em logs ou telas administrativas.

Campos importantes

Campo	O que observar
`data.object.id`	Identificador público do setup intent.
`client_secret`	Segredo usado para confirmar a coleta no browser do comprador.
`customer`	Customer a quem o método salvo pertencerá.
`payment_method`	Vem `null` enquanto nenhum método foi salvo.
`payment_method_types`	Tipos aceitos na coleta; atualmente `credit_card`.
`status`	Estado atual do setup intent.
`metadata`	Objeto livre para correlação com seu sistema.

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_771aQJELLNbaKbpF",
  "object": "event",
  "created_at": "2026-05-16T18:30:00Z",
  "data": {
    "object": {
      "id": "seti_kF4eCEtFHchRBhK4",
      "object": "setup_intent",
      "canceled_at": null,
      "cancellation_reason": null,
      "client_secret": "seti_kF4eCEtFHchRBhK4_secret_6e06cc8393b6f089544496c05ccad087db881d3876054535",
      "created_at": "2026-05-16T18:30:00Z",
      "customer": "cus_qb1PVGTkR3AoJjjN",
      "last_setup_error": null,
      "latest_attempt": null,
      "livemode": true,
      "metadata": {},
      "next_action": null,
      "payment_method": null,
      "payment_method_types": [
        "credit_card"
      ],
      "status": "requires_payment_method",
      "updated_at": null,
      "usage": "off_session"
    }
  },
  "livemode": true,
  "organization": "org_1F6N4Af742y2NePF",
  "request": {
    "id": null
  },
  "type": "setup.intent.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento setup.intent.created