Customisation

Customising your Web SDK Integration
Form Customisation
The iFrameConfiguration object is key for customising the look and behaviour of the iFrame.
You can change the appearance, behaviour and language, by passing the JSON configuration object into createCardDetails:
const iframeConfiguration = {
    iframe {
        ...
   }
}

var judo = new JudoPay("yourAPIToken", true);
var payment = judo.createCardDetails("payment-iframe", iframeConfiguration);
It is optional to provide the iframeConfiguration object in the createCardDetails call. 
If it is not provided, the customisation properties will be set as their default values.
﻿
Styles Properties
Configuration to style fields is within the Styles object. 
Styles can be applied to all fields by placing the style attribute in the default object inside Styles.
You can also apply styles individually to fields, directly to the field name.
The styles object has six properties:
Default 
Focus 
Error 
Valid 
cv2 
expiryDate 
Each of the above properties has two properties:
Field 
Label 
The properties for field and label:
Mapped to the style objects of the input and label HTML elements. 
The properties for focus, error and valid:
Mapped on state transition allowing the functionality to be consistent with other forms on your site.
Any property defined in default will be applied to all the fields.
Any property defined in a field will take priority over a default property, the fields are expiryDate and cv2.
All valid style properties are supported and take the form of camel cased CSS properties, eg padding-bottom becomes paddingBottom.
Styles Object Example
styles: {
            default: {
                field: {
                    backgroundColor: '#0a0a0a',
                    color: '#EEE',
                    padding: '10px',
                    margin: '0 20px',
                    width: '90%',
                    borderRadius: '4px',
                    boxShadow: 'rgba(255, 255, 255, 0.8) 0px 0px 10px inset'
                },
                label: {
                    color: '#EEE',
                    padding: '10px 10px 0 25px',
                    fontWeight: 'bold',
                    textTransform: 'capitalize'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#2a2a2a',
                    color: '#EEE'
                },
            },
            error: {
                field: {
                    backgroundColor: '#1a0a0a',
                    color: '#990000'
                }
            },
            valid: {
                field: {
                    color: '#CFC'
                }
            },
            cv2: {
                field: {
                    margin: "0 20px 10px;"
                },
            expiryDate: {
                field: {
                    marginBottom: "10px;"
                }
            }
styles: {
            default: {
                field: {
                    backgroundColor: '#0a0a0a',
                    color: '#EEE',
                    padding: '10px',
                    margin: '0 20px',
                    width: '90%',
                    borderRadius: '4px',
                    boxShadow: 'rgba(255, 255, 255, 0.8) 0px 0px 10px inset'
                },
                label: {
                    color: '#EEE',
                    padding: '10px 10px 0 25px',
                    fontWeight: 'bold',
                    textTransform: 'capitalize'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#2a2a2a',
                    color: '#EEE'
                },
            },
            error: {
                field: {
                    backgroundColor: '#1a0a0a',
                    color: '#990000'
                }
            },
            valid: {
                field: {
                    color: '#CFC'
                }
            },
            cv2: {
                field: {
                    margin: "0 20px 10px;"
                },
            expiryDate: {
                field: {
                    marginBottom: "10px;"
                }
            }
﻿
﻿
Form Layout
Three layout options are provided:
Vertical
Compact
Horizontal
﻿
﻿
Form Fonts
An array of JSON objects each representing a font, are added to the page.
They can be referenced from the Style object.
Each object can have the following properties:
Fonts Properties Descriptions
Example Snippet
Property Name
Values
Example Value
family
Specifies the name of the font face value properties.
Roboto
src
﻿
Specifies the resource containing the font data.
"/fonts/OpenSans-Regular-webfont.woff2"
display
Determines how a font face is displayed.
Based on whether and when it is downloaded and ready to use.
auto
 
style
﻿
Specifies the font styles.
﻿
italic
 
unicodeRange
The range of font Unicode code points to be used.
U+0025-00FF, U+4??
weight
Specifies the font weight, or boldness.
400
﻿
Assigning Font Example
//The following example loads Roboto from Google fonts and assigns it:
fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange: 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                },
                label: {
                    fontFamily: "'Roboto', sans-serif",
                }
            },

//The following example loads Roboto from Google fonts and assigns it:
fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange: 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                },
                label: {
                    fontFamily: "'Roboto', sans-serif",
                }
            },
﻿
﻿
Adding a new Language
You can:
Add any language you need.
Override some or all of the translations of an existing language.
The Web SDK supports: en, de, fr, es, pt.
To add a new language:
Define a dictionary of the language(s) you wish to add or override.
This is an object of languages, along with their translation keys and values.
Ensure the keys have no spelling errors, otherwise the translations will not work.
To define a new language: 
Supply all translation keys and values
To override an existing language: 
Supply only the translation key / pair values to override
For the purpose of this exercise, the following example dictionary object contains:
Translations for a new language: Italian
Translations for an existing language: English
Example Dictionary Object
const exampleDictionary = {
//This defines a new language so all keys must be provided
  it: {
    fieldLabels: {
        cardNumberLabel: 'Numero di carta',
        expiryDateLabel: 'Data di scadenza',
        cardVerificationCodeLabel: 'CVC',
        postCodeLabel: 'Post Codice',
        countryLabel: 'Paese',
        cardholderNameLabel: 'Nome del titolare'
        },
    fieldPlaceholders: {
        cardNumberPlaceholder: 'Numero di carta',
        expiryDatePlaceholder: 'MM / YY',
        cardVerificationCodePlaceholder: 'CVC',
        postCodePlaceholder: 'Post Codice',
        countryPlaceholder: 'Paese',
        cardholderNamePlaceholder: 'Nome del titolare'
      },
//will translate countryList items from WebSDK version 0.0.39
    countryList: {
        uk: 'RU',
        usa: 'USA',
        canada: 'Canada',
        other: 'Altro'
        },
    errors: {
        onlyNumbersAllowed: 'Il numero della carta può contenere solo numeri',
        invalidCardNumber: 'Numero della carta non valido',
        cardTypeNotRecognized: 'Tipo di carta non riconosciuto, ricontrolla il tuo numero',
        cardTypeNotSupported: '{1} non è supportato', // from WebSDk version 0.0.39
        cardNumberRequired: 'Numero della carta richiesto',
        cardExpired: 'La carta è scaduta',
        invalidCardExpiryDate: 'La data di scadenza della carta non è valida',
        expiryDateRequired: 'Data di scadenza richiesta',
        codeTooShort: '{0} codice troppo corto per {1} scheda',
        codeTooLong: '{0} codice troppo lungo per {1} scheda',
        onlyNumbersAllowedInCode: '{0} il codice può contenere solo numeri',
        codeRequired: '{0} codice richiesto per {1} scheda',
        invalidPostCode: 'Il codice postale/postale non è valido',
        generic: 'Mi dispiace, si è verificato un errore, non ti è stato addebitato.',
        cardHolderNameRequired: 'È richiesto il nome del titolare della carta',
        cardHolderNameTooShort: 'Il nome del titolare della carta non può essere inferiore a 4 caratteri',
        cardHolderNameSpecialChars:
              'Il nome del titolare della carta non può contenere numeri o caratteri speciali'
        }
    },

//This defines an already existing language
//Not all keys are required, but those that are will override the SDK's values
  en: {
    fieldLabels: {
      cardNumberLabel: 'Credit Card Number',
      expiryDateLabel: 'Expiration Date',
      cardVerificationCodeLabel: 'CVC'
        },
      fieldPlaceholders: {
        cardNumberPlaceholder: 'xxxx xxxx xxxx xxxx',
        expiryDatePlaceholder: 'MM / YY ',
        cardVerificationCodePlaceholder: 'xxx'
        },
      errors: {
        generic: 'Sorry, an error has occurred.',
        cardHolderNameRequired: 'Please enter a cardholder name',
        cardHolderNameTooShort: "Card Name can't be less than 4 characters",
        cardHolderNameSpecialChars: "Card Name can't contain numbers or special characters"
        }
    }
}

const exampleDictionary = {
//This defines a new language so all keys must be provided
  it: {
    fieldLabels: {
        cardNumberLabel: 'Numero di carta',
        expiryDateLabel: 'Data di scadenza',
        cardVerificationCodeLabel: 'CVC',
        postCodeLabel: 'Post Codice',
        countryLabel: 'Paese',
        cardholderNameLabel: 'Nome del titolare'
        },
    fieldPlaceholders: {
        cardNumberPlaceholder: 'Numero di carta',
        expiryDatePlaceholder: 'MM / YY',
        cardVerificationCodePlaceholder: 'CVC',
        postCodePlaceholder: 'Post Codice',
        countryPlaceholder: 'Paese',
        cardholderNamePlaceholder: 'Nome del titolare'
      },
//will translate countryList items from WebSDK version 0.0.39
    countryList: {
        uk: 'RU',
        usa: 'USA',
        canada: 'Canada',
        other: 'Altro'
        },
    errors: {
        onlyNumbersAllowed: 'Il numero della carta può contenere solo numeri',
        invalidCardNumber: 'Numero della carta non valido',
        cardTypeNotRecognized: 'Tipo di carta non riconosciuto, ricontrolla il tuo numero',
        cardTypeNotSupported: '{1} non è supportato', // from WebSDk version 0.0.39
        cardNumberRequired: 'Numero della carta richiesto',
        cardExpired: 'La carta è scaduta',
        invalidCardExpiryDate: 'La data di scadenza della carta non è valida',
        expiryDateRequired: 'Data di scadenza richiesta',
        codeTooShort: '{0} codice troppo corto per {1} scheda',
        codeTooLong: '{0} codice troppo lungo per {1} scheda',
        onlyNumbersAllowedInCode: '{0} il codice può contenere solo numeri',
        codeRequired: '{0} codice richiesto per {1} scheda',
        invalidPostCode: 'Il codice postale/postale non è valido',
        generic: 'Mi dispiace, si è verificato un errore, non ti è stato addebitato.',
        cardHolderNameRequired: 'È richiesto il nome del titolare della carta',
        cardHolderNameTooShort: 'Il nome del titolare della carta non può essere inferiore a 4 caratteri',
        cardHolderNameSpecialChars:
              'Il nome del titolare della carta non può contenere numeri o caratteri speciali'
        }
    },

//This defines an already existing language
//Not all keys are required, but those that are will override the SDK's values
  en: {
    fieldLabels: {
      cardNumberLabel: 'Credit Card Number',
      expiryDateLabel: 'Expiration Date',
      cardVerificationCodeLabel: 'CVC'
        },
      fieldPlaceholders: {
        cardNumberPlaceholder: 'xxxx xxxx xxxx xxxx',
        expiryDatePlaceholder: 'MM / YY ',
        cardVerificationCodePlaceholder: 'xxx'
        },
      errors: {
        generic: 'Sorry, an error has occurred.',
        cardHolderNameRequired: 'Please enter a cardholder name',
        cardHolderNameTooShort: "Card Name can't be less than 4 characters",
        cardHolderNameSpecialChars: "Card Name can't contain numbers or special characters"
        }
    }
}
﻿
It is important the language dictionary follows this structure with inner dictionaries and strings, so the translations can be applied.
Error Message strings:
The above example dictionary object contains error message strings which contain values {0} and {1}.
The {0} and {1} values will be will be swapped for strings at runtime, depending on the current state of the iFrame form.
For example:
{0} will change to the card verification code acronym
This will be named depending on the card type, for example CVC, or CVV.
{1} will refer to the detected card type, for example Visa, Mastercard, Diners Club International or Discover.
Ensure you include {1} or {0} in your translation strings (for appropriate keys), to enable this behaviour.
For more information on error messages, including these dynamic values, see Payment Form Error Messages﻿.
Set the customLanguages property in your iFrame configuration object to the dictionary object you have defined.
﻿
Changing the Form Language
Judopay's Web SDK supports multiple languages.
The default property is English.
Language Codes
Change at Page Load
Change at Runtime
Language
Code
English
en
French
fr
Spanish
es
Portuguese
pt
German
ge
You can also add other languages or override an existing language, see Adding a New Language﻿.
Set the language variable in your iFrame configuration object to the alpha-2 country code (above) for the desired language.

For the purpose of this exercise, the language is set to Spanish when the iFrame is initially loaded onto the page:
Set to Spanish on Page Load
<script>
  
    // ...Judopay WebSDK Setup...

    const config =  {
      isGeoLocationGatheringAllowed: true,
      iframe: {
          //...other iframe properties
          language: 'es'
        }
      }

    judopay.createCardDetails('judopay-payment-iframe', config);
</script>
<script>
  
    // ...Judopay WebSDK Setup...

    const config =  {
      isGeoLocationGatheringAllowed: true,
      iframe: {
          //...other iframe properties
          language: 'es'
        }
      }

    judopay.createCardDetails('judopay-payment-iframe', config);
</script>
﻿
You can change the language used in the form at run time. This is useful for consumers running a Single Page Application (SPA).



Call the Web SDK method for updating the language changeIframeLanguage('de')
You can call this method when an event occurs, such when a button is clicked, to dynamically changing the language.

For the purpose of this exercise, the method is called when a button is clicked, and the iFrame language is changed to German:
Set to German on Button Click
<button onclick="onButtonClick()">Translate to German</button>

<script>

  function onButtonClick() {
    judo.changeIframeLanguage('de');
  }
  
</script>
<button onclick="onButtonClick()">Translate to German</button>

<script>

  function onButtonClick() {
    judo.changeIframeLanguage('de');
  }
  
</script>
﻿
﻿
Configuration File Example
Below is an example configuration object that customises the payment iFrame.
It is provided as a parameter to the createCardDetails Web SDK call:
judo.createCardDetails('payment-iFrame', iFrameConfiguration)
iFrame Configuration Example
const iFrameConfiguration = {
    isGeoLocationGatheringAllowed: true,
    iframe: {
        language: 'en',
        errorFieldId: 'judopay-errors',
        cardTypeIconRight: '-400px',
        cardTypeIconTop: '-50x',
        backgroundColor: '#EAECEF',
        showCardTypeIcons: true,
        layout: 'vertical',
        enabledPaymentMethods: ['CARD'],
        defaultCountryCode: 'US',
        isCountryAndPostcodeVisible: false,
        isCardHolderNameVisible: false,
        disableUnderline: true,
        errorsDisplay: 'HIDE_UNDER_FIELDS',
        shouldAutofocus: false,
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                  'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: 'Roboto, sans-serif',
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px'
                },
                label: {
                    opacity: '1',
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0'
                },
                label: {
                    opacity: '1'
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0'
                },
                label: {
                    color: 'green',
                    opacity: '1'
                }
            },
            customLanguages: {
                en: {
                    fieldLabels: {
                        cardNumberLabel: 'Credit Card Number',
                        expiryDateLabel: 'Expiration Date',
                        cardVerificationCodeLabel: 'CVC'
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: 'xxxx xxxx xxxx xxxx',
                        expiryDatePlaceholder: 'MM / YY ',
                        cardVerificationCodePlaceholder: 'xxx'
                    },
                    errors: {
                        generic: 'Sorry, an error has occurred.',
                        cardHolderNameRequired: 'Please enter a cardholder name',
                        cardHolderNameTooShort: "Card Name can't be less than 4 characters",
                        cardHolderNameSpecialChars: "Card Name can't contain numbers or special characters"
                    }
                }
            }
        }
    }
}
const iFrameConfiguration = {
    isGeoLocationGatheringAllowed: true,
    iframe: {
        language: 'en',
        errorFieldId: 'judopay-errors',
        cardTypeIconRight: '-400px',
        cardTypeIconTop: '-50x',
        backgroundColor: '#EAECEF',
        showCardTypeIcons: true,
        layout: 'vertical',
        enabledPaymentMethods: ['CARD'],
        defaultCountryCode: 'US',
        isCountryAndPostcodeVisible: false,
        isCardHolderNameVisible: false,
        disableUnderline: true,
        errorsDisplay: 'HIDE_UNDER_FIELDS',
        shouldAutofocus: false,
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                  'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: 'Roboto, sans-serif',
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px'
                },
                label: {
                    opacity: '1',
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0'
                },
                label: {
                    opacity: '1'
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0'
                },
                label: {
                    color: 'green',
                    opacity: '1'
                }
            },
            customLanguages: {
                en: {
                    fieldLabels: {
                        cardNumberLabel: 'Credit Card Number',
                        expiryDateLabel: 'Expiration Date',
                        cardVerificationCodeLabel: 'CVC'
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: 'xxxx xxxx xxxx xxxx',
                        expiryDatePlaceholder: 'MM / YY ',
                        cardVerificationCodePlaceholder: 'xxx'
                    },
                    errors: {
                        generic: 'Sorry, an error has occurred.',
                        cardHolderNameRequired: 'Please enter a cardholder name',
                        cardHolderNameTooShort: "Card Name can't be less than 4 characters",
                        cardHolderNameSpecialChars: "Card Name can't contain numbers or special characters"
                    }
                }
            }
        }
    }
}
﻿
﻿
Property Name	Values	Example Value
family	Specifies the name of the font face value properties.	Roboto
src	Specifies the resource containing the font data.	"/fonts/OpenSans-Regular-webfont.woff2"
display	Determines how a font face is displayed. Based on whether and when it is downloaded and ready to use.	auto
style	Specifies the font styles.	italic
unicodeRange	The range of font Unicode code points to be used.	U+0025-00FF, U+4??
weight	Specifies the font weight, or boldness.	400
Language	Code
English	en
French	fr
Spanish	es
Portuguese	pt
German	ge
Updated 28 Aug 2024
Google Pay™ for Web
Payment Form Error Messages