Inicio rápido del SDK
Recopila datos de tarjeta en el navegador y obtén una referencia de token en minutos con el Bridge SDK de Tokeflow — ejemplos mínimos en Vanilla JS y React que puedes copiar y pegar.
El Bridge SDK recopila los detalles de pago en el navegador sin exponer tus servidores a los datos de tarjeta sin procesar. Los campos seguros de Tokeflow se ejecutan dentro de iframes aislados y de origen cruzado; los datos de tarjeta se cifran en el navegador y nunca llegan a tus servidores. El SDK devuelve una referencia de token que envías a tu backend para cobrar.
Esta página te lleva a un flujo de tokenización funcional con dos ejemplos mínimos y de extremo a extremo: uno en Vanilla JavaScript y otro en React. Para conocer la superficie completa del SDK (elementos, wallets, contexto de checkout, manejo de errores), consulta la descripción general del Bridge SDK.
Inicializa el SDK con una clave pública (pk_…). Las claves públicas están restringidas a ámbitos seguros para el cliente y es seguro incluirlas en el código del navegador. Nunca pongas una clave secreta (sk_…) en el navegador — consulta Autenticación.
Cómo funciona
El SDK gestiona la recopilación y el cifrado de la tarjeta en el navegador. Tu backend nunca ve la tarjeta — solo recibe una referencia de token (tok_…) que utiliza para cobrar.
La referencia de token es de corta duración y de un solo uso. Envía siempre token.tokenId a tu servidor; el cobro real ocurre del lado del servidor con tu clave secreta.
Instalación
Añade el SDK desde tu gestor de paquetes o carga la compilación de CDN con una etiqueta script.
npm install @tokeflow_com/bridge-js
# or: yarn add @tokeflow_com/bridge-js
# or: pnpm add @tokeflow_com/bridge-jsLa compilación de CDN expone un objeto global Tokeflow (Tokeflow.TokeflowBridge, Tokeflow.TokeflowError, Tokeflow.TokeflowErrorCode):
<script src="https://unpkg.com/@tokeflow_com/bridge-js/dist/tokeflow.min.js"></script>Vanilla JavaScript
Una página completa: un formulario con un elemento de tarjeta, inicialización del SDK, montaje y tokenización al enviar. Al enviar, el SDK devuelve una referencia de token — envía token.tokenId a tu servidor para cobrar.
<!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 tokeflow = new Tokeflow.TokeflowBridge({
publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx",
});
async function init() {
// Creates a session and loads the secure elements runtime.
await tokeflow.init();
// Combined card element (number, expiry, CVC in one iframe).
const cardElement = tokeflow.createCardElement();
cardElement.mount("#card-element");
document
.getElementById("payment-form")
.addEventListener("submit", async (e) => {
e.preventDefault();
const token = await tokeflow.cards.tokenize({ card: cardElement });
console.log("Token:", token.tokenId); // tok_…
// Send token.tokenId to YOUR server to create the charge.
await fetch("/api/payments", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ tokenId: token.tokenId }),
});
});
}
init();
</script>
</body>
</html>¿Usas un bundler de módulos en lugar de la CDN? Importa la clase directamente: import { TokeflowBridge } from "@tokeflow_com/bridge-js"; y usa new TokeflowBridge({ publicKey }).
React
Envuelve tu árbol en TokeflowProvider, renderiza un CardElement y lee la instancia del bridge con el hook useTokeflow. Pasa la instancia subyacente del elemento (a través del .element de la ref) a tokenize().
import { useRef, useState, FormEvent } from "react";
import {
TokeflowProvider,
useTokeflow,
CardElement,
CardElementRef,
} from "@tokeflow_com/bridge-js/react";
function PaymentForm() {
const { tokeflow, isReady } = useTokeflow();
const cardRef = useRef<CardElementRef>(null);
const [loading, setLoading] = useState(false);
const handleSubmit = async (e: FormEvent) => {
e.preventDefault();
if (!tokeflow || !cardRef.current?.element) return;
setLoading(true);
try {
const token = await tokeflow.cards.tokenize({
card: cardRef.current.element,
});
console.log("Token:", token.tokenId); // tok_…
// Send token.tokenId to YOUR server to create the charge.
await fetch("/api/payments", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ tokenId: token.tokenId }),
});
} finally {
setLoading(false);
}
};
if (!isReady) return <div>Loading payment form…</div>;
return (
<form onSubmit={handleSubmit}>
<CardElement ref={cardRef} id="card-element" />
<button type="submit" disabled={loading}>
{loading ? "Processing…" : "Pay"}
</button>
</form>
);
}
export default function App() {
return (
<TokeflowProvider config={{ publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx" }}>
<PaymentForm />
</TokeflowProvider>
);
}El provider inicializa el bridge por ti. Espera a isReady antes de llamar a tokenize() — hasta que la sesión se cree y los campos seguros estén montados, el bridge no está listo para tokenizar.
La respuesta del token
tokeflow.cards.tokenize(...) se resuelve en un CardToken. El único campo que reenvías es tokenId (una referencia tok_…); el resto son metadatos de visualización no sensibles.
// {
// tokenId: 'tok_a1b2c3d4e5', // the reference you send to your server
// type: 'card',
// brand: 'visa',
// last4: '4242',
// expiryMonth: '12',
// expiryYear: '2029',
// bin: '424242',
// createdAt: '2026-01-01T00:00:00.000Z'
// }| Field | Type | Descripción |
|---|---|---|
tokenId | string | La referencia de token de Tokeflow (tok_…). Envíala a tu servidor para cobrar. |
type | string | Siempre card para tokens de tarjeta. |
brand | string | Marca de la tarjeta, p. ej. visa, mastercard. |
last4 | string | Últimos cuatro dígitos, para mostrar. |
expiryMonth | string | Mes de vencimiento, p. ej. 12. |
expiryYear | string | Año de vencimiento, p. ej. 2029. |
bin | string | Número de identificación bancaria (opcional). |
createdAt | string | Marca de tiempo ISO 8601 (opcional). |
Cobra el token desde tu servidor
La referencia de token no es un cobro — es un identificador. Tu backend crea la transacción con tu clave secreta, haciendo referencia al token mediante card_ciphertext_id. Envía una Idempotency-Key para que un reintento nunca genere un doble cobro.
curl -X POST https://api.tokeflow.com/api/v1/transactions \
-H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_2026_0623_attempt_1" \
-d '{
"customer_id": "cust_a1b2c3d4e5",
"amount": 9900,
"currency": "BRL",
"payment_method": "credit_card",
"charge_type": "payment",
"country": "BR",
"capture": true,
"card_ciphertext_id": "tok_a1b2c3d4e5"
}'El flujo de cobro completo — sesiones de checkout, captura, reembolsos y lectura de la línea de tiempo del intento — se encuentra en Transacciones. Para el camino de extremo a extremo desde las claves hasta el webhook, consulta el Inicio rápido.
Nunca envíes números de tarjeta, CVC ni fechas de vencimiento sin procesar a tu propio backend. Solo la referencia tok_… producida por el SDK debe salir del navegador.
Próximos pasos
- Descripción general del Bridge SDK — elementos, wallets, localización y el modelo de configuración completo.
- Autenticación — claves públicas frente a secretas y las cabeceras de autenticación del SDK.
- Transacciones — cobra el token y luego captura, anula o reembolsa.
- Inicio rápido — el recorrido completo de cero a pago.