Criar um token

curl -X POST "https://api.chargefy.io/v1/tokens" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2030,
    "cvc": "123",
    "name": "NOME DO TITULAR"
  }'

{
  "id": "tok_Jfz869GPd6X84ZNg",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "livemode": true
}

{
  "error": {
    "code": "invalid_number",
    "message": "The card number is not a valid card number.",
    "param": "number",
    "type": "card_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid JSON body.",
    "type": "invalid_request_error"
  }
}

Troca os dados de um cartão por um token opaco de uso único. O número (PAN) e o CVC são trocados pelo token e não são retornados nem armazenados.

Normalmente você não chama este endpoint diretamente. O Chargefy.js o chama internamente durante confirmSetup(), para o número do cartão nunca tocar o seu servidor. Chame POST /v1/tokens direto apenas se você realmente precisa controlar o token de baixo nível.

O endpoint exige uma chave publicável pk_*. Ela define a organização e o ambiente do token; uma chave secreta ch_* não é aceita aqui. Todos os cinco campos são obrigatórios — não há campos opcionais nem defaults. Qualquer campo inválido retorna 402 card_error com o param correspondente.

string

required

Número do cartão, com 13 a 19 dígitos. Espaços e traços são ignorados.

number

required

Mês de validade (1–12).

number

required

Ano de validade. Aceita quatro dígitos (2030) ou dois (30).

string

required

Código de segurança (3 ou 4 dígitos).

string

required

Nome do titular impresso no cartão. Mínimo de 2 caracteres.

O que a Chargefy resolve sozinha

card.brand e card.last4 — derivados do número do cartão; o PAN e o CVC não são retornados nem armazenados.
Normalização — caracteres não numéricos são removidos de number e cvc; ano com dois dígitos vira quatro (30 → 2030).

O que fazer com o token

O id retornado (tok_*) é de uso único. Use-o uma vez como token_id ao concluir o cadastro. No fluxo recomendado, confirmSetup() faz essa troca sem expor o token ao seu código. Depois de consumido, o token morre; para uma nova tentativa, gere outro.

Erros

Situação	Resposta
Chave `pk_*` ausente ou inválida	`401 authentication_error`.
Número, validade, CVC ou nome inválidos	`402` `card_error` (`invalid_number`, `invalid_expiry_month`, `invalid_expiry_year`, `invalid_cvc`, `invalid_name`) com `param`.
Cartão recusado na tokenização	`402` `card_error` com o motivo estável disponível (`generic_decline`, `expired_card`, `incorrect_number`, `incorrect_cvc`, entre outros); `tokenization_failed` é o fallback quando não há sinal confiável.
Corpo da requisição não é JSON válido	`400` `invalid_request_error` (`invalid_request`).
Tokenização temporariamente indisponível	`503` `api_error` (`tokenization_unavailable`).

curl -X POST "https://api.chargefy.io/v1/tokens" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2030,
    "cvc": "123",
    "name": "NOME DO TITULAR"
  }'

{
  "id": "tok_Jfz869GPd6X84ZNg",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "livemode": true
}

{
  "error": {
    "code": "invalid_number",
    "message": "The card number is not a valid card number.",
    "param": "number",
    "type": "card_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid JSON body.",
    "type": "invalid_request_error"
  }
}

curl -X POST "https://api.chargefy.io/v1/tokens" \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2030,
    "cvc": "123",
    "name": "NOME DO TITULAR"
  }'

{
  "id": "tok_Jfz869GPd6X84ZNg",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "livemode": true
}

{
  "error": {
    "code": "invalid_number",
    "message": "The card number is not a valid card number.",
    "param": "number",
    "type": "card_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid JSON body.",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

O que a Chargefy resolve sozinha

O que fazer com o token

Erros

​O que a Chargefy resolve sozinha

​O que fazer com o token

​Erros

O que a Chargefy resolve sozinha

O que fazer com o token

Erros