---
title: Customisation
slug: FVh6-customisation
docTags: 
createdAt: 2024-08-28T12:19:15.971Z
---

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

:::BlockQuote
const iframeConfiguration = \{
    iframe \{
        ...
   }
}

var judo = new JudoPay("yourAPIToken", true);
var payment = judo.createCardDetails("payment-iframe", iframeConfiguration);
:::

:::hint{type="info"}
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:

1. Default 
2. Focus 
3. Error 
4. Valid 
5. cv2 
6. expiryDate 

Each of the above properties has two properties:

1. Field 
2. 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**.

:::CodeblockTabs
Styles Object Example

```css
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

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/U32tGC-6vJ8YTrVpXcOtc_3d-secure-2-authentication-7.png" size="56" width="501" height="131" position="flex-start" alt="form layout options" showCaption="false"}

***

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

:::::Tabs
:::Tab{title="Fonts Properties Descriptions"}
| **Property Name** | **Values**                                                                                                 | **Example Value**                       |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| family            | Specifies the name of the font face value properties.                                                      | Roboto                                  |
| src<br />         | Specifies the resource containing the font data.                                                           | "/fonts/OpenSans-Regular-webfont.woff2" |
| display           | Determines how a font face is displayed.<br />Based on whether and when it is downloaded and ready to use. | auto<br />                              |
| style<br />       | Specifies the font styles.<br />                                                                           | italic<br />                            |
| unicodeRange      | The range of font Unicode code points to be used.                                                          | U+0025-00FF, U+4??                      |
| weight            | Specifies the font weight, or boldness.                                                                    | 400                                     |


:::

::::Tab{title="Example Snippet"}
:::CodeblockTabs
Assigning Font Example

```javascript
//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:

1. 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.**
2. To define &#x61;**&#x20;new language**:&#x20;
   Supply all translation keys and values
3. To override an **existing language**:&#x20;
   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

:::CodeblockTabs
Example Dictionary Object

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

```
:::

:::hint{type="warning"}
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 &#x7B;0} and &#x7B;1}.
- The &#x7B;0} and &#x7B;1} values will be will be swapped for strings at runtime, depending on the current state of the iFrame form.
  For example:
  - &#x7B;0} will change to the card verification code acronym
    **This will be named depending on the card type, for example CVC, or CVV.**
  - &#x7B;1} will refer to the detected card type, for example Visa, Mastercard, Diners Club International or Discover.

Ensure you include &#x7B;1} or &#x7B;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](docId\:qfxaWPAQl_-2EVfP8y94d).

Set th&#x65;**&#x20;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.

:::hint{type="info"}
The default property is English.
:::

:::::Tabs
:::Tab{title="Language Codes"}
| **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](docId\:FVh6jG8c0jC7Q7OC9uoac).
:::

::::Tab{title="Change at Page Load"}
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:

:::CodeblockTabs
Set to Spanish on Page Load

```javascript
<script>
  
    // ...Judopay WebSDK Setup...

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

    judopay.createCardDetails('judopay-payment-iframe', config);
</script>
```
:::
::::

::::Tab{title="Change at Runtime"}
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:

:::CodeblockTabs
Set to German on Button Click

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

:::CodeblockTabs
iFrame Configuration Example

```javascript
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"
                    }
                }
            }
        }
    }
}
```
:::