> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Setup Intent

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.*`.

```json theme={}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Identificador do setup intent. Usa o prefixo `seti_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"setup_intent"`.
</ResponseField>

<ResponseField name="canceled_at" type="string | null">
  Data do cancelamento em ISO 8601. Vem `null` enquanto o setup intent não foi
  cancelado.
</ResponseField>

<ResponseField name="cancellation_reason" type="string | null">
  Motivo do cancelamento. Um de `abandoned`, `requested_by_customer` ou
  `duplicate`. Vem `null` enquanto o setup intent não foi cancelado.
</ResponseField>

<ResponseField name="client_secret" type="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.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="customer" type="string | null">
  ID do customer a quem o método salvo pertence. Vem `null` quando o setup
  intent foi criado sem customer.
</ResponseField>

<ResponseField name="last_setup_error" type="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.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar o setup intent com o seu sistema. Quando
  vazio, retorna `{}`.
</ResponseField>

<ResponseField name="next_action" type="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`.
</ResponseField>

<ResponseField name="payment_method" type="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`.
</ResponseField>

<ResponseField name="payment_method_types" type="array">
  Tipos de método aceitos por este setup intent. Hoje sempre `["credit_card"]`.
</ResponseField>

<ResponseField name="status" type="string">
  Estado atual do setup intent. Um de:

  <Expandable title="Valores de status">
    <ResponseField name="requires_payment_method" type="string">
      Ainda não há um método definido. Estado inicial quando o setup intent é
      criado sem `payment_method`.
    </ResponseField>

    <ResponseField name="requires_confirmation" type="string">
      Há um método definido, aguardando confirmação.
    </ResponseField>

    <ResponseField name="processing" type="string">
      A confirmação está em andamento.
    </ResponseField>

    <ResponseField name="succeeded" type="string">
      O método foi salvo e definido como padrão do customer. Estado terminal.
    </ResponseField>

    <ResponseField name="canceled" type="string">
      O setup intent foi encerrado sem salvar o método. Estado terminal.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto o setup intent
  nunca foi atualizado.
</ResponseField>

<ResponseField name="usage" type="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`.
</ResponseField>

## Operações

* [Listar setup intents](/api-reference/setup-intents/list)
* [Criar setup intent](/api-reference/setup-intents/create)
* [Consultar setup intent](/api-reference/setup-intents/get)
* [Atualizar setup intent](/api-reference/setup-intents/update)
* [Confirmar setup intent](/api-reference/setup-intents/confirm)
* [Cancelar setup intent](/api-reference/setup-intents/cancel)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`setup.intent.created`](/api-reference/webhooks/setup.intent.created)
* [`setup.intent.succeeded`](/api-reference/webhooks/setup.intent.succeeded)
* [`setup.intent.failed`](/api-reference/webhooks/setup.intent.failed)
* [`setup.intent.canceled`](/api-reference/webhooks/setup.intent.canceled)

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.