Concluir cadastro de cartão

curl -X POST "https://api.chargefy.io/v1/setup-intents/seti_VsaygQA79ZNhy4CQ/confirm" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pm_Be2jZhX6ifbAAP46"
  }'

{
  "id": "seti_VsaygQA79ZNhy4CQ",
  "object": "setup_intent",
  "client_secret": "seti_VsaygQA79ZNhy4CQ_secret_5f49f4ff5dace786d3bf2283772d726462b8e6131d553514",
  "created_at": "2026-08-07T12:00:00Z",
  "last_setup_error": null,
  "livemode": false,
  "next_action": null,
  "payment_method": "pm_Be2jZhX6ifbAAP46",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "usage": "off_session",
  "...": "campos server-side omitidos no navegador"
}

{
  "error": {
    "code": "card_setup_failed",
    "message": "Card could not be saved",
    "type": "card_error"
  }
}

Confirma um cadastro de cartão (setup_intent). Existe uma única operação para backend e navegador; o que muda é a credencial usada:

Origem	Credencial	Dados aceitos
Backend	chave secreta `ch_*`	`payment_method`, `token_id`, `card_id` e `customer`
Navegador	chave publicável `pk_*` + `client_secret`	cartão novo pelo `chargefy.confirmSetup()`

Em sucesso, a Chargefy cria ou reutiliza um payment_method, liga-o ao customer e retorna status: "succeeded". Nenhuma cobrança ou reserva de limite acontece nessa operação. Salvar o cartão não o torna automaticamente o método padrão do customer. Cada confirmação válida cria um setup_attempt. O campo latest_attempt aponta para a tentativa mais recente, inclusive quando ela falha.

Navegador: fluxo recomendado

Use a chave pk_live_* ou pk_test_* exibida em Developers → Chaves de API. A chave publicável pode ficar no JavaScript; o client_secret limita a ação a um único cadastro.

const chargefy = Chargefy("pk_test_...");

const setupIntent = await chargefy.confirmSetup({
  client_secret: clientSecret,
  payment_method_data: {
    type: "credit_card",
    card: {
      number: cardNumber,
      exp_month: expMonth,
      exp_year: expYear,
      cvc,
    },
    billing_details: {
      name: holderName,
    },
  },
});

console.log(setupIntent.status); // "succeeded"
console.log(setupIntent.payment_method); // "pm_*"

confirmSetup() tokeniza o cartão e confirma o cadastro internamente. O seu código não precisa criar, transportar nem gerenciar um token_id.

Crie o cadastro com customer no backend antes de entregar o client_secret ao navegador. Não coloque o client_secret em analytics, logs ou mensagens.

Backend

Use a chave secreta quando o cartão já virou um payment_method ou quando sua integração controla explicitamente o token de baixo nível.

curl -X POST "https://api.chargefy.io/v1/setup-intents/seti_VsaygQA79ZNhy4CQ/confirm" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pm_Be2jZhX6ifbAAP46"
  }'

Parâmetros

string

required

ID do cadastro (seti_*).

string

Obrigatório com chave publicável. Precisa pertencer ao id, organização e ambiente da URL. Não é necessário com chave secreta.

string

Cartão já salvo (pm_*) que pertence ao mesmo customer. Disponível somente no backend.

string

Token de cartão de uso único. O Chargefy.js usa este campo internamente; em integrações novas, prefira confirmSetup() no navegador.

string

Identificador de cartão já salvo no processador. Disponível somente no backend; prefira payment_method quando ele existir.

string

Customer que será dono do cartão. Só pode ser enviado pelo backend e é obrigatório quando o cadastro ainda não possui customer.

Resposta

Com chave secreta, a resposta usa o objeto completo. Com chave publicável, ela traz somente os campos necessários para a tela: identidade, estado, próximo passo, erro, ambiente, tipos aceitos, usage e payment_method.

{
  "id": "seti_VsaygQA79ZNhy4CQ",
  "object": "setup_intent",
  "client_secret": "seti_VsaygQA79ZNhy4CQ_secret_5f49f4ff5dace786d3bf2283772d726462b8e6131d553514",
  "created_at": "2026-08-07T12:00:00Z",
  "last_setup_error": null,
  "livemode": false,
  "next_action": null,
  "payment_method": "pm_Be2jZhX6ifbAAP46",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "usage": "off_session",
  "...": "campos server-side omitidos no navegador"
}

{
  "error": {
    "code": "card_setup_failed",
    "message": "Card could not be saved",
    "type": "card_error"
  }
}

Erros e como tratar

Situação	Resposta	Próxima ação
Chave `pk_*` ausente ou inválida	`401 authentication_failed`	Confira a chave e o ambiente.
`client_secret` ausente	`400 parameter_missing`	Corrija a integração.
Chave, secret, ID ou ambiente não combinam	`404 resource_missing`	Peça ao backend um cadastro válido; não tente descobrir outro recurso.
Cadastro sem customer no navegador	`409 setup_intent_customer_required`	Vincule o customer pelo backend.
Nenhum cartão informado no backend	`400 invalid_request`	Envie `payment_method`, `token_id` ou `card_id`.
Cartão pertence a outro customer	`400 invalid_request`	Use um método do customer correto.
Cartão não pôde ser salvo	`402 card_setup_failed`	Mostre uma mensagem neutra e permita outro cartão.
Customer sem CPF/CNPJ	`422 invalid_request`	Complete o customer antes de repetir.
Cadastro já concluído, cancelado ou em processamento	`409 setup_intent_state_conflict`	Consulte o objeto antes de iniciar outro cadastro.
Falha interna ao vincular ou persistir o cartão	`500 internal_error`	Consulte o cadastro; se ele não estiver concluído, tente novamente com outro request.
Indisponibilidade interna	`500` ou `503 api_error`	Não trate como sucesso; consulte o cadastro antes de repetir.

Uma falha de cartão devolve o cadastro para requires_payment_method, preenche last_setup_error, registra um setup_attempt com status: "failed" e emite setup.intent.failed. Se esse cartão também deve virar o padrão, faça essa escolha separadamente com POST /v1/payment-methods/{id}/attach depois que o cadastro retornar succeeded.

Limitações atuais

Hoje apenas credit_card é aceito.
O cadastro sempre usa usage: "off_session" na prática.
O processador atual não apresenta desafio 3DS neste fluxo; por isso requires_action e next_action fazem parte do contrato, mas não são produzidos nas confirmações atuais.
Confirmar um payment_method existente valida propriedade e estado local, mas não consulta o emissor nem reserva limite.
Tokens são de uso único. Depois de uma falha, confirmSetup() gera outro automaticamente a partir dos novos dados do cartão.

curl -X POST "https://api.chargefy.io/v1/setup-intents/seti_VsaygQA79ZNhy4CQ/confirm" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pm_Be2jZhX6ifbAAP46"
  }'

{
  "id": "seti_VsaygQA79ZNhy4CQ",
  "object": "setup_intent",
  "client_secret": "seti_VsaygQA79ZNhy4CQ_secret_5f49f4ff5dace786d3bf2283772d726462b8e6131d553514",
  "created_at": "2026-08-07T12:00:00Z",
  "last_setup_error": null,
  "livemode": false,
  "next_action": null,
  "payment_method": "pm_Be2jZhX6ifbAAP46",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "usage": "off_session",
  "...": "campos server-side omitidos no navegador"
}

{
  "error": {
    "code": "card_setup_failed",
    "message": "Card could not be saved",
    "type": "card_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Concluir cadastro de cartão

Navegador: fluxo recomendado

Backend

Parâmetros

Resposta

Erros e como tratar

Limitações atuais

​Navegador: fluxo recomendado

​Backend

​Parâmetros

​Resposta

​Erros e como tratar

​Limitações atuais

Navegador: fluxo recomendado

Backend

Parâmetros

Resposta

Erros e como tratar

Limitações atuais