Visión general del Bridge SDK

El Bridge SDK (@tokeflow_com/bridge-js) es la biblioteca del lado del cliente de Tokeflow para recopilar datos de pago sensibles en el navegador y convertirlos en una referencia de token segura. Tu aplicación nunca ve un número de tarjeta en bruto — recibes una referencia tok_… de corta duración y la envías a tu backend para realizar el cargo.

Tokeflow es la capa de orquestación detrás de tu plataforma. El Bridge SDK es la puerta de entrada: captura los detalles de pago dentro de iframes aislados de origen cruzado, los cifra en el navegador y entrega un token a tu código. Tu servidor crea entonces una transacción a través de la API de Tokeflow, y tus proveedores conectados se encargan del procesamiento y la liquidación.

Por qué el Bridge SDK

Recopilar datos de tarjeta directamente en tus propias páginas incluye a tus servidores dentro del alcance de PCI DSS y te hace responsable de proteger los datos del titular de la tarjeta. El Bridge SDK elimina esa carga.

• Compatible con PCI por diseño — Los campos de tarjeta se renderizan dentro de iframes aislados de origen cruzado. Los datos de tarjeta se cifran en el navegador y nunca llegan a tus servidores ni a los scripts de tu página.
• Un solo flujo de tokenización, muchos métodos de pago — Cards, PIX, Apple Pay y Google Pay producen todos el mismo tipo de referencia de token que reenvías a tu backend.
• Contexto de checkout — Cuando tu backend abre una sesión de checkout, el SDK puede leer los artículos con precio, la moneda seleccionada, los métodos de pago habilitados y los instrumentos guardados del cliente.
• Elementos listos para usar — Elementos de entrada prediseñados y personalizables para el número de tarjeta, la fecha de vencimiento, el CVC, el nombre del titular, el CPF y la dirección de facturación.
• Compatibilidad con frameworks — Funciona con JavaScript puro e incluye bindings de React de primera clase.
• Autenticación con clave pública — El SDK se autentica con una clave publicable que es segura de incluir en el código del navegador. Tus claves secretas permanecen del lado del servidor.

Cómo encaja todo

El Bridge SDK se ejecuta en el navegador y solo maneja referencias de token. Tu backend mantiene la clave secreta y realiza el cargo real.

Instalación

Instala desde el gestor de paquetes de tu preferencia:

npm install @tokeflow_com/bridge-js
# or
yarn add @tokeflow_com/bridge-js
# or
pnpm add @tokeflow_com/bridge-js
# or
bun add @tokeflow_com/bridge-js

CDN (etiqueta script)

Para páginas sin un paso de compilación, carga la build UMD desde un CDN. Expone un objeto global Tokeflow.

<script src="https://unpkg.com/@tokeflow_com/bridge-js/dist/tokeflow.min.js"></script>

El objeto global expone los puntos de entrada principales:

Tokeflow.TokeflowBridge;   // the SDK class
Tokeflow.TokeflowError;    // error class
Tokeflow.TokeflowErrorCode; // error-code enum

El requisito de la clave pública

El Bridge SDK se autentica con una clave pública — nunca con una clave secreta.

Las claves públicas tienen el aspecto pk_live_org_… o pk_live_mer_…. Están restringidas a ámbitos seguros para el cliente y son seguras de incrustar en el código del navegador. El SDK usa la clave para crear una sesión de corta duración y para descubrir qué métodos de pago ha habilitado tu Merchant. Emites y gestionas las claves en el Dashboard de Tokeflow durante el onboarding.

Para conocer la anatomía completa de las claves — secreta frente a pública, entorno, y ámbito de Organization frente a Merchant — consulta Entornos y claves y Autenticación.

Ciclo de vida

Una integración típica sigue cinco pasos: construir el bridge, inicializarlo, crear elementos, tokenizar y enviar el token a tu backend.

1. Construir el bridge

import { TokeflowBridge } from '@tokeflow_com/bridge-js';

const bridge = new TokeflowBridge({
  publicKey: 'pk_live_mer_your_public_key',
});

2. Inicializar

init() crea una sesión y carga el runtime de elementos seguros. Debe resolverse antes de que crees o montes cualquier elemento.

await bridge.init();

3. Crear y montar elementos

const cardElement = bridge.createCardElement();
cardElement.mount('#card-element');

4. Tokenizar

Cuando el cliente envía el formulario, tokeniza los datos recopilados. Los datos de tarjeta se cifran dentro del iframe y se intercambian por una referencia de token.

const token = await bridge.cards.tokenize({ card: cardElement });
console.log(token.tokenId); // 'tok_…'

5. Enviar el token a tu backend

Reenvía solo la referencia de token. Tu servidor usa su clave secreta para crear la transacción.

await fetch('/api/payments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tokenId: token.tokenId }),
});

Ejemplo completo en JavaScript puro

<!DOCTYPE html>
<html>
  <head>
    <title>Payment Form</title>
  </head>
  <body>
    <form id="payment-form">
      <div id="card-element"></div>
      <button type="submit">Pay</button>
    </form>

    <script src="https://unpkg.com/@tokeflow_com/bridge-js/dist/tokeflow.min.js"></script>
    <script>
      const bridge = new Tokeflow.TokeflowBridge({
        publicKey: 'pk_live_mer_your_public_key',
      });

      async function init() {
        await bridge.init();

        const cardElement = bridge.createCardElement();
        cardElement.mount('#card-element');

        document
          .getElementById('payment-form')
          .addEventListener('submit', async (e) => {
            e.preventDefault();

            const token = await bridge.cards.tokenize({ card: cardElement });

            // Send token.tokenId to your server
            await fetch('/api/payments', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({ tokenId: token.tokenId }),
            });
          });
      }

      init();
    </script>
  </body>
</html>

Métodos de pago

Una sola instancia de bridge cubre todos los métodos que tu Merchant ha habilitado. Descúbrelos en tiempo de ejecución con bridge.getAvailablePaymentMethods(), que devuelve un subconjunto de 'cards', 'pix', 'applePay' y 'googlePay'.

Consulta Métodos de pago para conocer la API completa de cada módulo.

Seguridad

La seguridad es la razón principal para usar el Bridge SDK en lugar de construir tu propio formulario de tarjeta.

• Los datos de tarjeta están aislados de tu página. Los campos sensibles se ejecutan dentro de iframes aislados de origen cruzado. Los scripts de tu página no pueden leer lo que el cliente escribe.
• Los datos de tarjeta se cifran en el navegador. Se cifran antes de salir de la página y nunca llegan a tus servidores — solo manejas una referencia de token.
• Tokenización compatible con PCI. Como los datos de tarjeta en bruto nunca llegan a tu infraestructura, el SDK mantiene los datos del titular de la tarjeta fuera de tu alcance de PCI DSS.
• Las claves públicas son seguras en el navegador. Las claves pk_… están restringidas a ámbitos seguros para el cliente y están diseñadas para incluirse en el código del cliente.
• Nunca uses claves secretas del lado del cliente. Las claves sk_… pertenecen únicamente a tu servidor. La tokenización y la creación de sesiones a través del SDK requieren solo una clave pública.

Próximos pasos

• Guía rápida — Pago de extremo a extremo en siete pasos.
• React — Provider, hooks y componentes de elementos.
• Elementos — Cada elemento de entrada, sus opciones, eventos y estado.
• Tokenización — Formas de entrada de tokenización, opciones y la respuesta del token.
• Métodos de pago — Cards, PIX, Apple Pay y Google Pay.