Entrada segura de tarjeta

Esta página asume que ya leíste la Descripción general de Secure Elements: ahí se cubre la carga del SDK y el flujo compartido de client-token, ambos aplican aquí.

Velo en vivo

La demo genera su propio token y monta los campos automáticamente. Ingresa cualquier número de tarjeta que pase una verificación de Luhn, completa el nombre del titular y envía. Usa Remint token & remount si el formulario deja de responder. Ábrela en su propia pestaña →

Genera un token de tokenización

Llama a POST /v1/client-token con "purpose": "tokenization":

{
  "purpose": "tokenization"
}

A diferencia de un token de revelado, este no necesita un virtualCardId. Sí requiere un alcance diferente en tu token de acceso — MANAGE_PAYMENT, no CREATE_VIRTUALCARD — y tiene una vida útil más larga (30 minutos por defecto) ya que un usuario tarda más llenando un formulario de tarjeta que haciendo un clic de revelado.

Renderiza los campos

const inputs = renderFieldsForTokenization({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
});

renderFieldsForTokenization no tiene la opción fields: PAN, vencimiento y CVV siempre se montan juntos como un solo iframe combinado, porque la validación del CVV es sensible a la marca (el CVV de Amex tiene 4 dígitos; el de las demás marcas, 3), lo que solo funciona si el campo conoce el número de tarjeta escrito en el campo contiguo dentro del frame. No puedes montarlos de forma independiente como se puede con los campos de createCardViewer.

Opción	Requerido	Detalles
`clientToken` / `loadToken`	Sí	Del mint de arriba
`frameHostOrigin`	No	Mismas reglas de origen en la allowlist que Card Reveal: por omisión apunta a producción
`style`	No	Mismo `{ color, fontSize, fontFamily, fontWeight }` que `createCardViewer`; ver la salvedad abajo
`mountTimeoutMs`	No	10 segundos por defecto
`submitTimeoutMs`	No	15 segundos por defecto — ver Enviar
`excludedCardBrands`	No	p. ej. `["amex"]` — ver Rastrea el estado de los campos

Una Google Font pasada en style.fontFamily se renderiza en los campos de Card Reveal pero aquí se omite en silencio: estos campos se renderizan dentro de un iframe de un proveedor con bóveda, sin forma de cargar CSS externo. Solo la allowlist de fuentes del sistema (system-ui, Arial, Georgia, monospace, etc.) realmente aplica una fuente en esta capacidad.

Móntalo

await inputs.mount(document.getElementById("card-fields"));

Misma forma que en Card Reveal: rechaza con FluzElementsError por INVALID_STYLE, MOUNT_TIMEOUT o MOUNT_FAILED (el frame no cargó, o esta instancia ya está montada). frameHostOrigin se valida de forma sincrónica cuando llamas a renderFieldsForTokenization, igual que en createCardViewer: un origen no reconocido lanza INVALID_FRAME_HOST_ORIGIN antes de llegar a mount().

Rastrea el estado de los campos

inputs.onChange((field, state) => {
  // field: "pan" | "expiry" | "cvv"
  // state: { isEmpty, isValid, isDirty, brand? }
});

Se activa en cada pulsación dentro del frame. brand solo aparece en el estado de pan, detectada a partir de los dígitos ingresados hasta el momento: amex, visa, mastercard, discover, diners o jcb. Usa isValid para controlar tu propio botón de envío y para los mensajes de validación inline: ninguno de estos campos expone el valor subyacente a tu página. excludedCardBrands (p. ej. ["amex"]) no bloquea la escritura: fuerza que isValid de pan sea false cuando se detecta una marca coincidente, por lo que el usuario aún puede ingresar el número pero submit() no tendrá éxito hasta que use una tarjeta distinta.

Enviar

Recopila el nombre del titular y la dirección de facturación como inputs normales en tu propia página: el SDK no los renderiza dentro de un frame alojado por Fluz porque no son datos de tarjeta. Si manejarlos tú afecta tu propio alcance PCI DSS depende de tu entorno más amplio de datos de titulares de tarjeta; confírmalo con tu QSA.

await inputs.submit({
  cardholderName: "Jane Doe",
  billingAddress: {
    line1: "123 Main St",
    line2: "Apt 4", // optional
    city: "Austin",
    state: "TX", // optional
    zipCode: "78701",
    country: "US",
  },
  isBackupPayment: false, // optional
});

cardholderName se divide en nombre y apellido solo por el primer espacio: "Mary Ann Smith" se convierte en nombre "Mary", apellido "Ann Smith"; un nombre de una sola palabra se usa como ambos. Para reutilizar una dirección ya existente en la cuenta en lugar de recopilar una nueva, pasa billingAddress: { userAddressId: "<uuid>" }.

submit() casi nunca rechaza, y nunca por una denegación. Solo lanza sincrónicamente por MOUNT_FAILED (aún no montado) o SUBMIT_FAILED (“ya hay una llamada a submit() en curso”: ignora una segunda llamada mientras hay una en progreso). Cualquier otro resultado — éxito, denegación, fallo de validación, timeout — se resuelve normalmente y llega a través de los callbacks de abajo.

Maneja los resultados

inputs.onSuccess((result) => {
  // result.bankCardId, brand, last4, expirationMonth, expirationYear,
  // cardholderName, billingAddress, createdAt
});

inputs.onDeclined((decline) => {
  // decline.code, decline.message
});

inputs.onError((error) => {
  // error.code, error.message
});

onSuccess se activa cuando la tarjeta se agrega como fuente de fondos. onDeclined se activa para una tarjeta que el procesador rechazó: sigue siendo un resultado normal y esperado, no un error:

Código de denegación	Significado
`CARD_DECLINED`	Denegación genérica
`INSUFFICIENT_FUNDS`	Denegada por fondos insuficientes
`CARD_EXPIRED`	La tarjeta ha expirado
`CARD_INVALID`	No se pudo verificar la tarjeta
`CVV_MISMATCH`	El código de seguridad no coincide
`AVS_MISMATCH`	La dirección de facturación no coincide
`CONTACT_BANK`	Denegada: contactar al emisor de la tarjeta
`DUPLICATE_CARD`	Esta tarjeta ya está en la cuenta
`PREPAID_REJECTED`	No se aceptan tarjetas prepagas
`FRAUD_FILTER`	Bloqueada por un filtro antifraude
`BIN_BLOCKED`	El BIN de la tarjeta está bloqueado
`EXPANDED_BIN_REQUIRED`	La tarjeta requiere datos de BIN ampliado que Fluz aún no tiene
`KYB_GATE`	La cuenta aún no es elegible para agregar una tarjeta
`TRUST_STATUS_FAILED`	La cuenta no es elegible para agregar una tarjeta
`DEVICE_BLOCKED`	Este dispositivo no es elegible para agregar una tarjeta
`MAX_CARDS_REACHED`	La cuenta alcanzó su límite de tarjetas
`DECLINED_OTHER`	Cajón de sastre para un motivo de denegación no mapeado

onError es para todo lo que no es una denegación normal:

Código de error	Dónde aparece	Significado
`INVALID_FRAME_HOST_ORIGIN`	Lanzado por `renderFieldsForTokenization`	`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 no completó su handshake dentro de `mountTimeoutMs`
`MOUNT_FAILED`	Rechazado por `mount()` / lanzado por `submit()`	El frame no cargó, ya estaba montado o se llamó a `submit()` antes de que `mount()` se resolviera
`SUBMIT_FAILED`	Lanzado por `submit()`, o entregado a `onError`	Un segundo `submit()` mientras ya hay uno en curso; o, vía `onError`, los valores de los campos fallaron la validación (`VALIDATION_FAILED`), el entorno no está aprovisionado para collect (`COLLECT_UNAVAILABLE`), el backend de Fluz rechazó la solicitud (`FUNDING_SOURCE_UNAUTHORIZED`) o un error inesperado del procesador (`FUNDING_SOURCE_UNAVAILABLE`)
`SUBMIT_TIMEOUT`	Entregado a `onError`	No llegó un resultado de envío dentro de `submitTimeoutMs` (15 segundos por defecto)
`FIELD_ERROR`	Entregado a `onError`	El campo subyacente de la bóveda de tarjetas reportó un error interno
`RATE_LIMITED`	Entregado a `onError`	Demasiados intentos de envío para este grant

Limpieza

inputs.destroy();

Quita el frame y desuscribe todos los listeners. Llama esto al desmontar, o antes de generar un token nuevo para reintentar.

Ejemplo completo

<div id="card-fields"></div>
<input id="cardholder-name" placeholder="Name on card" />
<button id="submit-button">Add card</button>

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

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

    const inputs = renderFieldsForTokenization({
      clientToken,
      loadToken,
      frameHostOrigin: "https://staging.secure.fluz.app",
      excludedCardBrands: ["amex"],
      style: { fontFamily: "system-ui", fontSize: "16px", color: "#1a1a1a" },
    });

    inputs.onChange((field, state) => console.log(field, state));
    inputs.onDeclined((decline) => alert(decline.message));
    inputs.onError((error) => console.error(error.code, error.message));
    inputs.onSuccess((result) => console.log("card added", result.bankCardId));

    await inputs.mount(document.getElementById("card-fields"));

    const submitButton = document.getElementById("submit-button");
    submitButton.addEventListener("click", async () => {
      submitButton.disabled = true;
      try {
        await inputs.submit({
          cardholderName: document.getElementById("cardholder-name").value,
          billingAddress: { userAddressId: "<existing-address-uuid>" },
        });
      } catch (error) {
        console.error(error.code, error.message);
      } finally {
        submitButton.disabled = false;
      }
    });
  })();
</script>

/mint-tokenization-token es tu propia ruta de backend: la que llama a POST /v1/client-token con "purpose": "tokenization" y tu token de acceso OAuth de Fluz.

Próximos pasos

Descripción general de Secure Elements

Generación de tokens, carga del SDK y CSP.

Card Reveal

La otra capacidad de Secure Elements: mostrar a un usuario los datos de su propia tarjeta.

Demo en vivo

Prueba el formulario para agregar tarjeta ejecutándose contra staging.

Integraciones de ejemplo

Ejemplos ejecutables en HTML plano y React de entrada segura de tarjeta con un servidor que genera tokens.

​Velo en vivo

​Genera un token de tokenización

​Renderiza los campos

​Móntalo

​Rastrea el estado de los campos

​Enviar

​Maneja los resultados

​Limpieza

​Ejemplo completo

​Próximos pasos

Descripción general de Secure Elements

Card Reveal

Demo en vivo

Integraciones de ejemplo

Velo en vivo

Genera un token de tokenización

Renderiza los campos

Móntalo

Rastrea el estado de los campos

Enviar

Maneja los resultados

Limpieza

Ejemplo completo

Próximos pasos