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": "payment_method is required when confirm is true",
    "param": "payment_method",
    "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`	`payment_method` (um cartão já salvo) 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.

Com payment method

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ó

Com um pm_* já salvo, confirm: true cria e conclui o cadastro na mesma chamada. Cartão novo nunca entra pelo backend: o número do cartão só é coletado no navegador, com Chargefy("pk_*") e confirmSetup() em Concluir cadastro.

Criar e confirmar

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",
    "payment_method": "pm_Be2jZhX6ifbAAP46"
  }'

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

padrão:"false"

Quando true, cria e confirma o setup intent na mesma chamada. Exige payment_method e customer na mesma chamada.

array

padrão:"[\"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": "payment_method is required when confirm is true",
    "param": "payment_method",
    "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 `payment_method`	`400 invalid_request` no parâmetro `payment_method`.
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`.

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": "payment_method is required when confirm is true",
    "param": "payment_method",
    "type": "invalid_request_error"
  }
}

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

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

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