Primeros pasosTokenización de tarjeta

Tokenización de tarjeta

Para garantizar la seguridad de los datos sensibles de la tarjeta, ninguna información debe transmitirse o almacenarse en texto plano. En este flujo, los datos se tokenizan en el cliente mediante criptografía asimétrica y solo el token cifrado se envía a la API.

La tokenización usa la clave de tokenización, no la clave de API. Está en Finanzas → Integraciones, en la sección Credenciales de API, y puede publicarse en el navegador. La clave de API es secreta y nunca debe aparecer en el front-end.

Descripción

La plataforma admite dos métodos de tokenización:

1. Mediante script de tokenización (Front-end) — recomendada para integraciones directas en el navegador, como checkouts web y aplicaciones client-side.
2. Mediante la clase PaymentTokenizer (API / Back-end) — recomendada para integraciones server-to-server, donde la encriptación ocurre en el backend del integrador antes del envío a la API.

¿Cómo funciona la tokenización?

El proceso de tokenización sigue los siguientes pasos:

1. Utiliza la clave de tokenización de la tienda.
2. Los datos de la tarjeta se cifran localmente con esta clave.
3. El resultado es un token.
4. Este token se envía a la API de pagos en lugar de los datos de la tarjeta.

Forma 1 - Tokenización en el Front-end (Script)

Para realizar transacciones con tarjeta de crédito, es necesario incluir el token de la tarjeta en la solicitud.
La generación del token es sencilla y debe realizarse en el front-end antes de enviar los datos a la API.
A continuación se muestra el primer paso, que consiste en importar el script oficial de tokenización.

Inclusión del Script de Tokenización

Agrega el siguiente script en tu página HTML o antes de utilizar la función de tokenización:

HTML

<script src="https://api.securitypag.com/v1/scripts"></script>

Ejemplo de uso — Generación del Token

NODE

const pk = "CHAVE_DE_TOKENIZACAO"

try {
  const card = {
    number: "5555444433331111",
    holderName: "John Doe",
    expMonth: 8,
    expYear: 2027,
    cvv: "789",
  };

  await SecurityPag.init(pk);
  const token = await SecurityPag.encrypt(card);
  console.log(token);
} catch (err) {
  console.error(err);
}

Forma 2 — Tokenización vía API (Clase PaymentTokenizer)

Este método está indicado para integraciones vía backend (API, workers o server-to-server), donde la tarjeta debe tokenizarse antes de enviarse a la API de pagos.
La tokenización continúa realizándose en tu entorno mediante criptografía asimétrica. Solo el token se envía a la plataforma.

Funcionamiento

1. Utiliza la clave de tokenización de la tienda.
2. Tu aplicación inicializa la clase PaymentTokenizer con esta clave.
3. Los datos de la tarjeta se validan y cifran localmente.
4. El resultado es un token.
5. Este token se envía a la API de pagos en lugar de los datos de la tarjeta.

Dependencia

La clase utiliza libsodium para la criptografía:

NODE

import sodium from "https://cdn.jsdelivr.net/npm/libsodium-wrappers@0.8.0/+esm

Clase PaymentTokenizer

NODE

import sodium from "https://cdn.jsdelivr.net/npm/libsodium-wrappers@0.8.0/+esm";

type CardDTO = {
  number: string;
  holder: string;
  expMonth: string;
  expYear: string;
  cvv: string;
};


class PaymentTokenizer {
  tokenizationKey = "";
  initialized = false;

  async init(pk: string): Promise<void> {
    this.assertValidTokenizationKey(pk);
    await sodium.ready;
    this.tokenizationKey = pk;
    this.initialized = true;
  }

  async encrypt(card: CardDTO): Promise<string> {
    if (!this.initialized || !this.tokenizationKey) {
      throw new Error("TOKENIZER_NOT_INITIALIZED");
    }

    const payload = this.buildPayload(card);

    const encrypted = sodium.crypto_box_seal(sodium.from_string(JSON.stringify(payload)), sodium.from_base64(this.tokenizationKey));

    return sodium.to_base64(encrypted);
  }

  buildPayload(card: CardDTO): CardDTO {
    return {
      number: this.validateCardNumber(card.number),
      holder: this.validateHolder(card.holder),
      expMonth: this.validateMonth(card.expMonth),
      expYear: this.validateYear(card.expYear),
      cvv: this.validateCvv(card.cvv),
    };
  }

  assertValidTokenizationKey(pk: string) {
    if (!pk || typeof pk !== "string" || pk.trim() === "") {
      throw new Error("INVALID_TOKENIZATION_KEY");
    }
  }

  validateHolder(value: string): string {
    if (!value?.trim()) {
      throw new Error("INVALID_CARD_HOLDER");
    }
    return value.trim();
  }

  validateCardNumber(value: string): string {
    const number = String(value ?? "").replace(/\D/g, "");

    if (!/^\d{13,19}$/.test(number)) {
      throw new Error("INVALID_CARD_NUMBER");
    }

    return number;
  }

  validateMonth(value: string): string {
    const monthStr = String(value ?? "").replace(/\D/g, "");

    if (!/^\d{2}$/.test(monthStr)) {
      throw new Error("INVALID_EXP_MONTH");
    }

    const month = Number(monthStr);

    if (month < 1 || month > 12) {
      throw new Error("INVALID_EXP_MONTH");
    }

    return monthStr;
  }

  validateYear(value: string): string {
    const yearStr = String(value ?? "").replace(/\D/g, "");

    if (!/^\d{4}$/.test(yearStr)) {
      throw new Error("INVALID_EXP_YEAR");
    }

    const year = Number(yearStr);
    const currentYear = new Date().getFullYear();
    if (year < currentYear) {
      throw new Error("CARD_EXPIRED");
    }
    return yearStr;
  }

  validateCvv(value: string): string {
    const cvv = String(value ?? "").replace(/\D/g, "");

    if (!/^\d{3,4}$/.test(cvv)) {
      throw new Error("INVALID_CVV");
    }

    return cvv;
  }
}

Clase PaymentTokenizer

NODE

import { PaymentTokenizer } from "./PaymentTokenizer";

const pk = "SUA_CHAVE_DE_TOKENIZACAO";

async function tokenizeCard() {
  const tokenizer = new PaymentTokenizer();
  await tokenizer.init(pk);

  const token = await tokenizer.encrypt({
    number: "4111111111111111",
    holder: "JOHN DOE",
    expMonth: "12",
    expYear: "2030",
    cvv: "123"
  });

  console.log("Token do cartão:", token);
}

tokenizeCard();

¿Algo mal en esta página? Habla con nosotros