Appearance and Localization

Before You Start

Read the following guides before proceeding:

Overview

The frames accept whitelisted, typed appearance tokens. They do not accept CSS. Arbitrary CSS inside a card
frame is a data-exfiltration channel — an attribute-selector rule with a url() value leaks a PAN one
character at a time — so every value is re-validated inside the frame against a strict grammar and applied
through CSSOM custom properties, never through generated <style> text.

An invalid value is dropped, the frame logs a console warning, and the default renders. A bad theme
degrades the look and never the isolation.

const appearance = {
  theme: 'dark',
  variables: { colorText: '#FFFFFF', borderRadius: '12px' },
  brandBadge: { style: 'logo', tone: 'color' },
};

createCardTopUpFields(sdk, { auth, appearance });

theme accepts light and dark; any other value renders the light scheme.

Appearance is read when an element mounts. Changing the object afterwards has no effect. To re-theme,
destroy the element and create a new one.

Variables

Reveal frames accept four more tokens:

Unknown tokens are dropped without a warning to your page.

Value Grammars

Each type is validated against the pattern below. var(), url(), calc(), quotes, semicolons and braces
fail every one of them by construction.

Brand Fonts

A brand font loads from a font file URL. A stylesheet URL is rejected — host-supplied CSS is the channel
the token model exists to close.

variables: {
  fontFamily: 'YourBrand, Inter, sans-serif',
  fontFaces: [
    { url: 'https://cdn.example.com/fonts/brand-400.woff2', weight: '400' },
    { url: 'https://cdn.example.com/fonts/brand-600.woff2', weight: '600' },
  ],
}

The frame builds the @font-face rules itself and names every face after the first family in fontFamily.
A custom font therefore requires a valid fontFamily; without one, fontUrl and fontFaces are dropped
with a console warning.

Two host-side requirements:

• The CDN origin must be registered against your client id. It enters the frames' font-src policy.
  Include it in onboarding or request it later.
• The font host must allow cross-origin loading. Browsers fetch fonts in CORS mode, so the file must
  respond with an Access-Control-Allow-Origin header covering the frame origin. * is acceptable for
  public font files.

Without the CORS header the browser blocks the font and reports net::ERR_FAILED on a 200 response.
The frame falls back to the next family in fontFamily and renders normally, so the failure is visible
only in the console.

Brand Badge

The card-number field shows the detected card brand. The artwork is bundled inside the frame; you select
among fixed presentations and cannot inject markup.

The default position is vertically centered, 16 pixels from the field's right edge. borderRadius and
size accept % in addition to the length units; offsetX and offsetY accept a leading - and no %.

appearance: {
  brandBadge: {
    style: 'logo',
    tone: 'color',
    background: '#FFFFFF',
    borderRadius: '50%',
    size: '24px',
  },
}

Localized Labels

Field labels and validation messages come from your application, already translated. The frames ship
English defaults and render whatever you pass.

createCardTopUpFields(sdk, {
  auth,
  strings: {
    cardNumberLabel: 'Numéro de carte',
    expiryLabel: 'MM/AA',
    cvvLabel: 'CVV',
    nameLabel: 'Titulaire',
    errCardLuhn: 'Numéro de carte invalide',
  },
});

Keys are per element type:

An omitted key renders its English default. Unknown keys are ignored.