Last update 6/09/2018

4. Customization

This chapter introduces two types of customization: basic and advanced. Under Basic Customization, you will learn to apply your own CSS and customize text colors, background and wrapper colors, and such. The following is an example of a default payment page using the default CSS file:

In the Advanced Customization, you will learn how to customize further the content of your form using master and partial templates, placeholders, and customizing text content with XML files. Depending on your needs, the partial templates are created and customized separately.

4.1 Basic customization

A basic customization involves configuring default style sheet under default ePDQ template.

4.1.1 Default ePDQ template

The CSS file can either be customized with a default ePDQ style or uploaded CSS file in the Template File Manager

For more information about customizing your own CSS file, refer to using style sheets.

4.1.2 Using style sheets

You can adapt the FlexCheckout layout by applying a CSS file. You will first need to upload your CSS file to the Template File Manager and link it to your ePDQ account. The CSS file consists of form/data container and elements (such as: Expiry date, CVC, Information box, and etc.) that must be set as the default CSS file. You can link each element that defines the formatting for each field to the form/data container. 

Based on your business needs, you can modify the formatting rule within each element. Click here for a list of CSS elements.

The following are Form/Data container and element samples:

/*---------FORM\DATA CONTAINER-----------*/

#payment-container {width:100%; max-width:768px !important; margin:0 auto;background:#fff;}

#payment-form-container {width:280px !important; padding:0 10px; margin:0 auto; background:#fff;overflow:hidden;}

#payment-data-container {width:260px !important; padding:20px 10px 5px 10px; margin:0 auto; color:#000; background:#fff;overflow:hidden;}

#payment-data-container .payment-label { color:#000; font-size:12px; padding-bottom:3px;}

#payment-data-container .payment-input input { width:248px !important; height:35px; color:#000; font-size:12px; margin-bottom:10px; padding:0 5px; -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; border:1px solid #000;}

#payment-data-container .payment-input select { width:109px; height:35px; color:#000; font-size:12px; margin-bottom:10px; padding:7px 5px; -webkit-border-radius: 3px;-moz-border-radius: 3px; border-radius: 3px; border:1px solid #000;}

#payment-cardnumber-label-container,#payment-accountowner-label-container{ overflow: hidden;}

/*---------FORM\DATA CONTAINER-----------*/

To get you started, we have created a sample CSS file which you can download from here (zip file). You can start creating your own CSS with this file.

You can change the default user interface (as displayed below) by applying your own CSS.

Form background color

Impacted CSS:

.payment-form-container{ Background:#f8f8f8; }

 

Form wrapper color

Impacted CSS:

#payment-data-container{ Background:#5F5F5F; }

 

Text color

>

Impacted CSS:

#payment-data-container .payment-label{color:#FFFFFF;}
#payment-data-container{color:#6E6E6E;}

Input border color

Impacted CSS:

#payment-data-container .payment-input input{border:1px solid #FFFFFF;}

 

Validation message box

Impacted CSS:

.payment-error { color:#ab1500; background:#ffe9e8; border:1px solid #ab1500;}
#payment-data-container .payment-input-error input { color:#ab1500; border:1px solid #ab1500;} #payment-data-container .payment-input-error select { color:#ab1500; border:1px solid #ab1500;}

Help information box

Impacted CSS:

#payment-cvc-info-container span.aroowImg {background: #5F5F5F url(arrow-top.png) 0 0 no-repeat;}
#payment-cvc-info-container p.cvc-info-txt{color: #6E6E6E;}
#payment-cvc-info-container div.help-box {border: 1px solid #000000;background: #FFFFFF;}

 

Information icon

Impacted CSS:

.payment-method-info {background:url(payment_info.png) 4px 1px no-repeat;}

 

Submit/Cancel button

Impacted CSS:

#payment-data-container #payment-submit {background:#c6ef84;color: #134600;}
#payment-cancel-container input {background:#f8f8f8;border-color:#000;}

 

Background color

Impacted CSS:

#payment-container {background:# e9e9e9}

 

CSS examples

#payment-container {background:# e9e9e9} .payment-form-container{ Background:#f8f8f8; }
#payment-data-container{ Background:#666; }
#payment-data-container{color:fff;}
#payment-data-container .payment-label{color:fff;}
#payment-data-container .payment-input input{border:1px solid #fff;}
.payment-error { color:#ab1500; background:#ffe9e8; border:1px solid #ab1500;}

#payment-data-container .payment-input-error input { color:#ab1500; border:1px solid #ab1500;}

#payment-data-container .payment-input-error select { color:#ab1500; border:1px solid #ab1500;}

#payment-cvc-info-container div.help-box {border: 1px solid #000;background: fff;}

#payment-cvc-info-container span.aroowImg {background: #fff url(arrow-top.png) 0 0 no-repeat;}

#payment-cvc-info-container p.cvc-info-txt{color: #000;} .payment-method-info {background:url(payment_info.png) 4px 1px no-repeat;}

#payment-data-container #payment-submit {background:#c6ef84;color: #134600;}

#payment-cancel-container input {background:#f8f8f8;border-color:#000;}

4.2 Advanced customization

For more flexibility, you can now create and customize master template and partial templates. Depending on your needs, the partial templates are created and customized separately. You can also customize the text content with XML files.
You can either choose to apply a $$$PAYMENT ZONE$$$ tag which calls for a simple template, or customize your own partial template by using placeholders.

4.2.1 Using placeholders

You can insert placeholders into master.html to customize and format your own master template (master.html) and partial templates.

You can also define the payment page appearance via a custom CSS file (newuser.css) that must be linked to the master.html. If you choose to customize your CSS file, the modified CSS file should be uploaded to the Template File Manager and set as a default.

Placeholders are categorized in three groups: Main, Element, and Grouped placeholders.

Main placeholders

The following is a list of main placeholders:
  • $$$PAYMENT ZONE$$$: Renders a request brand or payment method either through a custom template (with an available partial template) or the default template.
  • $$$TP RESOURCES URL$$$: Make available the URL to the directory where the files in the Template File Manager are found.

You also have the option of using custom scripts that will need to be linked to a custom JavaScript file. This JavaScript file can then be referenced once they are uploaded to the Template File Manager. For example, the referenced JavaScript file in <script type="text/javascript" src="$$$TP RESOURCES URL$$$/existinguser.js"></script> is existinguser.js.

To use JavaScript libraries in the templates (e.g., JQuery), you should upload the JavaScript files to the Template File Manager. Once uploaded, use $$$TP RESOURCE URL$$$ to reference the scripts. This step should be executed for any files referenced in the template: CSS, images, fonts, and so on, and will ensure that the executed script is the dedicated JavaScript.

Note: Not all data can be pushed to/pulled from a PCI non-compliant third-party host, so the use of JavaScript will impact merchants’ eligibility to PCI SAQ A.

  • $$$DISABLE MASKING$$$: Disables an input box masking.
  • $$$SUBMIT$$$: Renders a submit button for the form. For example:
<div id="payment-submit-container">
    <input id="payment-submit" type="submit" value="Submit"/> 
</div>
  • $$$CANCEL$$$: Renders a cancel button for the form. For example:
<div id="payment-cancel-container">
    <input id="payment-cancel" name="cancel" type="submit" value="Cancel"  class="cancel" />
</div>

A master template containing $$$PAYMENT ZONE$$$ will not need to include submit and cancel placeholders. However, submitted and canceled placeholders must be included if a partial template is built per payment method, or if a master template is built without $$$PAYMENT ZONE$$$ placeholder.

Element placeholders

The actual control <element> is rendered inside an element container: <div id="payment-<input_name>-<element>-container" class="payment-<element>">. For easy CSS styling, the same naming convention applies to ID and class. Element placeholders render html controls for different input elements and should follow this format:

  • $$$<input_name><element>$$$: The card number input control.
  • $$$CARD NUMBER.INPUT$$$ - CARD NUMBER: The <input_name> where INPUT is the html <element>.
  • $$$<input_name>LABEL$$$: Renders a label for the <input_name> element.

For example, the $$$CARD NUMBER LABEL$$$ placeholder renders this:

 <div id="payment-cardnumber-label-container" class="payment-label">
<label for="payment-cardnumber" id="lbl_CreditCardInputModel_CardNumber" title="CardNumber">Card number</label> </div>

For all labels a div will be rendered to act as a container:

 <div id="payment-<input_name>-label-container" class="payment-label">

The class for a label container will always be “payment-label” so the labels can be styled together.

A label for a label control will always be rendered:

<label for="payment-<input_name>" id="lbl_CreditCardInputModel_CardNumber" 
title="CardNumber">Card number</label>

To style a label control, apply the CSS file to the container ID, not to the control ID.

$$$<input_name> INPUT$$$ renders the input control for <input_name>:

<div id="payment-<input_name>-input-container" class="payment-input">
<input Id="payment-<input_name>" autocapitalize="off" autocomplete="off"
autocorrect="off" class="inp-txt" id="txt_CreditCardInputModel_CardNumber"
maxlength="40" name="CreditCardInputModel.CardNumber" pattern="[X0-9]*"
spellcheck="False" type="tel" value=""></input>
/div>

To style an input control, apply the CSS file to the container ID, not to the control ID.

$$$<input_name> INFO$$$ renders a link to a description of the <input_name> field:

<div id="payment-<input_name>-info-container" class="payment-info">
     <span id="payment-<input_name>-info"></span>
</div>

Bind any information for this field in the selected language.

$$$<input_name> ERROR$$$ renders a container for error messages from <input_name>:

<div id="payment-<input_name>-error-container">
<span class="field-validation-valid" data-valmsg-for="CreditCardInputModel.CardNumber"
data-valmsg-replace="true"></span>
</div>

Validation messages can be inserted in here.

Grouped placeholders

The element placeholders can be inserted as a group using grouped placeholders. The rendered container with a grouped placeholder: <div id="payment-<input_name>-container"></div> is where the element placeholders will be inserted and grouped. Effectively, it render this:
<div id="payment-<input_name>-container">
$$$<INPUT_NAME> LABEL$$$
$$$<INPUT_NAME> INPUT$$$
$$$<INPUT_NAME> ERROR$$$
$$$<INPUT_NAME> INFO$$$
</div>

A master template can have placeholders inside <div id="paymentForm">. The placeholders (such as $$$CARD NUMBER$$$, $$$CARDHOLDER NAME$$$, $$$EXPIRY DATE$$$, and so on) define the content of the credit card form. You can select the placeholders that best meet your needs.

The following is an example of a master template with placeholders for a credit card form labeled “paymentForm”:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <link rel="stylesheet" href="$$$TP RESOURCES URL$$$/newuser.css"/>
    </head>
<body>
    <div id="paymentForm">
$$$CARD NUMBER$$$
$$$CARDHOLDER NAME$$$
$$$EXPIRY DATE$$$
$$$CVC$$$
$$$SUBMIT$$$
$$$CANCEL$$$
    </div>
</body>
</html>

To create a direct debit form, you can use direct debit placeholders such as the one below:

$$$ACCOUNT OWNER$$$
$$$BANK ACCOUNT$$$
$$$BIC$$$

The bank account name, IBAN number, and BIC code will render a direct debit form.

If you want a template that supports multiple payment methods, you can build a master template and a partial template for the payment methods.

A master template is as follows:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>   
    <script src="$$$TP RESOURCES URL$$$/jquery-2.1.4.min.js"></script>
    <link rel="stylesheet" href="$$$TP RESOURCES URL$$$/user.css"/>
    <script type="text/javascript" src="$$$TP RESOURCES URL$$$/existinguser.js"></script>
</head>
<body>
    <div id="paymentForm">
        $$$PAYMENT ZONE$$$
    </div>
</body>
</html>

A partial template, built with placeholders ($$$CARD NUMBER$$$, $$$CARDHOLDER NAME$$$, $$$EXPIRY DATE$$$, and so on), is as follows:

<div id="paymentForm">
$$$CARD NUMBER$$$
$$$CARDHOLDER NAME$$$
$$$EXPIRY DATE$$$
$$$CVC$$$
$$$SUBMIT$$$
$$$CANCEL$$$
</div>

If you do not want to render the default payment form using $$$PAYMENT ZONE$$$, a partial template can be inserted instead.

For example, if the requested payment method is a credit card, a partial template by the name of master_creditcard.htm will be used. For a direct debit, a partial template by the name of master_directdebit.htm will be used instead.

The partial template will need to upload onto the File Manager. A naming convention must also be strictly followed. For example, if the existing master template is named master.html and is sent as a direct debit (payment method), then a partial template named master_directdebit.html will need to be uploaded to the File Manager.


4.2.2 Customizing text content with XML

You can also customize the text appearance on the tokenization pages using an XML file. The tokenization form will be used if an XML file is not applied. After customizing the XML file, you will need to upload it to the Template File Manager and use the same file name as the master template.

Note: As a prerequisite, a master template should be uploaded beforehand.

The elements must also be present to identify the fields in the XML file. Please click here for a complete list of elements. The following is an example of an element (CardHolderName) for the input of a cardholder name:

<Element ElementId="CardHolderName" >
    <Languages>
      <Language Id="en_us">Card Holder Name only en</Language>
      <Language Id="fr">Card Holder Name only  fr</Language>
    </Languages>
  </Element>

In this element, US, English, and French are specified in the Language ID. The ID tag also specifies the ISO culture code. If no elements are specified, the default text for that element will be used instead. And if the language is not specified for an element, the default language will be used.

Note:

The first line on the XML file must always start with <root> and the last line must always end with </root>.

4.3 Template File Manager

With the Template File Manager you can easily manage your templates and the various files that come with it.

To start using the File Manager, log on to your ePDQ account and go to "Configuration" > "Template" > "File Manager".

4.3.1 Upload template files

Upload Template Files

Under "Upload Template Files", select the "Files..." button to browse for the files you wish to upload. You can upload css and images (.css, .jpg, .jpeg, .gif, .png), with a maximum of 7 MB per file, and 10 MB in total.

Make your selection and then confirm.

4.3.2 Check and manage uploaded files

After the upload is done, you'll see your uploaded files on the same page in the "Uploaded files" section.

The files will first have the "Validating" status, during which some necessary security/virus checks are being performed (this can take several minutes).

You can use the files once the status has changed to "Validated".

Click the refresh button  to check the current status of your files / click the  button to delete the file permanently.

A file will get the "Refused" status if it didn't pass the security check. This can be due to a virus or if the extension of the file is wrong for instance.

4.3.3 Integration

In your code you refer to your uploaded files with a code following this structure: $$$TP RESOURCES URL$$$/[your file name].

*Call Charges: The following is a guide to call charge information from Business landlines within the UK.

Barclaycard is a trading name of Barclays Bank PLC. Barclays Bank PLC is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority (Financial Services Register number: 122702). Registered in England. Registered No. 1026167. Registered office: 1 Churchill Place, London E14 5HP

Barclays Bank PLC subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Further details can be found at www.lendingstandardsboard.org.uk escape arrow


© Barclaycard 2016