Skip to main content
Um setup_intent representa a intenção de preparar e salvar um método de pagamento de um cliente para usos futuros — sem cobrar nada no momento. Ele existe para os casos em que você quer guardar um cartão antes de fazer a primeira cobrança: assinaturas que começam em trial, cobranças sob demanda, ou qualquer fluxo em que o método é coletado agora e usado depois. É uma máquina de estados de vida curta que acompanha essa coleta do início até o desfecho. Ele nasce quando você o cria pela API e avança por um status que reflete o que falta acontecer: começa em requires_payment_method ou requires_confirmation, e termina em succeeded quando o método é salvo e definido como padrão do customer, ou em canceled quando você o encerra. O setup_intent se prende a um customer (a quem o método salvo pertence) e, ao concluir, ao payment_method resultante. O client_secret é o que autoriza o browser do comprador a confirmar a coleta sem expor a sua chave de API.

​
Data Object

Este é o formato completo retornado em create, get, update, itens de list, nas ações confirm e cancel, e em data.object dos webhooks setup.intent.*. 
{
  "id": "seti_123",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_123_secret_abc",
  "created_at": "2026-05-16T14:09:27Z",
  "customer": "id_456",
  "last_setup_error": null,
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "next_action": null,
  "payment_method": "id_789",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "updated_at": "2026-05-16T15:02:10Z",
  "usage": "off_session"
}
​
id
string
Identificador do setup intent. Usa o prefixo seti_*.
​
object
string
Sempre "setup_intent".
​
canceled_at
string | null
Data do cancelamento em ISO 8601. Vem null enquanto o setup intent não foi cancelado.
​
cancellation_reason
string | null
Motivo do cancelamento. Um de abandoned, requested_by_customer ou duplicate. Vem null enquanto o setup intent não foi cancelado.
​
client_secret
string
Segredo usado para confirmar a coleta no browser do comprador sem expor a chave de API. Não compartilhe em logs nem em superfícies públicas.
​
created_at
string
Data de criação em ISO 8601.
​
customer
string | null
ID do customer a quem o método salvo pertence. Vem null quando o setup intent foi criado sem customer.
​
last_setup_error
object | null
Detalhes do último erro ao tentar salvar o método. Preenchido quando uma confirmação falha; volta para null numa nova tentativa bem-sucedida.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Objeto livre para correlacionar o setup intent com o seu sistema. Quando vazio, retorna {}.
​
next_action
object | null
Próxima ação exigida do comprador para concluir a coleta. A configuração atual de cartão não exige acompanhamento, então normalmente vem null.
​
payment_method
string | object | null
Método de pagamento associado. Vem como o ID (pm_*) por padrão, null enquanto nenhum método foi definido, ou o objeto payment_method completo quando você usa expand[]=payment_method.
​
payment_method_types
array
Tipos de método aceitos por este setup intent. Hoje sempre ["credit_card"].
​
status
string
Estado atual do setup intent. Um de:
​
updated_at
string | null
Data da última atualização em ISO 8601. Vem null enquanto o setup intent nunca foi atualizado.
​
usage
string
Indica como o método salvo será usado depois: off_session (cobranças futuras sem o comprador presente) ou on_session (com o comprador presente). Padrão: off_session.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload sempre carrega o objeto setup_intent completo em data.object; eventos que alteram estado também incluem data.previous_attributes com os valores anteriores dos campos alterados.