Version 1.21
Skin Creation Manual
1
Table Of contents
1. Introduction …………………………………………………………………………………………….…Page 4
2. What is a Skin……………………………………………………………………………………………..Page 5
3. Creating a Skin in the SmartPay CA…………………………………………………….……..Page 7
4. Editing the Skin files …………………………………………………………………………………Page 18
5. A/B Testing………………………………………………………………………………………………Page 22
6. Publishing the Skin to live…………………………………………………………………………Page 23
7. Getting started with customisations…………………………………………………………Page 24
Appendix A: Standard set of Languages………………………………………………………..Page 27
Appendix B: Payment page HTML skeleton…………………………………….…………….Page 28
Appendix C: Visualisation of the HTML structure……………………………………………Page 29
Appendix D: reset.css listing………………………………………………………………………….Page 30
Appendix E: Customer Fields…………………………………………………………………………Page 31
Skin Creation Manual
2
Version Control
Version
Date
Changes
1.21
01-01-2014
•
Added ‘Popup’ screen shot
1.20
10-12-2013
•
Added information for Popup
functionality
1.19
04-06-2013
•
Simple skin customisation
•
Standard set of languages to Appendix
1.18
14-05-2012
•
Added A/B testing section
1.17
21-09-2010
•
Information on editing languages files in
CA
•
Extended customer fields section
•
Information for js directory
•
Included version control log
1.16
10-08-2010
Audience
This is a technical manual aimed at It personnel involved in integrating merchants
systems with those at SmartPay
Defensive Programming Warning
SmartPay strongly recommends the use of “defensive programming” when integrating
with the SmartPay Services. This implies that automated decisions programmed into
your systems should be defaulted to non-delivery of products and services. In other
words, program your systems to only deliver products and/or services after receiving
an explicit authorisation of the requested payment and NOT to deliver in situations
where an explicit rejection is not received.
Skin Creation Manual
3
Introduction
The purpose of this manual is to help you create and set up a Skin for the SmartPay
Hosted Payment Pages (HPPs). It is not intended to be used as a CSS tutorial.
In the following sections we will cover how you can:
•
•
•
Design a Skin: Design your Skin to look like your web site
Configure the Skin: Set the configuration parameters on your Skin in the
SmartPay Merchant Back Office, known as the Customer Area (CA)
Publish the Skin: Learn how to upload and publish your Skin to the TEST and
LIVE systems
This document does not cover:
•
•
•
•
The life-cycle of a payment
The SmartPay Customer Area
Basic architecture of the SmartPay systems
Integration with the SmartPay systems
These are documented separately on our support site at
http://www.barclaycard.co.uk/business/smartpay/en/documentation
Skin Creation Manual
4
What is a Skin
A Skin is an interface overlay that is applied to the SmartPay Hosted Payment Page
(HPP) to customise it according to your brand guidelines and create a seamless
consumer checkout experience. The Skin is comprised of a set of custom
HTML/JavaScript fragments, images and CSS.
You may create multiple Skins to accommodate testing requirements or to target a
specific type of device or application, such as a mobile phone browser or point-of-sale
terminal.
The Skin provides you with the ability to determine which payment methods are offered
by default and in what order. Minimum and maximum transaction amounts per payment
method, including a payment method-specific surcharge, can also be specified.
Skins are not restricted to a single merchant account - if you have multiple merchant
accounts associated with your company account, you may use the same Skin to
process payments for each account. Likewise, you may have multiple Skins processing
payments for a single merchant account.
Language Support
You do not need to create separate Skins to support multiple languages. SmartPay
provides a base set of translations which may be customised via the SmartPay CA, or
via the Skin resource files. The standard set of languages is provided in Appendix A.
When displaying a message, the HPP will search for the string in the following locations:
1. The Skin resource files using the payment session locale res file (specified via
shopper Locale field)
2. The Skin resource files using the default locale
3. The default resource files using the payment session locale (via the SmartPay
CA)
4. The default resource files using the default locale (via the SmartPay CA)
Text strings can be set or overridden in two places:
1. In the SmartPay CA - refer to page 11
2. In the Skin resource file - refer to page 14
Skin Creation Manual
5
Payment flow selections
You can choose between two different payment flows - the One-Page Payment flow
which reduces the payment process to a single page, and the Multi-Page Payment flow
which splits the payment process into two or three discrete steps.
One-Page payment flow
The One-Page Payment flow uses Java script extensively to manipulate and validate the
page content. It is suited for use on modern browsers and when page complexity is not
an issue. Some presentation and validation occurs automatically. For example, the credit
card logo is highlighted when the shopper enters the first digits of their card, and an
error appears if the card number is invalid prior to payment submission.
Using the One-Page Payment flow is achieved by calling pay.shtml
e.g. https://test.smartpay.com/hpp/pay.shtml
Processing over multiple accounts is usually due to reconciliation or accounting
requirements, which are beyond the scope of this document.
Multi-Page payment flow
The Multi-Page Payment flow is lightweight and doesn't require Java script, ensuring
maximum compatibility with a wide range of browsers and devices, including mobile
phones and PDAs.
Using the Multi-Page Payment flow is achieved by calling select.shtml
e.g. https://test.smartpay.com/hpp/select.shtml
Optionally, the payment method selection page can be skipped, so the shopper starts
directly on the payment details entry page. This is done by calling details.shtml instead
of select.shtml. A further parameter, brandCode, should be supplied with the payment
method chosen (please refer to the Integration Manual for more details).
Skin Creation Manual
6
Creating a skin in the SmartPay CA
You can create, edit, upload, test and publish your skin in the SmartPay CA
Skin List Tab
The Skin List tab identifies all the Skins that have been created and are associated with
the Company or Merchant account.
Creating a New Skin
Click on the New tab and follow the instructions in section 2 below. You may further
customise the Skin by manipulating the Skin files directly.
Editing a Skin
You may edit a Skin by clicking on its Skin Code in the Skin List tab. This displays the Edit
Skin configuration screen and populates the values that were entered when creating the
Skin. The fields are editable; if a shared secret was set, the input field will be masked
showing “****” rather than clear text.
Skin Creation Manual
7
Uploading a skin
Once you have modified the Skin files and saved it in a ZIP file (see chapter 4), it may be
uploaded to the TEST system where it will be combined with the current UI Skin settings.
Click on the disc image in the Upload column. When uploading the ZIP file you will receive
feedback on which files were accepted and which files were rejected. If, for instance, you
attempted to upload a ZIP file with an incorrect directory structure, or that has a
different SkinCode to its “root” directory, all files will be rejected. If you are satisfied that
the accepted file list is correct you can confirm the result of the upload. Doing so will
save the current upload with the current
Skin settings to the TEST environment.
Skin Creation Manual
8
Downloading a skin
Once you have created a Skin you may download the Skin to edit the files contained
within it. Click on the disc image in the Download column; the system will display the Skin
Code, the Description, and the File version for confirmation. Click the Download button
to proceed with the download.
Skin Creation Manual
9
Removing a Skin
If a Skin is no longer required you may delete it; the system will display the Skin Code,
the Description, and the File version for confirmation. Click the List button to proceed to
the remove section and select the relevant ‘X’ for deletion.
Skin Configuration
A Skin is identified by a unique combination of eight digits and letters known as the Skin
Code. It is a system generated field; in the rare instance that the randomly generated
Skin Code contains an undesirable combination of characters you may generate a new
Skin Code by clicking on the New tab again. Since the new Skin will not be saved until the
Save Skin to Test button is pressed, you can safely repeat this a number of times.
When creating a Skin you are prompted to specify the following Skin properties. The
details for the LIVE environment are required when publishing the Skin to LIVE but not
for initial testing within the TEST environment.
Skin Creation Manual
10
Description
A description of your Skin, to easily identify it should you have multiple Skins.
Account(s)
The merchant account(s) which will be able to process payments using the Skin.
HMAC Key
Specify the HMAC Key for each environment; the Key is used to compute the merchant
signature. Please note the same Key cannot be used for both the TEST and LIVE
environments (refer to Appendix B of the SmartPay Merchant Integration Manual for
more information).
Result URL OR Continue-to URL
The result URL is the URL where you host your payment result page. Customers will be
taken to this address after they complete payment. We append parameters to the result
URL to inform you of the status of the payment. Although not recommended it is
possible to override the result URL on a per-payment basis. Please refer to the
SmartPay Merchant Integration Manual.
If the value of the result URL is not set, and if the result URL parameter value is not
passed with the Payment Request, the default SmartPay result page will be used to
display the payment result.
The continue-to URL is only applicable if you use the default SmartPay result page to
display the payment result to the customer. When the customer has seen the payment
result, clicking on the Continue button will take them to this URL. Please note, payment
status parameters are not appended to the Continue-to URL.
Skin Options
Clicking on skin options reveals less commonly used skin options
Skin Creation Manual
11
Use inline frame for VbV and MSC 3-D secure interaction
For 3D secure payments the 3D window is iframe within the HPP.
Use deprecated back-button behaviour
The standard behaviour, when the consumer clicks the previous button on the HPP, is to
redirect the consumer to the result URL with auth Result=cancelled. This option will
perform the action browser minus 1, taking the consumer back to the previous page.
Shopper Interaction for this Skin
It is recommended that this option remains set to Unset, this will ensure that the system
will select the correct shopper interaction to be used. In specific circumstances this
setting may need to be changed, please contact the Support Team to discuss your
needs.
Support partial payments
Enable partial payment for gift cards. This means that a shopper can pay a part of the
transaction amount with their gift card, the remaining amount can be paid with another
payment method.
Billing Address Fields (AVS)
Displays the billing address input fields on the HPP for credit card payments. These will
be used for AVS (address verification) in the UK, US and Canada if available. This data
can be pre-populated (see the Integration manual for details).
Show extra costs/discount as
SmartPay provides the ability to set a surcharge or discount per payment method. This
option determines how the extra cost or discount is displayed on the payment method
selection screen. "Cost" will display the extra cost (or discount) itself, e.g. "EUR 0.50 +
3.50%", or "3.50%". "Value" will display the calculated cost value, e.g. "EUR 4.50".
Break out of frame
You may decide to implement an iFrame solution, while this is supported, you should be
aware that not all payment methods support iFrames, an example is iDeal.
This setting provides you with 3 options:
•
•
•
Selecting No will disable breaking out of iFrames.
Selecting same window will open the redirect page in the same window.
Selecting New Popup will result in the payment method redirect being opened
within a popup screen. Once the shopper completes the payment flow, the
popup will close and the session will continue within the iFrame.
Skin Creation Manual
12
Please note, the New Popup option is only available for a limited set of payment
methods, please contact Support
([email protected]) for more information.
OneClick options
Use new OneClick layout
When this option is enabled the OneClick values will be displayed at the payment
method itself, instead of at the top ofthe page. Please note, not all payment methods
currently support the OneClick functionality.
OneClick Configuration
Configure which payment methods will display a 'store details' options to store the
details for OneClick payments.
POS specific options
Show POS fields on callcenter page
Displays the POS data fields on the callcenter page
Extra options
**You must save the skin before clicking on any of the following settings
Skin Creation Manual
13
Payment Methods
The Payment Methods configuration gives you control over which payment methods
will be shown by default, the order in which they are displayed, the minimum/maximum
amounts that you want to accept per payment method, and if you want to charge a
surcharge per payment method.
Custom Fields
Custom fields are a powerful feature of the payment pages that allow you to add form
fields to the HPP. These will be sent to you before final payment submission for
approval; you may use this feature to capture any additional data or permissions that
you may require, such as collecting shipping data, forcing the shopper to accept terms
and conditions, or checking a validation code.
Any form field whose name attribute is prefixed with custom fields. is considered to be a
custom field. Custom fields are added as HTML to the page in an include file which is
named customfields.txt (or a localised variant, e.g. customfields_NL.txt). See Appendix
E-1 for an example.
The contents of the custom fields are sent as a SOAP Web Service request to a URL of
your choice as configured using the Custom Fields link on the Edit Skin page. See
Appendix E-2 for an example.
If you respond with [accepted] the payment is allowed to continue. If not, you can
specify which fields failed validation and the validation messages to display. See
Appendix E-3 for an example of the response. If you need to store this data
you must do so at this point, the data cannot be sent to you via the Notification server.
Skin Creation Manual
14
Download Skin
Takes you to the Download Skin page as described above.
Remove Skin
Takes you to the Remove Skin page as described above.
Edit Language Files
The SmartPay CA offers a visual interface in which to view and modify the text strings in
the SmartPay standard language set. Languages that are not part of the standard set
can be added via the Skin resource file method explained in chapter 4.
With the Skin selected click the Edit Language Files link in the Extra Options section. A
table is shown with the following fields:
•
Key
A unique identifier for the text string (e.g. button.continue)
•
SmartPay default
The text string SmartPay associates with the key (e.g. Continue).
•
Merchant default
The text string you associate with the key (if set); this overrides the SmartPay
default if set.
Set the Merchant default value for each key whose text you wish to change from the
SmartPay default and, when done, click the save button. It is important to ensure that
you save every 5 minutes to avoid your session from timing out, resulting in a loss of
any changes that have not been saved. Every time you save a new version of the Skin
will be created.
For the -default- language the res/resource. Properties file in the Skin will be
created/updated each time you save.
To edit another language, choose its shopper locale from the Language drop-down list.
A table is shown with the
Following fields:
• Key
A unique identifier for the text string (e.g. button. Continue).
• SmartPay default
The text string SmartPay associates with the key (e.g. Continue).
• SmartPay [language] (e.g. smartpay nl)
The text string SmartPay associates with the key for the language chosen (e.g.
Continue).
• Merchant [language] (e.g. merchant nl)
The text string you associate with the key for the language chosen (if set). This overrides
the SmartPay default if set.
Skin Creation Manual
15
For each language you set merchant values for, a file called
resources_[language].properties will be created in the res directory of the Skin. For
example, if shopper locale nl is chosen, a file called resources_nl.properties in the res
directory will be created.
Please note that language translations for new keys that SmartPay introduces may not
be immediately available in all languages.
Once you have completed editing the text string be sure to download the latest version
of the Skin to your PC before making any further changes. This will ensure you have the
updated Skin resource files.
Skin Creation Manual
16
Test a Skin
It is possible to send a payment request to the HPP directly from the Skin editor. This is
a very useful tool to quickly test the correct operation of the Skin and allows you to
submit payments to the system prior to completing your integration with the HPP.
This page also shows you the versions of the Skin that are currently deployed on the
TEST and LIVE HPP servers. There is always a delay between saving a Skin or
publishing it to the LIVE server. When the Latest Version value corresponds with
the Currently on Test or Currently on Live version, all the latest changes have been
deployed to that system.
The test functionality is also useful in debugging any problems you may have with your
integration since it produces a complete payment setup form against which you can
compare your implementation.
Skin Creation Manual
17
Editing The Skin files
This chapter covers the basics of editing the Skin files you downloaded from the
SmartPay CA. SmartPay provides a number of example Skins should you need a
reference or starting point. If your requirements are not too complex creating your Skin
may simply consist of replacing a logo and one or two images.
Skin Files
As described previously, a Skin is comprised of a number of files that are uploaded in the
SmartPay CA as a ZIP archive with the following structure (assuming that the SkinCode
of your Skin is 57Hw8sLg):
The contents of the ZIP file must exactly match the layout above otherwise the file will
not be accepted when uploading to
the SmartPay CA. File names and directory names are case sensitive and, as a rule,
extra subdirectories are not allowed and filenames should be composed of simple
characters2.
Skin Creation Manual
18
Expected contents of each subdirectory:
• css
This directory contains the customised stylesheets which will be included in each
page. The main stylesheet is screen.css which is valid for the media type “screen”.
Optionally you can also supply a print.css to format a print version of the page. The
optional screen_ie6.css file is included conditionally in Microsoft Internet Explorer
version 6 or lower as a workaround for some non-standard interpretations of the
CSS stylesheet standard. See Appendix B for details on how the stylesheets are
included in the pages
.
2 Specifically only characters in the range [a-z A-Z 0-9_-.]
•
Img Any images referenced in the stylesheets or HTML include files can be
uploaded via this directory. Filenames should be composed of simple characters.
•
Inc You may provide custom HTML content such as menus, shop links,
navigation, etc. This directory contains the HTML fragments that enable you to
do so. If an included file is language dependent it is possible to supply an include
for each language locale. For details of where these includes are inserted in the
page see Appendix B.
•
res This directory contains files named resources_$localename.properties with
text overrides for the text in payment pages. The main file is resources.properties
which overrides the default string (language locale en_GB). For overriding a string
in French you create file resources_fr.properties. The format of the resource files,
as well as the allowed overrides, are described below.
•
js This directory contains the javascript code for the Skin, any custom javascript
should be added to the custom.js file which is included on each page.
Getting the right look
SmartPay has created a HTML framework which, when combined with the Skin files,
forms the HPP. The framework was designed to provide the maximum amount of
flexibility when designing and creating your layout. Appendix B shows the HTML
skeleton which generates each page and indicates where each element of the Skin files
are represented. Appendix C shows a visualisation of the HTML skeleton. However when
the default flow model is modified using a stylesheet virtually any layout can be created.
Skin Creation Manual
19
The “reset.css” Stylesheet
If you examine the HTML in Appendix B you will see that the first stylesheet included is
reset.css. This stylesheet is always included to “nullify” the default HTML styling applied
by the browser. Default styling can vary between browsers, so applying the reset.css
stylesheet makes it much easier to create a layout which renders consistently across
browsers. The source listing for reset.css is in Appendix D3.
Creating and editing translations: skin resource file
Skin resource files can be created manually in the Skin. This method may be used for
adding languages not supported in the SmartPay CA. Refer to Appendix A for the
standard language set. When creating the files you state the key name and it's value, for
example button.continue=continue. The set of keys (with default values) can be seen via
the SmartPay CA (see above).
The resource files use the Latin 1 (ISO 8859-1) encoding but it is recommended that you
treat them as US-ASCII only. This means that any character that is outside the US-ASCII
set should be encoded in Unicode using the notation \u + UTF-16 code point. Thus “é”
becomes “\u00e9” and “Ř” becomes “\u0158”.
File names are resources.properties for the default locale (en_GB). For other languages
the locale is included in the filename as resources_fr.properties for French and
resources_en_US.properties for US English.
You may notice that there are some simple stylesheet classes which do not strictly
belong in reset.css. This is purely an optimisation to reduce the number of requests to
the server.
Button Image
To change the button image that is displayed for a standard payment method or to add
the image of your custom payment method, you must add the image file to the img
directory of your Skin. You will then need to add an extra style to your screen.css file.
The syntax of this style is:
.pmB<paymentMethodName> { background-image: url("../img/<imageName>")
!important; }
For example, if your custom payment method name is c_mycustomPayment and you
have added an image file mycustomPayment.png to the img directory of your Skin, the
style that you should add to your screen.css file is:
.pmBc_mycustomPayment { background-image: url("../img/mycustomPayment.png")
!important; }
Skin Creation Manual
20
Button Name
The button name of your custom payment method must be added to the
recources.properties file. If you require specific translations for different languages these
may also be added to the resource files.
The syntax for the button name is:
pm.<payment method name>.buttonName=<Insert display name>
Custom favicon.ico
To override the default icon which is displayed in the URL area when on the payment
pages place your favicon.ico file4 in the img directory of the Skin. It will be picked up
automatically by the payment pages.
If you don't have tools to create a custom favicon.ico file, you can generate one online at:
http://www.favicon.cc/
Payment Detail Reminder Email
Please see the SmartPay Email Manual for more details about using and Skinning the
payment detail reminder email.
Skin Creation Manual
21
A/B Testing
To analyse and optimise the conversion rate the SmartPay HPPs support A/B testing.
To create an A/B testing configuration click the Create new A/B testing configuration link
on the List tab; enter the Description and HMAC key, and then click the
Create New A/B configuration on TEST button. The system will generate a new wrapper
Skin Code and return you to the List tab.
Once you have created an A/B testing configuration, it must be updated to set the Skins
to use and the distribution of payment requests. Click the A/B testing configuration Skin
Code to edit the settings as you would with a regular Skin. From the Edit A/B testing
configuration screen click Configure Distribution to configure how the shoppers are
distributed between the different regular Skins. The Skin Codes that are available are
listed in the Deselected Skins column, select the Skin Codes that are to be used and click
the --> arrow to move them to the Selected Skins column. You will note that as
you add each Skin the percentage distribution appears to the right of the Skin Codes
and a slide scale appears below it, so that you can adjust the distribution. There is a
slider for each Skin.
Setting up the Payment
When you want to use A/B testing use the Skin Code and HMAC key of the A/B testing
configuration to set up a payment session. When the shopper reaches the HPP the Skin
Code of the A/B testing configuration is randomly replaced by one of the Skins
configured within it.
Payment Completion
Due to the Skin Code of the A/B testing configuration being replaced by one of the
configured Skins, once the shopper reaches the HPP the remainder of the payment
session will continue as if the regular Skin Code was submitted in the payment session
request. As such, the Skin Code and HMAC key of the regular Skin will be used in the
result URL.
View Results
After running the A/B test for the necessary period of time you can view the results and
start analysing them. This is done by navigating to the Reports menu, Conversion tab,
and then selecting the Skin Comparison option in the SmartPay CA.
Skin Creation Manual
22
Publishing the Skin to live
If you are satisfied with the way the Skin operates on the TEST system you can publish
the Skin to the LIVE system. Please note, the publish-to-live operation does not change
any settings, it replicates the Skin as it is on the TEST environment to the LIVE
environment.
Ensure that the relevant fields in the Properties on Live Only have been populated and click the
Save Skin to Test button. Click the Publish tab.
Click the Publish to Live button.
Skin Creation Manual
23
Getting Started with Customisations
When the Skin is generated, the default settings render as follows:
Once you have downloaded the Skin you can edit the files and directories to customise
it; here are some quick changes that you can easily implement.
Skin Creation Manual
24
How to Change the Header Image
1. Save the header image that you want to use in the img directory of the Skin files
2. Update the screen.css file to reference your header image:
How to Change the Payment Method Logos
1. Save the logos you want to use in the img directory of the Skin files
2. Update the screen.css file to override the .pmB element as shown:
How to Change the font colours
1.
Update the screen.css file to set the fonts you want to use:
Skin Creation Manual
25
How to Change the pay button
1. Save the logos you want to use in the img directory of the Skin files
2. Update the screen.css file to add the following line to the .paySubmit block:
How to automatically open the credit card payment option
1. Open the cfooter.txt file that is saved in the inc folder of the Skin files
2. Add the following script to the file and save:
Skin Creation Manual
26
Appendix A: Standard set of Languages
Language
Shopper Locale
Language
Shopper Locale
Chinese – traditional
zh
Greek
el
Czech
cz
Hungarian
hu
Danish
da
Italian
it
Dutch
nl
Lithuanian
li
English – British*
en_GB
Norwegian
no
English – Canadian
en_CA
Polish
pl
English – US
en_US
Portuguese
pt
Finnish
fi
Russian
ru
French
fr
Slovak
sk
French – Belgian
fr_BE
Spanish
es
French – Canadian
fr_CA
Swedish
sv
French – Swiss
fr_CH
Thai
th
Frisian
fy_NL
Turkish
tr
German
de
Ukrainian
uk
* British English is the default shopperLocale
Skin Creation Manual
27
Appendix B: Payment page HTML skeleton
*[locale] is the locale specified in the payment setup as shopperLocale (see SmartPay
Merchant Integration Manual)
Skin Creation Manual
28
Appendix C: Visualisation of the HTML structure
Skin Creation Manual
29
Appendix D: reset.css listing
Skin Creation Manual
30
Appendix D: reset.css listing
Skin Creation Manual
31
Appendix E: Custom Fields
E-1: customerfields.txt
E-2: SOAP Request
Skin Creation Manual
32
E-3: SOAP Response
Skin Creation Manual
33