Saltar al contenido principal
El Tokenizer es un SDK de frontend que transforma los datos sensibles de una tarjeta de crédito en un tokenId opaco y desechable, directamente en el navegador del comprador. Ese token es el que envías en creditCard.token al crear una transacción — así el número de la tarjeta nunca pasa por tu servidor, reduciendo tu alcance de PCI.
Los datos sensibles de la tarjeta (PAN, CVV) se recopilan y envían por el SDK en el navegador del comprador, directamente al cofre seguro (vault) de Z2Pay. Nunca envíes el número completo de la tarjeta ni el CVV a tu backend: tu servidor debe recibir únicamente el tokenId.

​
Por qué usar el SDK

Cuando el comprador ingresa los datos de la tarjeta en el checkout, el SDK envía el número (PAN), el CVV y la fecha de vencimiento directamente desde el navegador al cofre (vault) y a los PSPs — nunca a tu backend. Lo que tu servidor recibe es únicamente un tokenId opaco: una cadena que solo tiene sentido dentro de Z2Pay y que, por sí sola, no revela nada sobre la tarjeta.

Sin datos de tarjeta en tu servidor

El PAN/CVV van del navegador directamente al cofre. Tú solo ves el tokenId.

Token desechable

El tokenId es de uso temporal y expira automáticamente (TTL de 24h).

​
Instalación

Puedes cargar el SDK mediante una etiqueta <script> (CDN) o instalarlo como dependencia vía npm. 
<script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
<!-- Expone el constructor en window.Z2Pay.Tokenizer -->

​
Configuración

Crea una instancia del Tokenizer pasando la configuración a continuación.
​
companyId
string
requerido
Identificador público de tu company. Es seguro exponerlo en el frontend.
​
apiUrl
string
requerido
URL base de la API de Z2Pay. Usa https://api.sandbox.z2pay.com en sandbox y la URL de producción (consulta Entornos) en producción.
​
timeout
number
predeterminado:"15000"
Opcional. Tiempo máximo, en milisegundos, para la tokenización. Predeterminado: 15000 (15s).

​
Tokenizar una tarjeta

Llama a createCardToken con los datos de la tarjeta. El SDK retorna un objeto { tokenId }.
​
number
string
requerido
Número de la tarjeta (PAN), solo dígitos. Nunca llega a tu servidor.
​
holder
string
requerido
Nombre del titular, tal como aparece impreso en la tarjeta.
​
document
string
requerido
CPF o CNPJ del titular, solo dígitos.
​
cvv
string
requerido
Código de seguridad de la tarjeta (CVV).
​
expiration
string
requerido
Vencimiento en el formato MM/YYYY (ej: 12/2030). El formato MM/YY también es aceptado.
<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 tokenizarTarjeta() {
    const { tokenId } = await tokenizer.createCardToken({
      number: '4111111111111111',
      holder: 'MARIA DA SILVA',
      document: '12345678909',
      cvv: '123',
      expiration: '12/2030',
    });

    // Envía tokenId en creditCard.token al crear la transacción en tu backend
    return tokenId;
  }
</script>

​
Respuesta

createCardToken se resuelve con un objeto que contiene el tokenId opaco.
​
tokenId
string
Token opaco de uso temporal. Úsalo en creditCard.token en el POST /transactions. Expira en 24h.
{
  "tokenId": "tok_a1b2c3d4e5f6"
}
El prefijo y el formato exacto del tokenId se definen internamente — trata el valor como una cadena opaca y no intentes interpretarlo.
El tokenId es válido por 24 horas (TTL) y de uso único. Tokeniza la tarjeta justo antes de crear la transacción.

​
Usando el token en la transacción

Con el tokenId en mano, crea la transacción en tu backend indicándolo en creditCard.token: 
curl -X POST https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: TU_CLAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 19900,
    "paymentMethod": "credit_card",
    "creditCard": {
      "token": "tok_a1b2c3d4e5f6"
    }
  }'
Este ejemplo es ilustrativo del uso del token. Los campos exactos para la creación de transacciones están en la página Transacciones. Los valores son siempre enteros en centavos (19900 = R$ 199,00).

​
Cómo funciona por dentro

Al llamar a createCardToken, el SDK — ejecutándose en el navegador del comprador — envía los datos sensibles (PAN, CVV) directamente al cofre seguro (vault) y a los PSPs de Z2Pay, en paralelo, e intercambia todo por un único tokenId opaco. Los datos de la tarjeta nunca pasan por tu backend; tú recibes únicamente el tokenId. Toda la comunicación con el cofre, los PSPs y el servicio de tokenización la maneja el SDK — no necesitas orquestar nada de esto a mano.

​
Errores comunes

  • Failed to generate any tokens: ningún PSP ni cofre logró tokenizar la tarjeta. Causas comunes: datos de la tarjeta inválidos o ningún PSP configurado para la company. Verifica el companyId y los datos informados.
  • Timeout: la tokenización superó el timeout (predeterminado 15s). Suele indicar una red lenta del comprador.
  • Error de red / API: si la llamada a la API de Z2Pay falla, el SDK lanza un Error con el estado y el cuerpo de la respuesta. Consulta Errores para el formato de error de la API.

​
Ver también

Transacciones

Usa el tokenId al crear una transacción de tarjeta.

Tarjetas

Tarjetas guardadas y tokenización persistente.

Tarjetas de prueba (sandbox)

Números de tarjeta para probar en el entorno sandbox.

Entornos

URLs de sandbox y producción.