Skip to main content
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 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.

​
Instalação

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

​
Configuração

Crie uma instância do Tokenizer passando a configuração abaixo.
​
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.
​
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) em produção.
​
number
default:"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 }.
​
string
required
Número do cartão (PAN), apenas dígitos. Nunca chega ao seu servidor.
​
string
required
Nome do titular, conforme impresso no cartão.
​
string
required
CPF ou CNPJ do titular, apenas dígitos.
​
string
required
Código de segurança do cartão (CVV).
​
string
required
Validade no formato MM/YYYY (ex.: 12/2030). O formato MM/YY também é aceito.

​
Resposta

createCardToken resolve com um objeto contendo o tokenId opaco.
​
string
Token opaco, de uso único e válido por 24 horas. Use-o em creditCard.token no POST /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.
É 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.

​
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:
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.

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