Pular para o conteúdo principal
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 — assim o número do cartão nunca passa pelo seu servidor, reduzindo seu escopo de PCI.
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 do 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.

​
Por que usar o SDK

Quando o comprador digita os dados do cartão no checkout, o SDK envia o número (PAN), o CVV e a validade diretamente do navegador para o cofre (vault) e para os PSPs — nunca para o seu backend. O que o seu servidor recebe é apenas um tokenId opaco: uma string que só faz sentido dentro do Z2Pay e que, sozinha, não revela nada sobre o cartão.

Sem dados de cartão no seu servidor

O PAN/CVV vão do navegador direto para o cofre. Você só vê o tokenId.

Token descartável

O tokenId é de uso temporário e expira automaticamente (TTL de 24h).

​
Instalação

Você pode carregar o SDK via tag <script> (CDN) ou instalá-lo como dependência via npm. 
<script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
<!-- Expõe o construtor em window.Z2Pay.Tokenizer -->

​
Configuração

Crie uma instância do Tokenizer passando a configuração abaixo.
​
companyId
string
obrigatório
Identificador público da sua company. É seguro expô-lo no frontend.
​
apiUrl
string
obrigatório
URL base da API do Z2Pay. Use https://api.sandbox.z2pay.com no sandbox e a URL de produção (veja Ambientes) em produção.
​
timeout
number
padrão:"15000"
Opcional. Tempo máximo, em milissegundos, para a tokenização. Padrão: 15000 (15s).

​
Tokenizar um cartão

Chame createCardToken com os dados do cartão. O SDK retorna um objeto { tokenId }.
​
number
string
obrigatório
Número do cartão (PAN), apenas dígitos. Nunca chega ao seu servidor.
​
holder
string
obrigatório
Nome do titular, conforme impresso no cartão.
​
document
string
obrigatório
CPF ou CNPJ do titular, apenas dígitos.
​
cvv
string
obrigatório
Código de segurança do cartão (CVV).
​
expiration
string
obrigatório
Validade no formato MM/YYYY (ex.: 12/2030). O formato MM/YY também é aceito.
<script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
<script>
  const tokenizer = new window.Z2Pay.Tokenizer({
    companyId: 'comp_a1b2c3d4',
    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>

​
Resposta

createCardToken resolve com um objeto contendo o tokenId opaco.
​
tokenId
string
Token opaco de uso temporário. Use-o em creditCard.token no POST /transactions. Expira em 24h.
{
  "tokenId": "tok_a1b2c3d4e5f6"
}
O prefixo e o formato exato do tokenId são definidos internamente — trate o valor como uma string opaca e não tente interpretá-lo.
O tokenId é válido por 24 horas (TTL) e de uso único. Tokenize o cartão pouco antes de criar a transação.

​
Usando o token na transação

Com o tokenId em mãos, crie a transação no seu backend informando-o em creditCard.token: 
curl -X POST https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 19900,
    "paymentMethod": "credit_card",
    "creditCard": {
      "token": "tok_a1b2c3d4e5f6"
    }
  }'
Este exemplo é ilustrativo do uso do token. Os campos exatos da criação de transação estão na página Transações. Valores são sempre inteiros em centavos (19900 = R$ 199,00).

​
Como funciona por baixo

Ao chamar createCardToken, o SDK — rodando no navegador do comprador — envia os dados sensíveis (PAN, CVV) diretamente para o cofre seguro (vault) e para os PSPs do Z2Pay, em paralelo, e troca tudo por um único tokenId opaco. Os dados do cartão nunca passam pelo seu backend; você recebe apenas o tokenId. Toda a comunicação com o cofre, os PSPs e o serviço de tokenização é tratada pelo SDK — você não precisa orquestrar nada disso na mão.

​
Erros comuns

  • Failed to generate any tokens: nenhum PSP ou cofre conseguiu tokenizar o cartão. Causas comuns: dados do cartão inválidos ou nenhum PSP configurado para a company. Verifique o companyId e os dados informados.
  • Timeout: a tokenização passou do timeout (padrão 15s). Costuma indicar rede lenta do comprador.
  • Erro de rede / API: se a chamada à API do Z2Pay falhar, o SDK lança um Error com o status e o corpo da resposta. Veja Erros para o formato de erro da API.

​
Veja também

Transações

Use o tokenId ao criar uma transação de cartão.

Cartões

Cartões salvos e tokenização persistente.

Cartões de teste (sandbox)

Números de cartão para testar no ambiente de sandbox.

Ambientes

URLs de sandbox e produção.