Skip to main content

SecureFieldsHostedFormConfig

Hosted form mode: the SDK renders a complete, ready to use card form — card number, expiry date, CVV and cardholder name — into a single container, with a fixed layout.

The card fields are still cross-origin iframes the SDK mounts into the form it draws, so card data remains inaccessible to your page exactly as in hosted fields mode. What you gain is not having to build and style the form yourself; what you give up is control over the arrangement of the fields.

hostedForm and theme mirror the options accepted by @upstreampay/partner-ui, so a merchant already integrating the Purse widget can reuse the same objects.

Example​

const client = await initSecureFields({
  tenantId: 'tenant_xxx',
  config: {
    mode: 'hosted_form',
    container: 'secure-fields-form',
    brands: ['VISA', 'MASTERCARD', 'CARTE_BANCAIRE'],
    hostedForm: {
      panInputLabel: 'Card number',
      panPlaceholder: '1234 5678 9012 3456',
      panRequiredError: 'The card number is required',
      brandSelectionMode: 'implicit',
    },
    theme: {
      global: { color: '#181818', fontSize: '16px' },
      input: { borderRadius: '4px', ':focus': { borderColor: '#0070f3' } },
      label: { fontSize: '14px', color: '#344054' },
      helperText: { fontSize: '12px', ':invalid': { color: '#d32f2f' } },
    },
  },
});
client.render();

Properties​

brands​

brands: Brand[];

Eligible card networks, in order of preference. The first is used when several match a co-badged card and the cardholder has not chosen.

container​

container: string | HTMLElement;

Where the form is rendered: the id of an element, or the element itself. Its existing content is replaced.

Note this is an element id, not a css selector, consistent with the target of the individual fields in hosted fields mode.

fields?​

optional fields?: Partial<Record<"cardNumber" | "cvv" | "expDate" | "holderName", Omit<SecureFieldsFieldConfig, "target">>>;

Per-field overrides for the iframe title and the input's accessible name. Both default to the field's label from hostedForm, which is normally what you want — set these only to override.

There is no target: the form owns the layout and mounts each field itself.

hostedForm?​

optional hostedForm?: HostedFormUIOptions;

Every text the form displays, plus noCVV, hideHolderName and the brand selector mode. Any key you omit falls back to a shipped English default.

mode​

mode: "hosted_form";

styles?​

optional styles?: undefined;

Not available in hosted form mode — use theme instead. Declared so SecureFieldsConfig['styles'] still resolves across the mode union.

theme?​

optional theme?: object;

Colours, typography, borders, spacing and the focus/error/success states of the form.

NameTypeDescription
global?object-
global.:invalid?object-
global.:invalid.color?string-
global.:invalid.fontFamily?string-
global.:invalid.fontSize?string-
global.:invalid.fontWeight?string-
global.:invalid.gap?string-
global.:valid?object-
global.:valid.color?string-
global.:valid.fontFamily?string-
global.:valid.fontSize?string-
global.:valid.fontWeight?string-
global.:valid.gap?string-
global.color?string-
global.fontFamily?string-
global.fontSize?string-
global.fontSrc?stringURL of a merchant font, forwarded to the iframes. fontSrc is not a valid css style declaration key.
global.fontWeight?string-
global.gap?string-
helperText?object-
helperText.:disabled?object-
helperText.:disabled.color?string-
helperText.:disabled.fontFamily?string-
helperText.:disabled.fontSize?string-
helperText.:disabled.fontWeight?string-
helperText.:disabled.margin?string-
helperText.:invalid?object-
helperText.:invalid.color?string-
helperText.:invalid.fontFamily?string-
helperText.:invalid.fontSize?string-
helperText.:invalid.fontWeight?string-
helperText.:invalid.margin?string-
helperText.:valid?object-
helperText.:valid.color?string-
helperText.:valid.fontFamily?string-
helperText.:valid.fontSize?string-
helperText.:valid.fontWeight?string-
helperText.:valid.margin?string-
helperText.color?string-
helperText.fontFamily?string-
helperText.fontSize?string-
helperText.fontWeight?string-
helperText.margin?string-
input?object-
input.:-webkit-autofill?object-
input.:-webkit-autofill.backgroundColor?string-
input.:-webkit-autofill.borderColor?string-
input.:-webkit-autofill.borderRadius?string-
input.:-webkit-autofill.borderStyle?string-
input.:-webkit-autofill.borderWidth?string-
input.:-webkit-autofill.boxShadow?string-
input.:-webkit-autofill.color?string-
input.:-webkit-autofill.fontFamily?string-
input.:-webkit-autofill.fontSize?string-
input.:-webkit-autofill.fontStyle?string-
input.:-webkit-autofill.fontWeight?string-
input.:-webkit-autofill.outlineColor?string-
input.:-webkit-autofill.outlineStyle?string-
input.:-webkit-autofill.outlineWidth?string-
input.:-webkit-autofill.padding?string-
input.::placeholder?object-
input.::placeholder.backgroundColor?string-
input.::placeholder.borderColor?string-
input.::placeholder.borderRadius?string-
input.::placeholder.borderStyle?string-
input.::placeholder.borderWidth?string-
input.::placeholder.boxShadow?string-
input.::placeholder.color?string-
input.::placeholder.fontFamily?string-
input.::placeholder.fontSize?string-
input.::placeholder.fontStyle?string-
input.::placeholder.fontWeight?string-
input.::placeholder.outlineColor?string-
input.::placeholder.outlineStyle?string-
input.::placeholder.outlineWidth?string-
input.::placeholder.padding?string-
input.::placeholder:disabled?object-
input.::placeholder:disabled.backgroundColor?string-
input.::placeholder:disabled.borderColor?string-
input.::placeholder:disabled.borderRadius?string-
input.::placeholder:disabled.borderStyle?string-
input.::placeholder:disabled.borderWidth?string-
input.::placeholder:disabled.boxShadow?string-
input.::placeholder:disabled.color?string-
input.::placeholder:disabled.fontFamily?string-
input.::placeholder:disabled.fontSize?string-
input.::placeholder:disabled.fontStyle?string-
input.::placeholder:disabled.fontWeight?string-
input.::placeholder:disabled.outlineColor?string-
input.::placeholder:disabled.outlineStyle?string-
input.::placeholder:disabled.outlineWidth?string-
input.::placeholder:disabled.padding?string-
input.:focus?object-
input.:focus.backgroundColor?string-
input.:focus.borderColor?string-
input.:focus.borderRadius?string-
input.:focus.borderStyle?string-
input.:focus.borderWidth?string-
input.:focus.boxShadow?string-
input.:focus.color?string-
input.:focus.fontFamily?string-
input.:focus.fontSize?string-
input.:focus.fontStyle?string-
input.:focus.fontWeight?string-
input.:focus.outlineColor?string-
input.:focus.outlineStyle?string-
input.:focus.outlineWidth?string-
input.:focus.padding?string-
input.:hover?object-
input.:hover.backgroundColor?string-
input.:hover.borderColor?string-
input.:hover.borderRadius?string-
input.:hover.borderStyle?string-
input.:hover.borderWidth?string-
input.:hover.boxShadow?string-
input.:hover.color?string-
input.:hover.fontFamily?string-
input.:hover.fontSize?string-
input.:hover.fontStyle?string-
input.:hover.fontWeight?string-
input.:hover.outlineColor?string-
input.:hover.outlineStyle?string-
input.:hover.outlineWidth?string-
input.:hover.padding?string-
input.:invalid?object-
input.:invalid.backgroundColor?string-
input.:invalid.borderColor?string-
input.:invalid.borderRadius?string-
input.:invalid.borderStyle?string-
input.:invalid.borderWidth?string-
input.:invalid.boxShadow?string-
input.:invalid.color?string-
input.:invalid.fontFamily?string-
input.:invalid.fontSize?string-
input.:invalid.fontStyle?string-
input.:invalid.fontWeight?string-
input.:invalid.outlineColor?string-
input.:invalid.outlineStyle?string-
input.:invalid.outlineWidth?string-
input.:invalid.padding?string-
input.:valid?object-
input.:valid.backgroundColor?string-
input.:valid.borderColor?string-
input.:valid.borderRadius?string-
input.:valid.borderStyle?string-
input.:valid.borderWidth?string-
input.:valid.boxShadow?string-
input.:valid.color?string-
input.:valid.fontFamily?string-
input.:valid.fontSize?string-
input.:valid.fontStyle?string-
input.:valid.fontWeight?string-
input.:valid.outlineColor?string-
input.:valid.outlineStyle?string-
input.:valid.outlineWidth?string-
input.:valid.padding?string-
input.backgroundColor?string-
input.borderColor?string-
input.borderRadius?string-
input.borderStyle?string-
input.borderWidth?string-
input.boxShadow?string-
input.color?string-
input.fontFamily?string-
input.fontSize?string-
input.fontStyle?string-
input.fontWeight?string-
input.outlineColor?string-
input.outlineStyle?string-
input.outlineWidth?string-
input.padding?string-
label?object-
label.:invalid?object-
label.:invalid.color?string-
label.:invalid.fontFamily?string-
label.:invalid.fontSize?string-
label.:invalid.fontWeight?string-
label.:invalid.margin?string-
label.:valid?object-
label.:valid.color?string-
label.:valid.fontFamily?string-
label.:valid.fontSize?string-
label.:valid.fontWeight?string-
label.:valid.margin?string-
label.color?string-
label.fontFamily?string-
label.fontSize?string-
label.fontWeight?string-
label.margin?string-
tooltip?object-
tooltip.:focus?object-
tooltip.:focus.backgroundColor?string-
tooltip.:focus.borderRadius?string-
tooltip.:focus.boxShadow?string-
tooltip.:focus.color?string-
tooltip.:focus.fontFamily?string-
tooltip.:focus.fontSize?string-
tooltip.:focus.fontWeight?string-
tooltip.:focus.padding?string-
tooltip.:invalid?object-
tooltip.:invalid.backgroundColor?string-
tooltip.:invalid.borderRadius?string-
tooltip.:invalid.boxShadow?string-
tooltip.:invalid.color?string-
tooltip.:invalid.fontFamily?string-
tooltip.:invalid.fontSize?string-
tooltip.:invalid.fontWeight?string-
tooltip.:invalid.padding?string-
tooltip.backgroundColor?string-
tooltip.borderRadius?string-
tooltip.boxShadow?string-
tooltip.color?string-
tooltip.fontFamily?string-
tooltip.fontSize?string-
tooltip.fontWeight?string-
tooltip.padding?string-