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'],
  // ...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 Integration 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 Purse.initSecureFields({
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key',
  config: config
});

Next Steps​