> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Token

> Tokeniza um cartão e devolve um token de uso único.

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**.

<Note>
  **Normalmente você não chama este endpoint diretamente.** O [Chargefy.js](/features/chargefy-js)
  o chama no navegador do comprador, para o número do cartão **nunca tocar o seu
  servidor** — é o caminho recomendado e mantém o seu PCI baixo. Chame
  `POST /v1/tokens` direto apenas se você coleta o cartão em um ambiente próprio
  já certificado para tratar dados de cartão.
</Note>

Por ser usado a partir do navegador do comprador, este endpoint **não exige
chave de API**.

<ParamField body="number" type="string" required>
  Número do cartão. Espaços e traços são ignorados.
</ParamField>

<ParamField body="exp_month" type="number" required>
  Mês de validade (`1`–`12`).
</ParamField>

<ParamField body="exp_year" type="number" required>
  Ano de validade. Aceita quatro dígitos (`2030`) ou dois (`30`).
</ParamField>

<ParamField body="cvc" type="string" required>
  Código de segurança (3 ou 4 dígitos).
</ParamField>

<ParamField body="name" type="string" required>
  Nome do titular impresso no cartão.
</ParamField>

## O que fazer com o token

O `id` retornado (`tok_*`) é de **uso único**. Envie-o ao seu backend e use-o uma
vez como `token_id` ao [confirmar um setup intent](/api-reference/setup-intents/confirm) —
isso salva o cartão como um `payment_method` (`pm_*`) reutilizável. Depois de
consumido, o token morre; para uma nova tentativa, gere outro.

## Erros

| Situação                                 | Resposta                                                                                                                         |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 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` (`tokenization_failed` / `invalid_card`).                                                                     |
| 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`).                                                                                  |

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/tokens" \
    -H "Content-Type: application/json" \
    -d '{
      "number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "123",
      "name": "NOME DO TITULAR"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "tok_123",
    "object": "token",
    "card": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2030,
      "last4": "4242"
    },
    "created_at": "2026-05-16T14:09:27Z",
    "livemode": true
  }
  ```

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

  ```json 400 theme={}
  {
    "error": {
      "code": "invalid_request",
      "message": "Invalid JSON body.",
      "type": "invalid_request_error"
    }
  }
  ```
</ResponseExample>