Skip to main content

Customization

Customize the appearance and behavior of secure payment fields. See the SecureFieldsConfig reference for complete technical details.

Card Networks​

Specify which card networks your payment form accepts:

const config: SecureFieldsConfig = {
  brands: ['VISA', 'MASTERCARD', 'AMERICAN_EXPRESS', 'CARTE_BANCAIRE'],
  // ...other config
}

Field Configuration​

Configure where each secure field appears in your form. The holderName field is optional and depends on your PSP requirements.

fields: {
  cardNumber: {
    target: 'card-number-container',
    placeholder: '1234 5678 9012 3456',
    ariaLabel: 'Credit Card Number',
    iframeTitle: 'Secure Card Number Input'
  },
  cvv: {
    target: 'cvv-container',
    placeholder: 'CVV',
    ariaLabel: 'Card Security Code',
    iframeTitle: 'Secure CVV Input'
  },
  expDate: {
    target: 'exp-date-container',
    placeholder: 'MM/YY',
    ariaLabel: 'Expiry Date',
    iframeTitle: 'Secure Expiry Date Input'
  },
  holderName: {
    target: 'holder-name-container',
    placeholder: 'John Doe',
    ariaLabel: 'Cardholder Name',
    iframeTitle: 'Secure Cardholder Name Input'
  }
}

Field Properties:

PropertyTypeRequiredDescription
targetstringYesID of the DOM element where the field renders
placeholderstringNoPlaceholder text
ariaLabelstringNoARIA label for accessibility
iframeTitlestringNoiframe title attribute

Brand Selector​

Enable the built-in brand selector for co-branded cards:

const config: SecureFieldsConfig = {
  brands: ['VISA', 'MASTERCARD', 'CARTE_BANCAIRE'],
  brandSelector: true,
  // ...other config
}

When enabled, a dropdown appears when multiple brands are detected. When disabled, you must handle brand selection yourself and pass selectedNetwork to the submit() method. See Collect card details for manual brand selection.

Styling​

Customize field appearance using the styles property:

styles: {
  input: {
    fontSize: '16px',
    color: '#333',
    ':focus': {
      color: '#0070f3'
    },
    '::placeholder': {
      color: '#999'
    }
  }
}

Custom Fonts​

info

For security reasons, custom fonts must be hosted on a secure HTTPS server. Contact your Purse integration team to enable custom font files.

styles: {
  fontSrc: 'https://fonts.example.com/myfont.woff2',
  input: {
    fontFamily: 'MyCustomFont, sans-serif'
  }
}

Pseudo-Classes​

Supported pseudo-classes for state-based styling:

  • :empty — Field is empty
  • :focus — Field has focus
  • :valid — Field contains valid input
  • :invalid — Field contains invalid input
  • :autocomplete — Field was autocompleted
  • ::placeholder — Placeholder text

Style Properties​

  • fontFamily
  • fontSize
  • lineHeight
  • fontWeight
  • color
  • backgroundColor
  • placeholderColor

Complete Example​

const config: SecureFieldsConfig = {
  brands: ['VISA', 'MASTERCARD', 'AMERICAN_EXPRESS', 'CARTE_BANCAIRE'],
  brandSelector: true,
  fields: {
    cardNumber: {
      target: 'card-number-container',
      placeholder: '1234 5678 9012 3456',
      ariaLabel: 'Credit Card Number',
      iframeTitle: 'Secure Card Number Input'
    },
    cvv: {
      target: 'cvv-container',
      placeholder: 'CVV',
      ariaLabel: 'Card Security Code',
      iframeTitle: 'Secure CVV Input'
    },
    expDate: {
      target: 'exp-date-container',
      placeholder: 'MM/YY',
      ariaLabel: 'Expiry Date',
      iframeTitle: 'Secure Expiry Date Input'
    },
    holderName: {
      target: 'holder-name-container',
      placeholder: 'John Doe',
      ariaLabel: 'Cardholder Name',
      iframeTitle: 'Secure Cardholder Name Input'
    }
  },
  styles: {
    fontSrc: 'https://fonts.example.com/custom-font.woff2',
    input: {
      fontFamily: 'CustomFont, Arial, sans-serif',
      fontSize: '16px',
      color: '#1a1a1a',
      ':focus': {
        color: '#0070f3'
      },
      ':invalid': {
        color: '#d32f2f'
      },
      '::placeholder': {
        color: '#999999'
      }
    }
  }
}

const secureForm = await sf.initSecureFields({
  tenantId: '${VAULT_TENANT_ID}',
  config: config,
});

Next Steps​