Cadastro de cartão

Um setup_intent é o cadastro de cartão da API Chargefy. Ele acompanha a tentativa de salvar um cartão no customer para uma cobrança futura, sem cobrar nada naquele momento.

Nome no produto: usamos “Cadastro de cartão” nas telas e nesta documentação. setup_intent, seti_*, as rotas e os eventos setup.intent.* continuam sendo os identificadores técnicos da API.

Quando usar hoje

Caso de uso	O que o cadastro resolve
Assinatura com período grátis	Coleta o cartão agora e deixa a assinatura pronta para cobrar quando o trial terminar.
Checkout próprio ou white-label	Permite salvar o cartão dentro da sua interface, usando Chargefy.js, sem expor a chave secreta.
Cobrança futura sob demanda	Gera um `payment_method` reutilizável para uma venda posterior cujo valor ainda não existe.
Cliente precisa trocar ou adicionar cartão	Salva o novo cartão. Se uma assinatura estiver aguardando esse cadastro, também atualiza a assinatura e encerra a pendência.

Uma assinatura em trial criada sem cartão pode trazer pending_setup_intent: "seti_*". Nesse caso, o cadastro já foi criado pela Chargefy: consulte-o, colete o cartão e conclua-o. O Portal do Cliente e a ação Coletar método do Dashboard também conseguem concluir essa pendência ao salvar ou escolher um cartão.

O que acontece na conclusão

Seu backend cria o cadastro para um customer.
O navegador chama confirmSetup(); o token de uso único fica interno ao SDK.
O navegador conclui com client_secret ou o backend conclui com a chave de API.
A Chargefy salva um payment_method (pm_*) e o vincula ao customer.
Se uma assinatura apontava para esse cadastro em pending_setup_intent, ela recebe o cartão e a pendência é removida.

O cadastro não altera automaticamente o cartão padrão do customer. Quando essa for a intenção, escolha o padrão explicitamente com a operação de vincular payment method.

O que este recurso não faz

Cadastro de cartão não cobra, não reserva limite, não faz pré-autorização e não confirma que haverá saldo na cobrança futura. Confirmar um pm_* já salvo apenas verifica se ele pertence ao customer; não consulta novamente o emissor. Para movimentar dinheiro, crie um Payment Intent.

Limitação atual	Consequência prática
Apenas `credit_card`	Pix, boleto e outros métodos não podem ser cadastrados para reutilização por este objeto.
Sem valor (`amount`)	Não existe cobrança ou validação financeira durante o cadastro.
`next_action` sem ação disponível	Hoje a confirmação de cartão é síncrona e o campo retorna `null`.
`processing` reservado no contrato	O fluxo atual normalmente sai da confirmação direto para `succeeded` ou volta para `requires_payment_method`.
Sem expiração própria	Um cadastro avulso pode continuar pendente até ser concluído ou cancelado. Quando ele pertence a uma assinatura terminal, a Chargefy o cancela automaticamente.
Um customer por cadastro	O cartão salvo pertence ao customer definido; use outro cadastro para outro cliente.

Data Object

Este é o formato retornado em create, get, update, list, confirm e cancel, e em data.object dos webhooks setup.intent.*.

{
  "id": "seti_6qpAQKujZ17qnXAJ",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_6qpAQKujZ17qnXAJ_secret_4d258ea9279857f68a063b6f834c5a271499c5c6f1eeaf7e",
  "created_at": "2026-05-16T14:09:27Z",
  "customer": "cus_KRiUnNCtBjHwAbHp",
  "last_setup_error": null,
  "latest_attempt": "setatt_L6ZmE4rSCaYzP5wJ",
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_rdRooUAivf5RK2ha",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "updated_at": "2026-05-16T15:02:10Z",
  "usage": "off_session"
}

string

Identificador do cadastro de cartão. Usa o prefixo seti_*.

string

Sempre "setup_intent".

string | null

Data do cancelamento em ISO 8601. Vem null enquanto o cadastro não foi cancelado.

string | null

Motivo do cancelamento. Vem null enquanto o cadastro não foi cancelado.

Show Valores de cancellation_reason

string

O fluxo não foi concluído ou deixou de ser necessário. A Chargefy também usa este motivo ao encerrar a pendência de uma assinatura que terminou.

string

O cliente pediu para não salvar o cartão.

string

Outro cadastro já cobre a mesma coleta.

string

Autoriza consultar e concluir somente este cadastro no navegador quando usado junto de uma chave publicável. Envie-o apenas à página do comprador que fará a coleta; não coloque em analytics ou logs. Ele não permite listar cadastros, trocar customer ou alterar metadata.

string

Data de criação em ISO 8601.

string | null

Customer que será dono do cartão salvo. Pode ser null em um cadastro criado pelo backend, mas precisa estar definido antes da confirmação no navegador.

object | null

Último erro ao tentar salvar o cartão. Uma falha devolve o cadastro para requires_payment_method; uma conclusão posterior limpa este campo.

Show Campos de last_setup_error

string

Categoria: card_error, invalid_request_error ou api_error.

string

Código estável para tratamento programático.

string

Descrição voltada ao desenvolvedor.

string

Parâmetro relacionado ao erro, quando aplicável.

string | object | null

Tentativa de confirmação mais recente (setatt_*). Retorna null antes da primeira confirmação ou o objeto expandido com expand[]=latest_attempt.

boolean

true em produção; false no ambiente de teste.

object

Dados livres definidos pela sua integração. Quando vazio, retorna {}.

object | null

Próxima ação exigida do comprador. Na implementação atual de cartão retorna null.

string | object | null

Cartão associado. Retorna o ID pm_*, null enquanto não existe, ou o objeto expandido com expand[]=payment_method.

array

Hoje sempre ['credit_card'].

string

Estado atual do cadastro.

Show Valores de status

string

Aguarda um cartão. Também é o estado após uma tentativa de salvamento falhar.

string

Já possui um payment_method, mas ainda aguarda a conclusão.

string

Exige uma ação adicional do comprador descrita em next_action. O processador atual não produz este estado no fluxo de cartão.

string

Reservado para confirmações assíncronas. Não é o retorno normal do fluxo atual de cartão.

string

O cartão foi salvo e vinculado ao customer. Estado terminal.

string

O cadastro foi encerrado sem salvar um novo cartão. Estado terminal.

string | null

Data da última alteração em ISO 8601.

string

Contexto previsto para reutilizar o cartão: off_session ou on_session. Hoje o produto cria cadastros com off_session.

Operações

Eventos

O payload leva o setup_intent completo em data.object. Eventos de mudança também levam os valores anteriores em data.previous_attributes.

Salvar cartão para cobrar depois

Veja o fluxo completo com Chargefy.js, customer e payment method.

Concluir cadastro

Use pk_* e client_secret no navegador ou ch_* no backend.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Cadastro de cartão

Quando usar hoje

O que acontece na conclusão

O que este recurso não faz

Data Object

Operações

Eventos

Salvar cartão para cobrar depois

Concluir cadastro

​Quando usar hoje

​O que acontece na conclusão

​O que este recurso não faz

​Data Object

​Operações

​Eventos

Salvar cartão para cobrar depois

Concluir cadastro

Quando usar hoje

O que acontece na conclusão

O que este recurso não faz

Data Object

Operações

Eventos