Secure Card Input

This page assumes you’ve read Secure Elements Overview — it covers loading the SDK and the shared client-token flow, both of which apply here.

See it live

The demo mints its own token and mounts the fields automatically. Enter any card number that passes a Luhn check, fill in the cardholder name, and submit. Use Remint token & remount if the form stops responding. Open it in its own tab →

Mint a tokenization token

Call POST /v1/client-token with "purpose": "tokenization":

{
  "purpose": "tokenization"
}

Unlike a reveal token, this one doesn’t need a virtualCardId. It does need a different scope on your access token — MANAGE_PAYMENT, not CREATE_VIRTUALCARD — and it’s longer-lived (30 minutes by default) since a user filling out a card form takes longer than a reveal click.

Render the fields

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

renderFieldsForTokenization has no fields option — PAN, expiry, and CVV always mount together as one combined frame, because CVV validation is brand-aware (an Amex CVV is 4 digits; every other brand is 3), which only works if the field knows the card number typed into the frame next to it. You can’t mount them independently the way createCardViewer’s fields can be.

Option	Required	Details
`clientToken` / `loadToken`	Yes	From the mint call above
`frameHostOrigin`	No	Same allowlisted-origin rules as Card Reveal — defaults to production if omitted
`style`	No	Same `{ color, fontSize, fontFamily, fontWeight }` as `createCardViewer` — see the caveat below
`mountTimeoutMs`	No	Defaults to 10 seconds
`submitTimeoutMs`	No	Defaults to 15 seconds — see Submit
`excludedCardBrands`	No	e.g. `["amex"]` — see Track field state

A Google Font passed in style.fontFamily renders in Card Reveal’s fields but is silently skipped here — these fields render inside a vendor-hosted vault iframe with no hook for loading external CSS into it. Only the system-font allowlist (system-ui, Arial, Georgia, monospace, and so on) actually applies a font in this capability.

Mount it

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

Same shape as Card Reveal: rejects with FluzElementsError for INVALID_STYLE, MOUNT_TIMEOUT, or MOUNT_FAILED (frame failed to load, or this instance is already mounted). frameHostOrigin is validated synchronously when you call renderFieldsForTokenization, the same as createCardViewer — an unrecognized origin throws INVALID_FRAME_HOST_ORIGIN before you ever reach mount().

Track field state

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

Fires on every keystroke inside the frame. brand is only present on pan’s state, detected from the digits typed so far: amex, visa, mastercard, discover, diners, or jcb. Use isValid to gate your own submit button and drive inline validation messaging — none of these fields expose the underlying value to your page. excludedCardBrands (e.g. ["amex"]) doesn’t block typing — it forces pan’s isValid to false once a matching brand is detected, so a user can still enter the number but submit() won’t succeed until they use a different card.

Submit

Collect the cardholder name and billing address as ordinary inputs on your own page — the SDK doesn’t render them inside a Fluz-hosted frame, since they aren’t card data. Whether handling them yourself affects your own PCI DSS scope depends on your broader cardholder data environment; confirm with your 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 is split into first/last on the first space only — "Mary Ann Smith" becomes first name "Mary", last name "Ann Smith"; a single-word name is used as both. To reuse an address already on the account instead of collecting a new one, pass billingAddress: { userAddressId: "<uuid>" }.

submit() almost never rejects, and never for a decline. It only throws synchronously for MOUNT_FAILED (not mounted yet) or SUBMIT_FAILED (“a submit() call is already in progress” — it ignores a second call while one is in flight). Every other outcome — success, decline, validation failure, timeout — resolves normally and arrives through the callbacks below instead.

Handle results

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 fires once the card is added as a funding source. onDeclined fires for a card the processor rejected — still a normal, expected outcome, not an error:

Decline code	Meaning
`CARD_DECLINED`	Generic decline
`INSUFFICIENT_FUNDS`	Declined for insufficient funds
`CARD_EXPIRED`	Card has expired
`CARD_INVALID`	Card could not be verified
`CVV_MISMATCH`	Security code didn’t match
`AVS_MISMATCH`	Billing address didn’t match
`CONTACT_BANK`	Declined — contact card issuer
`DUPLICATE_CARD`	This card is already on the account
`PREPAID_REJECTED`	Prepaid cards aren’t accepted
`FRAUD_FILTER`	Blocked by a fraud filter
`BIN_BLOCKED`	Card’s BIN is blocked
`EXPANDED_BIN_REQUIRED`	Card requires expanded BIN data Fluz doesn’t have yet
`KYB_GATE`	Account isn’t yet eligible to add a card
`TRUST_STATUS_FAILED`	Account isn’t eligible to add a card
`DEVICE_BLOCKED`	This device isn’t eligible to add a card
`MAX_CARDS_REACHED`	Account has reached its card limit
`DECLINED_OTHER`	Catch-all for an unmapped decline reason

onError is for everything that isn’t a normal decline:

Error code	Where it surfaces	Meaning
`INVALID_FRAME_HOST_ORIGIN`	Thrown by `renderFieldsForTokenization`	`frameHostOrigin` isn’t a recognized Fluz frame host
`INVALID_STYLE`	Rejected by `mount()`	A `style` value failed validation
`MOUNT_TIMEOUT`	Rejected by `mount()`	The frame didn’t complete its handshake within `mountTimeoutMs`
`MOUNT_FAILED`	Rejected by `mount()` / thrown by `submit()`	The frame failed to load, was already mounted, or `submit()` was called before `mount()` resolved
`SUBMIT_FAILED`	Thrown by `submit()`, or delivered to `onError`	A second `submit()` while one is already in flight; or, via `onError`, the field values failed validation (`VALIDATION_FAILED`), the environment isn’t provisioned for collect (`COLLECT_UNAVAILABLE`), Fluz’s own backend rejected the request (`FUNDING_SOURCE_UNAUTHORIZED`), or an unexpected processor error (`FUNDING_SOURCE_UNAVAILABLE`)
`SUBMIT_TIMEOUT`	Delivered to `onError`	No submit result arrived within `submitTimeoutMs` (default 15 seconds)
`FIELD_ERROR`	Delivered to `onError`	The underlying card-vault field reported an internal error
`RATE_LIMITED`	Delivered to `onError`	Too many submit attempts for this grant

Cleanup

inputs.destroy();

Removes the frame and detaches all listeners. Call this on unmount, or before minting a fresh token to retry.

Full example

<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.1.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 is your own backend route — the one that calls POST /v1/client-token with "purpose": "tokenization" and your Fluz OAuth access token.

Next steps

Secure Elements Overview

Token minting, SDK loading, and CSP.

Card Reveal

The other Secure Elements capability — showing a user their own card details.

Live demo

Try the card-add form running against staging.

Example integrations

Runnable plain-HTML and React secure-card-input examples with a token-minting server.

​See it live

​Mint a tokenization token

​Render the fields

​Mount it

​Track field state

​Submit

​Handle results

​Cleanup

​Full example

​Next steps

Secure Elements Overview

Card Reveal

Live demo

Example integrations

See it live

Mint a tokenization token

Render the fields

Mount it

Track field state

Submit

Handle results

Cleanup

Full example

Next steps