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

# Tokenizer

> SDK de tokenização de cartão. Transforme os dados do cartão em um token opaco direto no navegador — o número nunca passa pelo seu servidor.

O **Tokenizer** é um SDK de frontend que transforma os dados sensíveis de um cartão de crédito em um
`tokenId` opaco e descartável, **direto no navegador do comprador**. Esse token é o que você envia em
`creditCard.token` ao [criar uma transação](/pt-BR/transactions) — assim o número do cartão
**nunca passa pelo seu servidor**, reduzindo seu escopo de PCI.

<Warning>
  Os dados sensíveis do cartão (PAN, CVV) são coletados e enviados pelo SDK **no navegador do
  comprador**, direto para o cofre seguro da Z2Pay. **Nunca** envie o número completo do cartão ou o
  CVV para o seu backend: o seu servidor deve receber apenas o `tokenId`.
</Warning>

## Instalação

Você pode carregar o SDK via tag `<script>` (CDN) ou instalá-lo como dependência via npm.

<CodeGroup>
  ```html Script (CDN) theme={null}
  <script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
  <!-- Expõe o construtor em window.Z2Pay.Tokenizer -->
  ```

  ```bash npm theme={null}
  npm install @z2pay/psp-tokenizer
  ```
</CodeGroup>

## Configuração

Crie uma instância do `Tokenizer` passando a configuração abaixo.

<ParamField path="companyId" type="string" required>
  Identificador público da sua company (prefixo `comp_`). É seguro expô-lo no frontend. Você o encontra
  no **Dashboard** (dados da conta) e ele também aparece como `companyId` nas respostas da API e no
  envelope dos webhooks.
</ParamField>

<ParamField path="apiUrl" type="string" required>
  URL base da API da Z2Pay, **sem** o `/v1` — o SDK monta o caminho completo. Use
  `https://api.sandbox.z2pay.com` no sandbox e a URL de produção (veja
  [Ambientes](/pt-BR/ambientes)) em produção.
</ParamField>

<ParamField path="timeout" type="number" default="15000">
  Opcional. Tempo máximo, em milissegundos, para a tokenização. Padrão: `15000` (15s).
</ParamField>

## Tokenizar um cartão

Chame `createCardToken` com os dados do cartão. O SDK retorna um objeto `{ tokenId }`.

<ParamField body="number" type="string" required>
  Número do cartão (PAN), apenas dígitos. Nunca chega ao seu servidor.
</ParamField>

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

<ParamField body="document" type="string" required>
  CPF ou CNPJ do titular, apenas dígitos.
</ParamField>

<ParamField body="cvv" type="string" required>
  Código de segurança do cartão (CVV).
</ParamField>

<ParamField body="expiration" type="string" required>
  Validade no formato `MM/YYYY` (ex.: `12/2030`). O formato `MM/YY` também é aceito.
</ParamField>

<CodeGroup>
  ```html Script (CDN) theme={null}
  <script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
  <script>
    const tokenizer = new window.Z2Pay.Tokenizer({
      companyId: 'comp_irhiwrufxtw7sard5bdhwdio5',
      apiUrl: 'https://api.sandbox.z2pay.com',
    });

    async function tokenizarCartao() {
      const { tokenId } = await tokenizer.createCardToken({
        number: '4111111111111111',
        holder: 'MARIA DA SILVA',
        document: '12345678909',
        cvv: '123',
        expiration: '12/2030',
      });

      // Envie tokenId em creditCard.token ao criar a transação no seu backend
      return tokenId;
    }
  </script>
  ```

  ```js npm theme={null}
  import { Tokenizer } from '@z2pay/psp-tokenizer';

  const tokenizer = new Tokenizer({
    companyId: 'comp_irhiwrufxtw7sard5bdhwdio5',
    apiUrl: 'https://api.sandbox.z2pay.com',
  });

  const { tokenId } = await tokenizer.createCardToken({
    number: '4111111111111111',
    holder: 'MARIA DA SILVA',
    document: '12345678909',
    cvv: '123',
    expiration: '12/2030',
  });

  // Envie tokenId em creditCard.token ao criar a transação no seu backend
  ```
</CodeGroup>

### Resposta

`createCardToken` resolve com um objeto contendo o `tokenId` opaco.

<ResponseField name="tokenId" type="string">
  Token opaco, de **uso único** e válido por **24 horas**. Use-o em `creditCard.token` no
  [POST /transactions](/pt-BR/transactions) — o ideal é tokenizar pouco antes de criar a transação.
  O prefixo e o formato são internos: trate o valor como string opaca e não tente interpretá-lo.
</ResponseField>

```json theme={null}
{
  "tokenId": "tok_cm2upf8b8cdgbzadh99b9jdf7"
}
```

<Note>
  É o **mesmo token** com nomes de campo diferentes conforme o contexto: o Tokenizer retorna como
  `tokenId`; ao criar a transação você envia em `creditCard.token`; no confirm do Checkout é `card.tokenId`. O
  valor não muda — só o nome do campo.
</Note>

## Usando o token na transação

Com o `tokenId` em mãos, crie a transação no seu backend. O token vai em `payments[].creditCard.token`
— **não** existe `creditCard` no topo do corpo. Os campos obrigatórios são `referenceCode` e `items`,
e o pagamento entra no array `payments`:

```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/transactions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceCode": "pedido-2026-0001",
    "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
    "items": [
      { "description": "Plano Pro", "quantity": 1, "amount": 19900 }
    ],
    "payments": [
      {
        "paymentMethod": "credit_card",
        "amount": 19900,
        "creditCard": { "token": "tok_cm2upf8b8cdgbzadh99b9jdf7" }
      }
    ]
  }'
```

<Note>
  A soma de `items` (1 × `19900`) deve bater com a soma de `payments` (`19900`). Valores são sempre
  inteiros em centavos (`19900` = R\$ 199,00). Veja todos os campos em
  [Transações](/pt-BR/transactions).
</Note>

## O que o SDK faz por você

`createCardToken` cuida de tudo entre o formulário e o `tokenId`: os dados sensíveis vão do navegador
direto para o ambiente seguro da Z2Pay, e você recebe de volta apenas a referência opaca. Nada disso
passa pelo seu servidor, e você não orquestra nenhuma etapa.

Como é uma operação de rede, ela pode falhar por um motivo que não é o cartão. Trate a falha como
*"não deu para tokenizar agora"* e ofereça nova tentativa, em vez de acusar o cartão do comprador.

## Erros comuns

* **`Failed to generate any tokens`**: não foi possível tokenizar o cartão. Confira os dados
  informados e o `companyId`. Se persistir com um cartão sabidamente válido, a conta pode não estar
  habilitada para cartão — fale com o suporte.
* **`Timeout`**: a tokenização passou do `timeout` (padrão 15s). Costuma indicar rede lenta do
  comprador.
* **Erro de rede / API**: se a chamada à API da Z2Pay falhar, o SDK lança um `Error` com o status e o
  corpo da resposta. Veja [Erros](/pt-BR/erros) para o formato de erro da API.

## Veja também

<CardGroup cols={2}>
  <Card title="Transações" icon="credit-card" href="/pt-BR/transactions">
    Use o `tokenId` ao criar uma transação de cartão.
  </Card>

  <Card title="Cartões" icon="wallet" href="/pt-BR/cards">
    Cartões salvos e tokenização persistente.
  </Card>

  <Card title="Cartões de teste (sandbox)" icon="flask-conical" href="/pt-BR/sandbox/cartoes">
    Números de cartão para testar no ambiente de sandbox.
  </Card>

  <Card title="Ambientes" icon="server" href="/pt-BR/ambientes">
    URLs de sandbox e produção.
  </Card>
</CardGroup>