QPAY Customization

Customization

If the default design and layout of QPAY Checkout Page do not fit to the design and layout of your online shop, you have different possibilities to modify the design of QPAY Checkout Page.

Customization using CSS

The responsive design of QPAY Checkout Page can be adjusted using a valid CSS file. The URL to this CSS file is stored on your server and must be accessible from the Internet. The CSS file is received via the given URL in the request parameter CssUrl from your server. The rule set contained in the CSS is then used by our responsive design.

Please note that due to security reasons neither url() functions nor @import directives (e.g. external fonts) are allowed in the CSS file. If they are used they will be ignored. Never send any font changes within the CSS file. Security checks may last several minutes and lead to payment cancelation. We strongly recommend to customize your fonts using CSS templates.

These templates are available on GitHub.

For more information visit CSS.

Customization using templates

In the custom template files (see below) the following aspects of QPAY Checkout Page can be customized:

  • Display and positioning of additional images.

  • Adjustment of page layout.

  • Use of merchant font styles.

  • Use of additional texts.

Based on these template files you are able to customize the following pages within the payment process of QPAY Checkout Page:

  • Info page: This page manages user input of your consumer during the payment process.

  • Intermediate page: This page is displaying status information to your consumer during the payment process.

  • Payment page: This page displays content of external pages like authentication of 3-D Secure codes.

Please be aware that you are not able to customize 3rd party pages which may be shown to your consumer during the payment process. Typical examples of such 3rd party pages are handling the 3-D Secure process of credit cards or financial institution dependent online banking pages.

What are the customization restrictions?

During your customization please be aware of the following rules:

  • Do not use JavaScript for security reasons.

  • Do not change the structure of the folders and the names of the files. You can add additional files regarding images, or CSS if you need.

  • Do not remove the tags in the template files otherwise you may lose some specific functionalities within the payment process.

  • All your changes between the tags will be ignored and replaced by our content.

  • The maximum file size of your zipped template must not exceed 2 MB.

  • External links are not permitted.

  • Do not add additional font files.

What are the prerequisites?

The customization of QPAY Checkout Page is an optional feature which need to be ordered by contacting our sales teams and enabled by our support teams.

What are the steps to perform?

To customize QPAY Checkout Page you have to perform the following steps:

  1. Order this feature for your online shop by contacting our sales teams.

  2. Please be patient till our support teams enable this feature for your online shop.

  3. In the meantime you may already want to start editing the templates to your needs.

  4. After editing of the template files, please send them as a zipped file to our support teams. We will check your customization and configure QPAY Checkout Page according to your needs.

Editing the templates

This zip-file contains the following elements:

  • qtemplate.info.html …​ template for managing user input

  • qtemplate.intermediate.html …​ template for displaying intermediate information within the payment process

  • qtemplate.payment.html …​ template for displaying external pages within the payment process

  • /img …​ folder containing required images

  • /styles …​ folder containing CSS files

    • merchant.css …​ CSS file where you can add your CSS related customizations

    • qstyles.css …​ CSS File of standard design of QPAY Checkout Page (please do not edit this file)

What are QENTA tags?

Within the HTML files (qtemplate.info.html, qtemplate.intermediate.html and qtemplate.payment.html) you can see HTML comments which start always with the text “QENTA” and end always with “BEGIN” or “END”. In between there are individual names, depending on the individual tag.

These tags define the beginning and the end of page elements which are replaced with current values of the actual payment of your consumer when using QENTA Checkout Page. To help you during your customization of these template files, we have added typical dummy texts between these tags. In production mode all content between these tags will be replaced by QPAY Checkout Page.

<!--QENTA-[tagname]-BEGIN-->
  ... some dummy content ...
<!--QENTA-[tagname]-END-->

Which elements of QPAY Checkout Page can be customized?

Within the customization possibilities you can modify the following elements:

  • Customizing the HTML files outside the QENTA specific tags to modify the markup and content of these HTML pages.

  • Customizing the CSS file named “merchant.css” within the folder “/styles”.

  • Customizing of image files within the folder “/img” which are not used within the QENTA tags.

Masking of special characters in templates

In order to avoid any display problems in your online shop resulting from the use of special characters it is required that you mask such special characters with HTML entities in the templates you forward to QENTA.

For a list of HTML entities to mask special characters please visit HTML entities.

Testing the customization

You can either open the HTML files directly in the file system in your favorite browser or upload them to your web server to test in real conditions like https.

Which QENTA tags can be used in which page?

QENTA Tag qtemplate.info.html qtemplate.intermediate.html qtemplate.payment.html

QHEAD

Required

Required

Required

QSCRIPTWARNING

Required

Required

Required

QMERCHANTIMAGE

Optional

Optional

Optional

QMERCHANTIMAGE200X100

Optional

Optional

Optional

QBRANDIMAGEVERTICAL

Optional

Optional

Optional

QBRANDIMAGEHORIZONTAL

Optional

Optional

Optional

QBRANDIMAGE200X220

Optional

Optional

Optional

QBRANDIMAGE350X30

Optional

Optional

Optional

QCERTIFICATE

Required

Required

Required

QENTAINFO

Required

Required

Required

QORDERINFO

Optional

Optional

Never

QORDIVIDER

Optional

Never

Never

QINPUTHEAD

Required

Never

Never

QINPUTFOOT

Required

Never

Never

QINFOTEXT

Never

Required

Never

QERRORTEXT

Required

Required

Never

QINPUT

Required

Never

Never

QCSSBUTTONS

Required

Never

Never

QBUTTONS

Required

Never

Never

QWAKEUPMESSAGE

Never

Never

Required

QCHECKOUTEXPRESS

Optional

Never

Never

Description of QENTA tags

QHEAD

Contains the title of the HTML page, the include of the default CSS (“/styles/qstyles.css”), the includes for the JavaScript files and sets the content type.

QSCRIPTWARNING

Contains a warning text if JavaScript is not enabled within the web browser of your consumer.

QMERCHANTIMAGE, QMERCHANTIMAGE200X100

Contains the logo of your online shop, i.e. the image you alternatively define by setting a URL in the request parameter imageUrl. Depending on the tag you use in the template files your logo can have the following dimensions in pixel:

Tag Image width Image height

QMERCHANTIMAGE

95pixel

65pixel

QMERCHANTIMAGE200X100

200pixel

100pixel

Please be aware that you can use only one of these two tags in your customized checkout page.

QBRANDIMAGEVERTICAL, QBRANDIMAGEHORIZONTAL, QBRANDIMAGE200X220, QBRANDIMAGE350X30

Contains the logos of the brands of payment methods you offer in your online shop which may be displayed within the payment process. Depending on the tag you use within the template files the brand logos can have the following dimensions in pixel:

Tag Image width Image height

QBRANDIMAGEVERTICAL

90pixel

220pixel

QBRANDIMAGEHORIZONTAL

220pixel

90pixel

QBRANDIMAGE200X220

200pixel

220pixel

QBRANDIMAGE350X30

350pixel

30pixel

Please be aware that you can use only one of these four tags within your customized checkout page.

If you set a different background color for the HTML pages, you are able to set also the background color for the brand image containing the logos. This can be done by using “backgroundColor” as an additional optional request parameter. The value for this parameter is a hex-coded RGB color-value for the color you are using as your background color, e.g. “f0f0f0”.

QCERTIFICATE

Contains the certification logo of VeriSign.

QENTAINFO

Contains the logo of QENTA, which is required for each page within the QPAY Checkout Page.

QORDERINFO

Contains information about the current order of your consumer in your online shop. This is the text you send as request parameter “displayText” to QPAY Checkout Page. Additionally the amount, currency and current date are displayed to your consumer.

QORDIVIDER

Contains a visible horizontal line with the word or in the middle of it.

QINPUTHEAD

Contains the header for the input fields.

QINPUTFOOT

Contains the footer of the input fields.

QINFOTEXT

Contains information texts regarding the current state within the payment process.

QERRORTEXT

Contains information texts regarding error messages or critical information texts.

QINPUT

Contains input elements like text fields, option buttons, radio buttons, check boxes or selection lists. These elements are always encapsulated within the tags “QINPUTHEAD” and “QINPUTFOOT”.

QCSSBUTTONS

Contains the buttons for the actions "Cancel", "Back" and "Next". Please be aware that these buttons are defined as unordered list items and designed as buttons via corresponding CSS definitions.

QBUTTONS

Contains the buttons as images for the actions "Cancel", "Back" and "Next". These buttons are defined as images with the following names:

  • Back button: button_back_[language].gif

  • Next button: button_next_[language].gif

  • Cancel button: button_next_[language].gif

where [language] means the two-character shortcut for a language, e.g. button_back_en.gif is the image for the back button in English.

This method of displaying buttons on a customized version of QPAY Checkout Page is outdated and only documented for compatibility reasons to old customizations. Please use QCSSBUTTONS instead of QBUTTONS.
QWAKEUPMESSAGE

Contains pages of 3rd party financial institutions like 3-D Secure for credit cards or online banking pages.

QCHECKOUTEXPRESS

Contains a list of express checkout and "Buy with …​" buttons. Only displayed on the credit card input page.