Customizing the Hosted Payment Fields

Learn how to customize Hosted Payment Fields with styling, accessibility features, or masking.

Styling the Hosted Payment Fields

Much of the styling of the Hosted Payment Fields (i.e. width, height, and outer styling) can be performed as usual via CSS.

The Hosted Payment Fields are iframes within the <div> containers, and they are nearly invisible in terms of styling. The iframes themselves do not have a border and their width and height are 100%. Input inside the iframes has no border margin or padding, has a width and height of 100%, and has a transparent background. Placeholders for inputs are provided automatically.

To apply styling inside of the Hosted Payment Fields, use the style JavaScript shown in step 4 of the Hosted Payment Fields implementation instructions.

Supported CSS Properties

We support the following CSS properties inside of the Hosted Payment Fields:

  • -webkit-appearance
  • appearance
  • background-color, background-origin, background-position, background-repeat, background-size
  • border-bottom, border-bottom-color, border-bottom-left-radius, border-bottom-right-radius, border-bottom-style, border-bottom-width, border-color, border-left, border-left-color, border-left-style, border-left-width, border-radius, border-right, border-right-color, border-right-style, border-right-width, border-style, border-top, border-top-color, border-top-left-radius, border-top-right-radius, border-top-style, border-top-width, border-width
  • bottom
  • color
  • display
  • font, font-family, font-size, font-style, font-weight
  • height
  • left
  • letter-spacing
  • line-height
  • margin, margin-bottom, margin-left, margin-right, margin-right, margin-top
  • opacity
  • outline
  • padding, padding-bottom, padding-left, padding-right, padding-top
  • position,
  • right
  • text-align
  • text-decoration
  • text-shadow
  • top
  • transition
  • width

Note: Using any unsupported CSS properties results in failure of the Hosted Payment Fields.


You can use the following selectors to define when the style is applied:

  • #ccn, #ccn:focus, #ccn:focus:-moz-placeholder, #ccn:focus:-ms-input-placeholder, #ccn:focus::-moz-placeholder, #ccn:focus::placeholder, #ccn:focus::-webkit-input-placeholder, #ccn:hover, #ccn.invalid, #ccn.valid
  • #cvv, #cvv:focus, #cvv:focus:-moz-placeholder, #cvv:focus:-ms-input-placeholder, #cvv:focus::-moz-placeholder, #cvv:focus::placeholder, #cvv:focus::-webkit-input-placeholder, #cvv:hover, #cvv.invalid, #cvv.valid
  • #exp:hover
  • :focus, :focus:-moz-placeholder, :focus:-ms-input-placeholder, :focus::-moz-placeholder, :focus::placeholder, :focus::-webkit-input-placeholder
  • :hover, :hover::placeholder
  • input
  • .invalid, .invalid:focus
  • :-moz-placeholder
  • ::-moz-placeholder
  • :-ms-input-placeholder
  • ::placeholder
  • .valid, .valid:focus
  • ::-webkit-input-placeholder


var bsObj = {
  style: {
    "input": {
      //style for all input elements
      "font": "bold 14px Arial",
      "color": "#4A5157
    ":focus": {
      //style for all elements on focus event
      "color": "orange"
    "#ccn": {
      //style only ccn element
      "color": "blue"
    "#cvv.invalid": {
      //style cvv input when invalid
      "color": "red"

Back to Top

Customizing Accessibility Features

Hosted Payment Fields accessibility features are provided as part of the solution but, you also have the option to customize some of these features.

Customizing field names for screen readers

  • Add a fieldNames object inside the accessibility object and provide names for each or some of the fields inside it. The names you provide will replace the default names we use for the aria-label attribute (which can be used by screen readers to address each field).
var bsObj = {
    accessibility: /*OPTIONAL*/ { 
      fieldNames: /*OPTIONAL*/{
        ccn: 'Card number input', //for example
        exp: 'Card expiration date input', //for example
        cvv: 'Card CVC/CVV input' //for example


UpdateAccessibilityError Callback Function

  • We pass updateAccessibilityError to your onError handler. this callback function accepts only strings and allows you to change the field’s accessibility error message (error message is invisible and meant for screen reader usage).
  • This function will only be passed if the error originated from a specific field, and it is meant to be used inside your onError function. You can use other parameters that you receive to determine an appropriate error message.
  • If you don’t make use of this function inside your onError, the field accessibility error message will default to the errorDescription that we pass as a parameter to your onError.
onError: function (tagId, errorCode, errorDescription, eventOrigin, updateAccessibilityError){
// ...Handle the error

// Update the error message:
    if (updateAccessibilityError) { // Make sure the function was passed
           var error = 'invalid input';
           switch(tagId) { // Conditionally determine an appropriate error message
                 case 'ccn':
                       error = 'invalid card number';//for example
                 case 'exp':
                       error = 'invalid expiration date';//for example
                 case 'cvv':
                       error = 'invalid card verification value'; //for example
         updateAccessibilityError(error); // Update the error message of the field

Masking Hosted Payment Field Inputs

You can activate masking for the CCN and the CVV fields by using the ccnMask and cvvMask properties inside your sdkRequest object.

  • ccnMask: When set to true, this enables masking capability for the credit card number input. The input will be masked when the shopper leaves the field and unmasked when he enters it. The last four digits of the number will always be visible.
  • cvvMask: When set to true, this enables masking capability for the cvv input. The shopper will be able to toggle the field from masked to unmasked by clicking the eye icon which will appear inside the cvv field.
var bsObj = {
    ccnMask: true,
    cvvMask: true

Back to Top