Custom Template
Jump to: Step 2, Step 3, Step 4, Step 5, Step 6, Step 7
Step 1: Getting Started
The Sage Pay Form and Server systems allow you to customise not only the look and feel of the payment pages presented to your customers, but also the design of the completion e-mails, error pages and 3D-secure frame pages. You can download our payment page templates from the Downloads section of the tech support website.
The templates are XSLT version 2 code, with no customised tags or non-standard additions. You can find a wealth of help on XSLT on the Internet and in numerous paper publications. Your web developers will be able to help you if you are unfamiliar with XLST. If you do not have a Web Developer, Sage Pay has a number of partners in your area that will be able to help (please refer to our partners list at (http://www.sagepay.com/partners.asp)
This kit not only provides the Sage Pay Default XSLT templates, the XML to populate them, and all images used on our pages, but also provides everything you need to render the XLST templates into HTML pages during testing (using the freeware versions of Saxon (http://saxon.sourceforge.net/) and Kernow (http://sourceforge.net/projects/kernowforsaxon/).
XML is provided for protocols 2.22 and 2.23 in directories XML_2.22 and XML_2.23 respectively. The default XML directory contains 2.23 versions. If you wish to use 2.22 simply copy all files from the XML_2.22 directory and paste into the XML directory.
All you need to use the renderers is the Java runtime version 1.4 or higher. The latest Java runtimes can be found at http://java.sun.com/
Once you've installed the Java runtime, you're ready to go.
To render a template, follow these simple steps:
It's a simple as that. When you are changing the XLST pages, any mistakes you make in the XSLT or XHTML code will be reported in the bottom window of the Kernow page when you click Run. The line number and position are displayed with each error, so it's very easy to debug your code.
The following templates are included in this kit:
• card_selection.xslt - This is the initial screen presented to your customers that asks them to click on an image to select the required card type.
• card_details.xslt - The second payment page, which asks for the card number, expiry date, card holder name etc. It also has pop-up links to static HTML information pages in the images folder. Feel free to change these, or add other pop-ups that you think may help your customers.
• card_confirmation.xslt - The third payment page, which displays the full order summary (including basket contents where they have been passed) and a summary of the chosen card.
• card_authentication.xslt - The frame page surrounding the bank 3D-Secure pages which may be presented to your customers if you have enabled 3D-Secure on your account. This now has a "skip3d" button to allow users to continue even if 3D-Authentication fails.
• authorisation.xslt - The "Authorising please wait" screen displayed for the few seconds that Sage Pay are talking to your acquiring bank to obtain an authorisation.
• error.xslt - The error screen displayed by Server and Form if a problem has occurred with a transaction.
• 3d_callback.xslt, 3d_redirect.xslt - Simple forwarding pages which do not really need modification. They only display during the 3D-Secure process if a customer has JavaScript turned off. Their role is to post 3D-secure information from Sage Pay to the Issuing bank and back again. Please do not change the function or the 3D-Secure process will not work.
• post_through_browser.xslt - A very simple page that automatically redirects the browser to the 3D Secure ACSURL. Only visible if JavaScript is disabled in the browser. Shouldn't really need modification but can be rendered using any xml file and JavaScript turned off in your browser.
• Form only: form_response.xslt - The page displayed to Form customers if there are errors during transaction registration or completion. This provides a link back to your FailureURL page to prevent the customers being stranded on the Sage Pay site.
• Form only: customer_email.xslt - The e-mail sent to your customer when a transaction completes successfully.
• Form only: vendor_email.xslt - The e-mail sent to your VendorEMail address whenever a transaction completes.
• Server only: card_details_low.xslt - A low profile version of card_details.xslt which requests the same details apart from the card type. Render using card_details.xml.
• Server only: card_authentication_low.xslt - A low profile version of card_authentication.xslt. A very simple page that automatically redirects the browser to a full screen 3D-secure page. This page will only be visible if scripting is disabled within the browser. Can be rendered using any xml file and JavaScript disabled in your browser.
• Server only: authorisation_low.xslt - A low profile version of authorisation.xslt. A basic full screen "Authorising please wait" page with a simple animated gif. Render using authorisation.xml.
• i18n.xml - The templates are capable of supporting multiple languages however it is your responsibility to provide translations. The text displayed on the screen is sourced from the i18n.xml file included with the templates (except the e-mails). If you wish to create pages that support multiple languages, you should add additional text entries in this file. When you are satisfied your templates work in English, create a <texts xml:lang="xx"> (where xx is the two character ISO 639 language, e.g. "fr" or "de") with the same text labels, but their contents translated.
• countrys.xml - This file is used to create the Billing Country drop-down list on the Card Details page. This should not be amended.
• states.xml - This file is used to create the Billing State drop-down on the Card Details page for United States customers. A Billing State is only required if 'United States' has been selected in the Billing Country drop-down. This should not be amended.
The files are all multiple language compliant. You'll notice they obtain the text to display on the screen from the i18n.xml file included with the templates. If you wish to create pages that support multiple languages, you should add additional text entries in this file and when your templates work in English, create a <texts xml:lang="xx"> (where "xx" is the language, e.g. "fr" or "de") with the same text labels, but their contents translated. Sage Pay will provide additional language translations for our default templates as we create them.
To edit the templates, simply open the XSLT file in your preferred editor and change the layout at your leisure. We use DreamWeaver at Sage Pay, but many XSLT editors are available on the net (including freeware editors). The images you can change are all included in the "CustomTemplates/images/YourImages folder". Place any additional images or pop-ups in that folder, or subfolders thereof. Don't try to access images from anywhere else. Your templates will not work on our systems if you do so.
You'll notice that the Sage Pay logo and the JavaScript code is loaded from the images/Sage Pay folder. You cannot change this code or the images there (when your templates are uploaded, nothing from this folder will be uploaded to our servers) but you can use the JavaScript mouse-over and pop-up functions in your code.
The support team will validate your templates, but cannot offer to debug them for you. Please ask your web-developers for help if you are experiencing difficulties with XSLT or the multi-language support.
The templates are extremely flexible and allow you to completely customise the look and feel of the pages, but there are some rules you must follow:
• Do not change FORM field contents - If an edit box called "CardNumber" is rendered on a page inside a Form called "Continue", then your page must also have an edit box called "CardNumber" inside a Form called "Continue". You can change how that box displays, but not the fact that a box needs to be there. Also if a page contains three forms which submit different data, you should ensure your page behaves identically.
• No additional JavaScript - Sage Pay ONLY allow the pop-up and mouseover functions we've provided for you. No other JavaScript is allowed.
• Do not reference externally - We do not allow templates that reference code or images that are not on our server. All references should be to local documents placed in the "YourImages folder".
• Do not navigate away from the payment pages - We do not allow links or redirects to pages before or after the payment pages. Once on the Sage Pay site, the customer must complete the payment process either by a successful transaction or by cancelling.
• Do not embed active content - ActiveX controls, streaming content, large movie files etc. will not be supported.
• Include the Sage Pay Logo in card_selection.xslt - Somewhere on your card-selection screen, you must include the Sage Pay logo. It is optional on subsequent screens.
• Do not modify the JavaScript files or logos in the "images/Sage Pay folder" - As mentioned above, these are provided for your reference and use, but will not be uploaded with your templates, so changing them will not help you.
• Do not modify the XML file - This are example files used for template creation. The real XML used by your templates on our test and live systems is generated dynamically. If you try to add fields to the XML and reference them, then these changes will not be transferred to live.
• ALWAYS INCLUDE NOSCRIPT SECTIONS for every <SCRIPT> section in your templates. If you only use our mouseover functions to submit pages, for example, customers without JavaScript enabled will not be able to submit the pages and their payments will not be taken. You do not have to use JavaScript on your pages at all, if you do not wish to.
When Sage Pay store your logo, it is held in a subfolder of our central images folder with the same name as your Vendor Name, called [VendorName].gif. For example, if your Vendor Name is wonka, your main logo will be at https://[Sage PaysystemURL]/images/wonka/wonka.gif
This logo will be displayed in our default templates as well as your custom templates, so if you need to switch back to our templates, your customers will still know they are buying from you.
In the custom template kit, this image (called YourImages.gif): represents the location of your real logo (which you provide to Sage Pay when your account is set up). If you wish to replace this with your real logo whilst testing these pages, simply overwrite it, but leave your logo called YourImages.gif and leave the references to it in the style sheets as they are, for example:
<img border="0">
<xsl:attribute name="src"><xsl:value-of select="payment-model/imagesURL"/><xsl:value-of select="payment-model/vendor/vendorname"/><xsl:text disable-output-escaping="yes">/</xsl:text><xsl:value-of select="payment-model/vendor/logo"/></xsl:attribute>
</img>
Bear in mind that your real logo will be called [VendorName].gif, so don't create any other images with that name.
Step 6: Sending your templates to Sage Pay
When you are happy that your pages work correctly on your local machine (and have tested with JavaScript enabled AND disabled), zip up the contents of your XSLT and YourImages folders and e-mail them, along with your Vendor Name to templates@sagepay.com.
The team will validate them against the rules above, and if everything is okay, upload them to the test server for you. This process can take up to 72 hours. Once the team has come back to you, log into your Test My Sage Pay screens and set your templates to Custom in My Sage Pay, then test them.
Unfortunately we cannot debug your XSLT code for you. Our team can only validate your templates against the rules above, not correct the XSLT itself (although we will validate that the XSLT is valid using the same tools we've provided to you). If you need help with XSLT, your web developer should be able to provide it.
If you are happy with them on the test server, email that address again and ask for your templates to be set live. The team will upload them for you and let you know when they are there. Again, you can set them live in your Live My Sage Pay area.
If you have questions about templates, please e-mail support@sagepay.com (include your Vendor Name) and we'll do our best to help you.
Step 7: Low profile payment pages
With Server, you now have the option of using LOW PROFILE payment pages, enabling you to select the minimal Server payment page screens instead of the normal default set.
Low Profile templates are designed to run inside iframes and present full screen HTML pages with no pop-ups, no positional data and minimal graphics. All transaction information passed between merchant sites and the Sage Pay systems is encrypted using 128-bit SSL certificates, therefore we can ensure complete security using the Sage Pay payment pages. However, from a customer's perspective, the secure padlock will not display within the iframes, therefore we strongly recommend you to ensure you obtain your own SSL certificate for these pages.
Please note that you will NOT be able to accept PayPal transactions with Low Profile templates enabled (as PayPal transactions cannot run inside iframes). The Low Profile option simply displays a Card Details page to the shopper (rather than the initial ‘card selection’ screen), asking for the Card details and Billing Address details.
If 3D Secure is active on your account, the customer is redirected to the card issuing bank’s 3D Secure page, (presented as a full screen HTML page). Once the shopper completes 3D Authentication, (or if 3D Secure is disabled on your account), the shopper is presented with the page below whilst Sage Pay contact the bank for authorisation.
If you would like to use Low profile payment pages, you will need to pass a value of “LOW” in the ‘Profile’ field included in the Transaction Registration Post (see Appendix A1).
You have the option of customising the Low Profile pages, (including the ‘ReadOnly’ and ‘NoAddress’ options) so that the look and feel of the payment pages is similar to your own site. For further information about how you can customise the LOW PROFILE payment pages, please refer to the Sage Pay Custom Templates Kit, which can be downloaded from the support section on our website:
http://www.sagepay.com/developers.asp