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

# Tokenizar um cartão

> Colete um cartão no seu próprio frontend, transforme-o em um token seguro e salve-o para cobrar depois — sem que o número do cartão toque o seu backend.

Este guia mostra, na prática, como **coletar um cartão na sua própria página** e transformá-lo em uma credencial reutilizável (`pm_*`), passo a passo. A regra que mantém o seu PCI baixo: o cartão é **tokenizado no navegador do comprador** e o seu backend só lida com um token opaco.

São três peças, cada uma com um papel:

| Peça                                                               | Papel                                                            |
| ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [`token`](/api-reference/tokens/object) (`tok_*`)                  | O cartão recém-digitado, tokenizado no navegador. **Uso único.** |
| [`setup_intent`](/api-reference/setup-intents/object) (`seti_*`)   | Troca o token por um cartão salvo, sem cobrar.                   |
| [`payment_method`](/api-reference/payment-methods/object) (`pm_*`) | O cartão salvo e reutilizável.                                   |

```mermaid theme={}
sequenceDiagram
  participant Browser as Sua página (Chargefy.js)
  participant App as Seu backend
  participant API as Chargefy API

  Browser->>Browser: cliente digita o cartão
  Browser->>API: POST /v1/tokens (cartão)
  API-->>Browser: token (tok_*)
  Browser->>App: token.id
  App->>API: POST /v1/setup-intents (customer, token_id, confirm: true)
  API-->>App: setup_intent succeeded + payment_method (pm_*)
```

## Passo a passo

<Steps>
  <Step title="Carregue o Chargefy.js na sua página">
    Inclua o script sempre da origem oficial — não faça cópia local, para receber correções de segurança automaticamente.

    ```html theme={}
    <script src="https://api.chargefy.io/v1/chargefy.js"></script>
    ```

    Isso expõe um global `Chargefy`.
  </Step>

  <Step title="Tokenize o cartão no navegador">
    Inicialize com o ambiente (`test` ou `live`) e chame `createPaymentToken` com os campos do cartão. O resultado é um [`token`](/api-reference/tokens/object) de uso único — o número do cartão sai do navegador direto para a Chargefy e **nunca toca o seu backend**.

    ```js theme={}
    const chargefy = Chargefy({ environment: "live" });

    try {
      const token = await chargefy.createPaymentToken({
        number: cardNumber,
        exp_month: expMonth,
        exp_year: expYear,
        cvc: cvc,
        name: holderName,
      });

      // token.id (tok_*) é o que você envia ao backend.
      await fetch("/api/save-card", {
        method: "POST",
        body: JSON.stringify({ token_id: token.id }),
      });
    } catch (err) {
      // err.code / err.message — trate na sua UI (ver "Erros").
    }
    ```

    <Tip>
      Em `environment: "test"`, o token é sintético e nenhum dado vai para a rede — use os [cartões de teste](/features/chargefy-js#cartões-de-teste) para simular aprovação e recusa.
    </Tip>
  </Step>

  <Step title="Tenha um customer com documento">
    O cartão salvo pertence a um cliente. No seu backend, crie (ou reaproveite) o `customer` com `document` (CPF/CNPJ) — obrigatório para salvar cartão no Brasil.

    ```bash theme={}
    curl -X POST "https://api.chargefy.io/v1/customers" \
      -H "Authorization: Bearer {{API_KEY}}" \
      -H "Content-Type: application/json" \
      -d '{
        "document": "11144477735",
        "email": "nome@email.com",
        "name": "Cliente"
      }'
    ```
  </Step>

  <Step title="Salve o cartão com um setup intent">
    No backend, confirme um setup intent enviando o `token_id`. Com `confirm: true`, você cria e confirma em uma só chamada. A resposta traz o `payment_method` (`pm_*`) salvo e já definido como padrão do customer.

    ```bash theme={}
    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_123",
        "token_id": "tok_123"
      }'
    ```

    ```json theme={}
    {
      "id": "seti_123",
      "object": "setup_intent",
      "customer": "cus_123",
      "payment_method": "pm_456",
      "status": "succeeded",
      "usage": "off_session"
    }
    ```
  </Step>

  <Step title="Cobre quando precisar">
    Com o `pm_*` salvo, cobre a qualquer momento criando um payment intent que referencia o `customer` e o `payment_method`.

    ```bash theme={}
    curl -X POST "https://api.chargefy.io/v1/payment-intents" \
      -H "Authorization: Bearer {{API_KEY}}" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 9900,
        "confirm": true,
        "currency": "brl",
        "customer": "cus_123",
        "payment_method": "pm_456"
      }'
    ```
  </Step>
</Steps>

## Erros

A validação no navegador é a primeira barreira de UX; a **aprovação ou recusa** definitiva do cartão acontece quando você cobra. O `createPaymentToken` rejeita a Promise com um erro que carrega `type`, `code`, `message` e, quando aplicável, `param`.

| `code`                                         | Quando acontece                                   |
| ---------------------------------------------- | ------------------------------------------------- |
| `invalid_number`                               | Número do cartão ausente ou com tamanho inválido. |
| `invalid_expiry_month` / `invalid_expiry_year` | Validade inválida.                                |
| `invalid_cvc`                                  | CVC com menos de 3 ou mais de 4 dígitos.          |
| `invalid_name`                                 | Nome do titular ausente.                          |
| `tokenization_failed` / `invalid_card`         | O cartão foi recusado na tokenização.             |

<Warning>
  Não reaproveite um token: ele é de uso único. Se a confirmação falhar, gere um novo token e tente de novo.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Tokenização de cartão" icon="credit-card" href="/features/card-tokenization">
    O conceito completo: token, setup intent e cartão salvo.
  </Card>

  <Card title="Chargefy.js" icon="code" href="/features/chargefy-js">
    Referência do script de tokenização no navegador.
  </Card>

  <Card title="Objeto token" icon="cube" href="/api-reference/tokens/object">
    Contrato do token de uso único.
  </Card>

  <Card title="Checkout white-label" icon="bolt" href="/features/white-label-checkout">
    Cobrar cartão na sua própria página, com a sua marca.
  </Card>
</CardGroup>