Iniciar cadastro de cartão

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

{
  "id": "seti_miN78Be7PtbTiq4J",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_miN78Be7PtbTiq4J_secret_820b133e1d69189a9b88f6bf4b997dbb135c557585e1084f",
  "created_at": "2026-05-16T18:30:00Z",
  "customer": "cus_AAMdwCYQ7FEPFrBX",
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": null,
  "payment_method_types": [
    "credit_card"
  ],
  "status": "requires_payment_method",
  "updated_at": null,
  "usage": "off_session"
}

{
  "error": {
    "code": "invalid_request",
    "message": "token_id and card_id can only be used when confirm is true",
    "param": "token_id",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Customer not found.",
    "param": "customer",
    "type": "invalid_request_error"
  }
}

Cria um cadastro de cartão (setup_intent), usado para salvar um cartão sem cobrar nada — por isso não existe campo de valor aqui. A cobrança acontece depois, pela assinatura ou por um payment intent que você cria com o pm_* salvo. Nenhum campo é obrigatório. Um POST vazio já cria um cadastro em requires_payment_method, sem customer — você define o resto depois, no update ou no confirm. O que existe são exigências condicionais entre os campos:

Se você enviar…	Então também precisa de…
`payment_method`	`customer` (o método precisa de dono)
`confirm: true`	um cartão: `payment_method`, `token_id` ou `card_id`
`token_id` ou `card_id`	`confirm: true` e `customer`

Formas de iniciar

(a) Vazio ou só com customer — o fluxo padrão

Crie cedo, colete o cartão depois. É o formato recomendado: o backend cria o cadastro para o customer e o navegador o conclui com client_secret e Chargefy.js.

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

(b) Com um cartão já salvo

Quando o cartão já existe como pm_* e você quer concluir o cadastro ou uma pendência de assinatura. O cadastro nasce em requires_confirmation.

Concluir com um pm_* existente verifica a propriedade do cartão, mas não faz uma nova autorização no emissor e não reserva limite.

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

(c) Criar e confirmar numa chamada só

Quando o seu backend já recebeu um token_id recém-tokenizado, ele pode criar e concluir em uma chamada. É o atalho server-side; para manter o token no navegador, use Concluir cadastro com Chargefy("pk_*") e confirmSetup().

curl -X POST "https://api.chargefy.io/v1/setup-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true,
    "customer": "cus_AAMdwCYQ7FEPFrBX",
    "token_id": "tok_ahVV5g6vJZYCx15s"
  }'

Parâmetros

string

Customer que receberá o método salvo (cus_*). Opcional na criação, mas obrigatório junto de payment_method e na confirmação — o método salvo sempre pertence a um customer.

string

Cartão já salvo (pm_*) que será associado. Quando informado, o setup_intent nasce com status: "requires_confirmation". Exige customer. Quando omitido, o setup intent nasce em requires_payment_method e o método é definido depois.

boolean

default:"false"

Quando true, cria e confirma o setup intent na mesma chamada. Exige um cartão na mesma chamada: payment_method, token_id ou card_id.

string

Token de cartão de uso único (tok_*) gerado no browser. Só pode ser enviado junto com confirm: true e customer.

string

ID de cartão já salvo que pertence a este customer. Só pode ser enviado junto com confirm: true e customer. A propriedade é validada antes de salvar; um cartão que não pertence ao customer é recusado. Prefira token_id no fluxo padrão.

array

default:"[\"credit_card\"]"

Tipos de método aceitos. Hoje o único valor aceito é ["credit_card"]; omita o campo.

object

Metadata livre. Quando omitido, o objeto retorna {}.

{
  "id": "seti_miN78Be7PtbTiq4J",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_miN78Be7PtbTiq4J_secret_820b133e1d69189a9b88f6bf4b997dbb135c557585e1084f",
  "created_at": "2026-05-16T18:30:00Z",
  "customer": "cus_AAMdwCYQ7FEPFrBX",
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": null,
  "payment_method_types": [
    "credit_card"
  ],
  "status": "requires_payment_method",
  "updated_at": null,
  "usage": "off_session"
}

{
  "error": {
    "code": "invalid_request",
    "message": "token_id and card_id can only be used when confirm is true",
    "param": "token_id",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Customer not found.",
    "param": "customer",
    "type": "invalid_request_error"
  }
}

Erros e limites relevantes

Situação	Resposta
`confirm: true` sem cartão	`400 invalid_request` — envie `payment_method`, `token_id` ou `card_id`.
`token_id` ou `card_id` sem `confirm: true`	`400 invalid_request`.
Cartão informado sem customer	`400 invalid_request` no parâmetro `customer`.
Customer ou `payment_method` não existe	`404 resource_missing`.
Cartão pertence a outro customer	`402 card_error`.
Tipo diferente de `credit_card`	`400 invalid_request` no parâmetro `payment_method_types`.
Chave ausente, inválida ou de outro ambiente	`401 authentication_failed`.

Uma tentativa que cria e conclui com token_id consome esse token. Se o salvamento falhar, gere um token novo antes de tentar outra vez.

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

{
  "id": "seti_miN78Be7PtbTiq4J",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_miN78Be7PtbTiq4J_secret_820b133e1d69189a9b88f6bf4b997dbb135c557585e1084f",
  "created_at": "2026-05-16T18:30:00Z",
  "customer": "cus_AAMdwCYQ7FEPFrBX",
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": null,
  "payment_method_types": [
    "credit_card"
  ],
  "status": "requires_payment_method",
  "updated_at": null,
  "usage": "off_session"
}

{
  "error": {
    "code": "invalid_request",
    "message": "token_id and card_id can only be used when confirm is true",
    "param": "token_id",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Customer not found.",
    "param": "customer",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Iniciar cadastro de cartão

Formas de iniciar

(a) Vazio ou só com customer — o fluxo padrão

(b) Com um cartão já salvo

(c) Criar e confirmar numa chamada só

Parâmetros

Erros e limites relevantes

​Formas de iniciar

​(a) Vazio ou só com customer — o fluxo padrão

​(b) Com um cartão já salvo

​(c) Criar e confirmar numa chamada só

​Parâmetros

​Erros e limites relevantes

Formas de iniciar

(a) Vazio ou só com customer — o fluxo padrão

(b) Com um cartão já salvo

(c) Criar e confirmar numa chamada só

Parâmetros

Erros e limites relevantes