Revelar tarjeta

Esta página asume que ya leíste el Resumen de Secure Elements: cubre la emisión de un token de cliente, la carga del SDK y el estilo de los campos, todo lo cual aplica aquí.

Velo en vivo

La demo emite su propio token y monta el visor automáticamente. Usa Remint token & remount si los botones de revelado dejan de responder, y Reveal, Reveal CVV only o Mask para probar los controles a nivel de campo que se cubren abajo. Ábrela en su propia pestaña →

Emitir un token de revelado

Llama a POST /v1/client-token con "purpose": "reveal" y el virtualCardId que quieres mostrar:

{
  "purpose": "reveal",
  "virtualCardId": "c107e50b-10f3-449c-92c0-609d9a8cfa2a"
}

Pasa el clientToken y el loadToken que devuelve directamente a createCardViewer abajo.

Crear el visor

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

fields controla qué partes de la tarjeta se renderizan, en orden — si lo omites obtienes ["pan", "expiry", "cvv"]. Cada entrada es un nombre de campo simple o un objeto { field, individualReveal }; "pan" es una abreviatura de { field: "pan", individualReveal: true }. pan, expiry y cvv son los únicos nombres de campo válidos — cualquier otro arroja un FluzElementsError (error.code === "INVALID_FIELD") de forma sincrónica, desde el propio createCardViewer, antes de que llames a mount().

Campo	Marcador enmascarado, antes de cualquier revelado	Notas
`pan`	`•••• •••• •••• {last4}`	Los últimos 4 dígitos vienen del metadato de la tarjeta en tu token de cliente
`expiry`	El `MM/YYYY` real — sin máscara	No se trata como sensible
`cvv`	`•••`	Soporta `individualReveal: false` (abajo)

individualReveal es true de forma predeterminada en cada campo. Establecerlo en false evita que ese campo se revele por sí solo — ve Revelar un solo campo. Es independiente de reveal(), que siempre revela todos los campos sin importar esta configuración.

Montarlo

await viewer.mount(document.getElementById("card-viewer"));

mount() agrega un iframe con sandbox por cada campo configurado dentro del elemento contenedor que le pasas — tres frames separados para los fields predeterminados, no un frame combinado — y devuelve una promesa que se resuelve cuando cada frame completa su handshake. Rechaza con un FluzElementsError si:

el style que pasaste a createCardViewer falla la validación (error.code === "INVALID_STYLE") — ve Estilo de campos
un frame no completa su handshake dentro de mountTimeoutMs (error.code === "MOUNT_TIMEOUT"; por defecto 10 segundos, configurable vía createCardViewer({ ..., mountTimeoutMs }))
un frame falla al cargar por completo, o este visor ya está montado (error.code === "MOUNT_FAILED") — cada instancia de CardViewer solo puede montarse una vez; crea una nueva con createCardViewer si necesitas montar de nuevo

Revelar y enmascarar campos

await viewer.reveal(); // fetch and show every configured field at once
await viewer.reveal("cvv"); // fetch and show one field, if that field allows it
viewer.setMask("cvv", true); // re-mask a field that's already been revealed
viewer.setMask("cvv", false); // un-mask it again -- see below

reveal(field?) — asíncrona. Obtiene el valor real desde Fluz y lo muestra. Llamada sin argumento, obtiene y muestra todos los campos configurados sin importar individualReveal. Llamada con un nombre de campo, obtiene y muestra solo ese campo — a menos que ese campo haya sido configurado con individualReveal: false, en cuyo caso rechaza con error.code === "INDIVIDUAL_REVEAL_DISABLED". Un visor no montado, o un nombre de campo que no esté en fields, rechaza con MOUNT_FAILED.
setMask(field, masked, options?) — sincrónica, no asíncrona. Nunca obtiene nada — solo alterna lo que se muestra actualmente:
- setMask(field, true) vuelve a enmascarar el campo a su marcador, haya sido revelado o no.
- setMask(field, false) lo des-enmascara — pero solo muestra el valor real si reveal() ya obtuvo uno para ese campo. Llámalo antes de cualquier reveal() y el campo se quedará en su marcador, ya que aún no hay un valor obtenido para mostrar.
- setMask(field, true, { hidden: true }) deja el campo completamente en blanco (vacío, ni siquiera un marcador) en lugar de mostrar puntos/last4/expiry. hidden solo tiene efecto mientras masked es true.
- No hay una llamada masiva para “enmascarar todo” — llama a setMask una vez por campo en fields si necesitas reiniciar todo el visor.
destroy() — desmonta cada frame y desacopla el visor. Llama a esto al desmontar para no filtrar frames montados cuando tu componente desaparece.

Revelar un solo campo

Para revelar solo un campo por sí mismo (p. ej., un botón “Mostrar CVV” junto a ese campo), llama a reveal(field) — todos los campos permiten esto de forma predeterminada, así que no se necesita configuración para el caso común. Si un campo no debe revelarse nunca por sí solo y solo debe aparecer como parte de la llamada de reveal() de tarjeta completa, exclúyelo con { field, individualReveal: false } en fields:

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
});

await viewer.reveal("cvv"); // rejects — error.code === "INDIVIDUAL_REVEAL_DISABLED"
await viewer.reveal(); // succeeds — reveals pan, expiry, and cvv together

reveal(field) contra un campo excluido rechaza con FluzElementsError (code: "INDIVIDUAL_REVEAL_DISABLED") sin contactar a frame-host. En cualquier caso, reveal() sin argumento siempre revela todos los campos montados — individualReveal no tiene efecto sobre ella.

Esta es una elección de integración del lado del cliente, no una capacidad aplicada por el servidor: controla lo que tu propia UI puede activar, no qué datos puede devolver el grant. No confíes en individualReveal: false como un límite de seguridad.

Manejar eventos

const unsubscribeMount = viewer.onMount(() => {
  // all configured fields have finished rendering
});

const unsubscribeError = viewer.onError((error) => {
  // error.code, error.message
});

onMount se dispara una vez, después de que cada campo configurado se haya renderizado dentro del frame. onError se dispara por problemas que ocurren dentro de un frame ya montado — un reveal() fallido o un límite de tasa — en lugar de problemas con mount() o createCardViewer() en sí, que rechazan o lanzan directamente en su lugar (ver abajo). Tanto onMount como onError devuelven una función para desuscribirse. Cada FluzElementsError que esta capacidad puede producir, y dónde aparece:

Código	Dónde aparece	Significado
`INVALID_FIELD`	Lanzado por `createCardViewer`	Una entrada de `fields` no es `pan`, `expiry` o `cvv`
`INVALID_FRAME_HOST_ORIGIN`	Lanzado por `createCardViewer`	`frameHostOrigin` no es un host de frames de Fluz reconocido
`INVALID_STYLE`	Rechazado por `mount()`	Un valor de `style` falló la validación
`MOUNT_TIMEOUT`	Rechazado por `mount()`	El frame de un campo no completó su handshake dentro de `mountTimeoutMs`
`MOUNT_FAILED`	Rechazado por `mount()`, o lanzado por `reveal()` / `setMask()`	Un frame falló al cargar; el visor ya estaba montado; o `reveal()` / `setMask()` se llamó con un campo desconocido o no montado
`INDIVIDUAL_REVEAL_DISABLED`	Rechazado por `reveal(field)`	Ese campo fue configurado con `individualReveal: false`
`FIELD_ERROR`	Entregado a `onError`	Un `reveal()` falló dentro del frame después del montaje (error de red, o revelado aún no disponible)
`RATE_LIMITED`	Entregado a `onError`	Demasiados intentos de revelado para este grant — `error.message` incluye el tiempo de reintento

Ejemplo completo

<div id="card-viewer"></div>

<script src="https://secure-cdn.fluz.app/secure-elements/v0.3.0/index.global.js"></script>
<script>
  (async () => {
    const { createCardViewer } = FluzSecureElements;

    const res = await fetch("/mint-reveal-token", { method: "POST" });
    const { clientToken, loadToken } = await res.json();

    const viewer = createCardViewer({
      clientToken,
      loadToken,
      frameHostOrigin: "https://staging.secure.fluz.app",
      fields: ["pan", "expiry", { field: "cvv", individualReveal: false }],
      style: {
        fontFamily: "IBM Plex Mono",
        fontSize: "16px",
        color: "#1a1a1a",
      },
    });

    viewer.onError((error) => console.error(error.code, error.message));
    viewer.onMount(() => console.log("card viewer ready"));

    await viewer.mount(document.getElementById("card-viewer"));
  })();
</script>

/mint-reveal-token es tu propia ruta de backend — la que llama a POST /v1/client-token con tu token de acceso OAuth de Fluz, como se describe en Emitir un token de cliente.

Próximos pasos

Resumen de Secure Elements

Emisión de tokens, carga del SDK, estilos y CSP.

Entrada de tarjeta segura

La otra capacidad de Secure Elements: capturar una tarjeta física en lugar de revelar una.

Demo en vivo

Revelar, revelar solo CVV y enmascarar, ejecutándose contra staging.

Integraciones de ejemplo

Ejemplos ejecutables en HTML simple y React para revelado, con un servidor que emite tokens.

​Velo en vivo

​Emitir un token de revelado

​Crear el visor

​Montarlo

​Revelar y enmascarar campos

​Revelar un solo campo

​Manejar eventos

​Ejemplo completo

​Próximos pasos

Resumen de Secure Elements

Entrada de tarjeta segura

Demo en vivo

Integraciones de ejemplo

Velo en vivo

Emitir un token de revelado

Crear el visor

Montarlo

Revelar y enmascarar campos

Revelar un solo campo

Manejar eventos

Ejemplo completo

Próximos pasos