Revelado de 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í.

Verlo 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 descritos 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 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 y en qué orden; si lo omites obtendrás ["pan", "expiry", "cvv"]. Cada entrada es un nombre de campo simple o un objeto { field, individualReveal }; "pan" es una forma abreviada de { field: "pan", individualReveal: true }. pan, expiry y cvv son los únicos nombres de campo válidos: cualquier otro lanza un FluzElementsError (error.code === "INVALID_FIELD") de forma síncrona, desde createCardViewer, antes de que llames a mount().

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

individualReveal es true por defecto en cada campo. Configurarlo en false impide que ese campo se revele por sí solo; consulta Revelar un solo campo. Es independiente de reveal(), que siempre revela todos los campos sin importar este ajuste.

Montarlo

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

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

el style que pasaste a createCardViewer falla la validación (error.code === "INVALID_STYLE") — ver Estilo de campos
un iframe no completa su handshake dentro de mountTimeoutMs (error.code === "MOUNT_TIMEOUT"; por defecto 10 segundos, configurable vía createCardViewer({ ..., mountTimeoutMs }))
un iframe no carga en absoluto, 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. Sin argumento, obtiene y muestra todos los campos configurados sin importar individualReveal. Con un nombre de campo, obtiene y muestra solo ese — 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?) — síncrona, no asíncrona. Nunca obtiene nada; solo alterna lo que se muestra actualmente:
- setMask(field, true) vuelve a enmascarar el campo a su marcador, se haya revelado o no.
- setMask(field, false) lo desenmascara, 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 que mostrar.
- setMask(field, true, { hidden: true }) deja el campo en blanco por completo (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 cada campo en fields si necesitas reiniciar todo el visor.
destroy() — desmonta cada iframe y separa el visor. Llama a esto al desmontar para no dejar iframes montados cuando tu componente desaparezca.

Revelar un solo campo

Para revelar solo un campo por sí mismo (por ejemplo, un botón “Mostrar CVV” junto a ese campo), llama a reveal(field); cada campo permite 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 reveal() de toda la tarjeta, 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 haya renderizado dentro del iframe. onError se dispara por problemas que ocurren dentro de un iframe ya montado — un reveal() fallido o un límite de rate — en lugar de problemas con mount() o createCardViewer() en sí, que en su lugar rechazan o lanzan directamente (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 iframes de Fluz reconocido
`INVALID_STYLE`	Rechazado por `mount()`	Un valor de `style` falló la validación
`MOUNT_TIMEOUT`	Rechazado por `mount()`	El iframe de un campo no completó su handshake dentro de `mountTimeoutMs`
`MOUNT_FAILED`	Rechazado por `mount()`, o lanzado por `reveal()` / `setMask()`	Un iframe no cargó; el visor ya estaba montado; o `reveal()` / `setMask()` se llamó con un campo no montado o desconocido
`INDIVIDUAL_REVEAL_DISABLED`	Rechazado por `reveal(field)`	Ese campo fue configurado con `individualReveal: false`
`FIELD_ERROR`	Entregado a `onError`	Un `reveal()` falló dentro del iframe 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-staging.fluz.app/secure-elements/v0.1.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.

Demo en vivo

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

Integraciones de ejemplo

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

​Verlo 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

Demo en vivo

Integraciones de ejemplo

Verlo 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