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
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_secretou 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 que este recurso não faz
Data Object
Este é o formato retornado emcreate, get, update, list, confirm e
cancel, e em data.object dos webhooks setup.intent.*.
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.
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.Último erro ao tentar salvar o cartão. Uma falha devolve o cadastro para
requires_payment_method; uma conclusão posterior limpa este campo.Tentativa de confirmação mais recente (
setatt_*). Retorna null antes da
primeira confirmação ou o objeto expandido com expand[]=latest_attempt.Cartão associado. Retorna o ID
pm_*, null enquanto não existe, ou o objeto
expandido com expand[]=payment_method.Contexto previsto para reutilizar o cartão:
off_session ou on_session.
Hoje o produto cria cadastros com off_session.Operações
- Iniciar cadastro de cartão
- Consultar cadastro de cartão
- Atualizar cadastro de cartão
- Listar cadastros de cartão
- Concluir cadastro
- Listar tentativas
- Cancelar cadastro de cartão
Eventos
O payload leva osetup_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.

