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: {
            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

//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

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:

<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:

<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)

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"
                    }
                }
            }
        }
    }
}