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

# Chargefy.js (tokenização no browser)

> O script de tokenização da Chargefy: troca os dados do cartão por um token de uso único no navegador do comprador, sem que o número do cartão toque o seu servidor.

**Chargefy.js** é o script de browser que transforma os dados de um cartão em um **token de uso único** (`token_id`) direto no navegador do comprador. O número do cartão (PAN) e o código de segurança (CVC) **nunca** passam pelo seu backend — você recebe só um token opaco, que o seu servidor envia para a API com a sua chave secreta.

É a peça que falta para montar um **Checkout white-label**: você controla 100% da UI, e mantém o seu PCI baixo porque os dados sensíveis do cartão saem do navegador direto para a Chargefy.

<Note>
  Chargefy.js só **tokeniza**. Ele não cobra, não cria customer e não conhece a
  sua chave secreta. Cobrar e salvar cartão acontecem no seu backend, com o
  `token_id` que o script devolve — veja [Checkout
  white-label](/features/white-label-checkout) e [Tokenização de
  cartão](/features/card-tokenization).
</Note>

## Carregar o script

Inclua o script servido pela Chargefy. Carregue-o 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`.

## Inicializar

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

| Parâmetro     | Valores              | Descrição                                                                                                                                                               |
| ------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment` | `"test"` \| `"live"` | Define o ambiente. Em `test`, o token é sintético e nenhum dado vai para a rede — use os cartões de teste listados abaixo. Em `live`, o cartão é tokenizado de verdade. |

<Tip>
  Use `test` enquanto desenvolve e `live` em produção, espelhando o ambiente da
  chave (`ch_test_` / `ch_live_`) que o seu backend usa para confirmar. Misturar
  ambientes faz a confirmação falhar.
</Tip>

## Tokenizar um cartão

`createPaymentToken` recebe os campos do cartão e devolve uma `Promise` com o token.

```js theme={}
try {
  const token = await chargefy.createPaymentToken({
    number: "4242424242424242",
    exp_month: 12,
    exp_year: 2030,
    cvc: "123",
    name: "MARIA SOUZA",
  });

  // token.id -> envie ao seu backend para confirmar
  console.log(token.id); // "tok_123"
} catch (err) {
  // err.code / err.message — veja "Erros"
}
```

### Campos do cartão

<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 4 dígitos (`2030`) ou 2 dígitos (`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 token retornado

```json theme={}
{
  "id": "tok_123",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  }
}
```

<ResponseField name="id" type="string">
  O `token_id` de **uso único**. Envie ao seu backend e use-o uma vez para
  confirmar um setup intent ou um payment intent. Depois de consumido, ele morre
  — para uma nova tentativa, gere outro token.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `token`.
</ResponseField>

<ResponseField name="card" type="object">
  Dados não sensíveis para você exibir um resumo do cartão (`brand`,
  `exp_month`, `exp_year`, `last4`). O número completo e o CVC nunca são
  retornados.
</ResponseField>

## O que fazer com o token

O `token_id` é o que liga o browser ao seu backend. O fluxo padrão:

```mermaid theme={}
flowchart LR
  B[Browser<br/>Chargefy.js] -- token_id --> S[Seu backend]
  S -- token_id + chave secreta --> A[Chargefy API]
  A -- pm_* / cobrança --> S
```

1. O browser tokeniza e te entrega o `token_id`.
2. O seu backend envia o `token_id` para a Chargefy (com a sua chave secreta) para **salvar o cartão** ([setup intent](/features/card-tokenization)) e/ou **cobrar** ([payment intent](/features/white-label-checkout)).
3. O cartão salvo vira um `payment_method` (`pm_*`) reutilizável.

## Erros

`createPaymentToken` **rejeita** a Promise com um erro que carrega `type`, `code`, `message` e, quando aplicável, `param` — o mesmo formato dos [erros da API](/api-reference/errors).

```js theme={}
try {
  await chargefy.createPaymentToken(card);
} catch (err) {
  // err.type    -> "card_error" | "invalid_request_error" | "api_error"
  // err.code    -> "invalid_number", "invalid_cvc", "tokenization_failed", ...
  // err.param   -> "number", "cvc", ... (quando o erro é de um campo)
  // err.message -> texto pronto para log (use uma mensagem sua na UI)
}
```

| `code`                     | Quando acontece                                              |
| -------------------------- | ------------------------------------------------------------ |
| `invalid_number`           | Número do cartão ausente ou com tamanho inválido.            |
| `invalid_name`             | Nome do titular ausente.                                     |
| `invalid_expiry_month`     | Mês fora de `1`–`12`.                                        |
| `invalid_expiry_year`      | Ano de validade inválido.                                    |
| `invalid_cvc`              | CVC com menos de 3 ou mais de 4 dígitos.                     |
| `invalid_environment`      | `Chargefy()` inicializado sem `test`/`live`.                 |
| `tokenization_failed`      | O cartão foi recusado na tokenização (dados inconsistentes). |
| `invalid_card`             | O cartão é inválido.                                         |
| `tokenization_unavailable` | Indisponibilidade temporária — peça para tentar de novo.     |

<Warning>
  A validação no browser é uma primeira barreira de UX, não a decisão final. A
  **aprovação ou recusa** do cartão acontece quando você cobra um [payment
  intent](/features/white-label-checkout) no backend — é lá que você trata
  recusa e retry.
</Warning>

## Cartões de teste

Em `environment: "test"`, o número do cartão escolhe o cenário. O token é sintético (nenhum dado vai para a rede) e carrega o cenário até a confirmação no backend.

| Número             | Resultado na cobrança                                |
| ------------------ | ---------------------------------------------------- |
| `4242424242424242` | Aprovado.                                            |
| `4000000000003220` | Autorizado para captura posterior.                   |
| `4000000000000002` | Recusado com `payment_error.code = generic_decline`. |
| `4000000000009995` | Saldo insuficiente.                                  |
| `4000000000000069` | Cartão expirado.                                     |
| `4000000000000127` | Código de segurança incorreto.                       |
| `4000000000000119` | Erro de processamento.                               |

Use qualquer CVC de 3 dígitos e uma validade futura. A tabela completa de cartões para todos os `payment_error.code` públicos fica em [Sandbox](/integrate/sandbox#falhas-de-cartao).

## Content Security Policy

Se a sua página usa CSP, libere a Chargefy para carregar e se comunicar:

```
script-src  https://api.chargefy.io;
connect-src https://api.chargefy.io;
```

O script faz a troca segura do cartão para você. Se a sua CSP for restritiva e a tokenização for bloqueada, fale com o [suporte](https://chargefy.io/docs/support).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Checkout white-label" icon="bolt" href="/features/white-label-checkout">
    Monte uma tela de pagamento com a sua marca, de ponta a ponta.
  </Card>

  <Card title="Tokenização de cartão" icon="credit-card" href="/features/card-tokenization">
    Salve o cartão para cobrar depois (assinaturas, recompra).
  </Card>
</CardGroup>