Field	Type	Description
header	Element	Set of the elements associated with the header of a form.
footer	Element	Set of the elements associated with the footer of a form.
submit	Element	Set of the elements associated with the submit button on a form.
cancel	Element	Set of the elements associated with the cancel button on a form.
agreement	Element	Set of the elements associated with the agreement for using a form.
paymentOptionInformation.header	Element	Set of the elements associated with the header of the paymentOptionInformation section of a form.
paymentOptionInformation.footer	Element	Set of the elements associated with the footer of the paymentOptionInformation section of a form.
transactionInformation.header	Element	Set of the elements associated with the header of the transactionInformation section of a form.
transactionInformation.footer	Element	Set of the elements associated with the footer of the transactionInformation section of a form.
cscHint	Element	Set of the elements shown next to the Card Security Code (CSC) entering field.

6) The Element structure includes the following attributes:


The gateway allows to customize pages in two modes - standard and advanced. In rare occasions when standard customization is not enough, and it is necessary to change the layout and behavior of the pages drastically, the advanced customization may be used.

HPP Customization

Basic Customization (development in progress)

Basic customization is used when it is necessary to change the functionality of the pages (for example, validation, page behavior, etc.). For this type of customization, the following files are used:

• custom.js – a script used for merchant/account’s pages customization (validation, custom scripts, etc.).
• custom.css - a style sheet used for the addition of custom styles to a merchant’s pages.

If it is necessary to customize the pages of a merchant/account using the standard methods, follow these rules:

1. By default, all default pages are available for every merchant. For this reason, you don’t have to download them. You can call them with an API request.
2. For a merchant/account to process through the customized pages, use two scripts - profile.js and custom.js:

• if it necessary to change labels and add your own text, use profile.js;
• if it is necessary to change validation and drastically change the layout of a page, use custom.js.

3. Depending on the level of customization, download the script you need, modify it, and upload to the directory of the merchant/account.
4. If you need to add your own CSS styles, use a custom.css style sheet by uploading it to the directory of the merchant/account.

Detailed steps are described in the General Customization via UI section.

Advanced Customization

You can customize pages in an advanced way via modification of the default pages or adding your own pages to a merchant/account.

If it is necessary to customize the pages of a merchant/account using the advanced methods, follow these rules:

1) Custom pages, which are HTML files, are configured and modified through the uploading process to the merchant’s/account’s directory on the user interface:

• if the merchant/account already has customized pages, they are uploaded to its directory;
• if there are no customized files, then default pages can be used as templates. In this case, default pages must be copied to the merchant/account, then be downloaded, modified and re-uploaded.

Please refer to the guidelines below to learn when customization is appropriate and when default pages should be used.

2) By default, the HPP pages are placed in the directory 1000; they are available for all merchants when calling a particular operation. The behavior of these pages can be completely or partially overridden:

• if custom pages are uploaded at the account level, they override the merchant’s pages and are available for the account they are uploaded to;
• if custom pages are uploaded at the merchant’s level, they expand the scope automatically to all of that particular merchant’s accounts where no pages are set up;
• if all 5 HTML files are uploaded, then all default pages are overridden. However, if only a few from the whole set are uploaded, for example, 2 of 5, then these 2 override the default pages and the remaining 3 default pages will continue to be used.

Let’s review a typical business scenario as an example of the default pages overriding:


Detailed steps are described in the Advanced Customization via UI section.

Customization Rules

When customizing your hosted payment pages, it is important to follow these rules:

Encoding

Uploaded HTML files must be saved as UTF-8 and encoding within them must be UTF-8 as well. The code within an HTML page will look as follows:

 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 

Adaptive design

• if it is necessary for a page to have an adaptive design, it must include a meta tag with the name=viewport attribute. The code within an HTML page will look as follows:

 
<meta name="viewport" content="width=device-width, initial-scale=1">
 

• if it is necessary to record the fixed length of a table or any other component, it must be done by using the max-width CSS attribute, not the width attribute. A max value for the table length must be indicated. The code within an HTML page will look as follows:

Good example:

 
<table style="max-width: 500px">
 

Bad example:

 
<table width="500px">
 

Convenience Fee

If a merchant wants to collect convenience fees from its customers when processing through HPP, it must have this feature activated within a provider profile. If set, every time when an HPP is rendered, it has a transitional page allowing to calculate convenience fee. The difference between this page and a standard one is that it does not have a field for entering a transaction amount and getting to the next page is available by clicking the Calculate Charges button. On the next page, information about the transaction amount and a charged convenience fee is shown. Further processing through the hosted payment page goes as usual.


Resources

All customization elements, such as images, JS scripts and CSS files, are uploaded to the /resources directory of a merchant/account via the user interface. Note that all resources which are not placed in the /resources directory will not be included in the hosted payment page.


Style URL

If there is a need for a page to contain different designs, depending on which operation is made or which product/service is purchased, it can be performed by applying a dynamic style via style URL. This URL is indicated as a parameter within an API call and can reference either an internal CSS file located on the server, or an external one. It can include a relative path (link to the internal file) or an absolute path (link to the external file). However, usage of the absolute path can be dangerous from a security perspective. For this reason, it can be prohibited from use by enabling the unipay.system.absolute-style-path-allowed system property.


Resource Path

The links to the uploaded files can be indicated as an absolute or relative path. For example:

• Absolute path:

 
<script language="JavaScript" src="https://$UNIPAY/resources/hpp/1000/paypage_card.js"></script>
 
<script language="JavaScript" src="https://$UNIPAY/resources/hpp/$ACCOUNT_ID/profile.js"></script>
 

• Relative path:

 
<script language="JavaScript" src="/resources/hpp/1000/paypage_card.js"></script>
 
<script language="JavaScript" src="/resources/hpp/$ACCOUNT_ID/profile.js"></script>
 

If an absolute path is used, the page can be called from both UniPay and UniBroker. Regardless of the place where the page is called from, it is always rendered on UniPay. In the path to the resources, it is possible to set a domain, where the resources are located. For this purpose, the following variables are used:

• $UNIPAY – when this variable is used, it is replaced with the domain name of the UniPay server. The domain name is taken from the API request.

This means that if a request is submitted to the UniBroker server https://unibroker.your-server.com or UniPay server https://unipay.your-server.com, and the path to the resource is set as https://$UNIPAY/resources/hpp/..., then the path which the resource is referred to will always be https://unipay.your-server.com/resources/hpp/... .

• $UNIBROKER – when this variable is used, it is replaced with the domain name of the UniBroker server. The domain name is taken from the system settings (System perspective => System => Settings => Services => UniBroker).

This means that if a request is submitted to the UniBroker server https://unibroker.your-server.com or UniPay server https://unipay.your-server.com, and the path to the resource is set as https://$UNIBROKER/resources/hpp/..., then the path which the resource is referred to will always be https://unibroker.your-server.com/resources/hpp/... .

• $ACCOUNT_ID - when this variable is used, it is replaced with an identifier of an account, which is a Folder Code (see screenshot). It allows for an account ID to not be revealed in the HTML code of a page. If the directory code is not assigned, it is replaced with the account ID. This identifier is determined by the account used in the API request.

This means that if a path to resources looks like …/resources/$ACCOUNT_ID/profile.js, the resources are taken from the profile of an account indicated in the API request.


Custom fields

If there is a need to submit custom fields to the gateway, then these fields must be preceded by an underscore sign (_). In this scenario, the fields will be submitted and stored to the database. For example, an integrator needs to send a size parameter, which is not present in the API of UniPay. In this case, the parameter must be submitted as _size.

Customization Guidelines

1) In cases where you are going to customize HPPs, it is recommended to define the scope of the necessary changes. This is needed to determine what customization to use - a standard one via the profile.js and/or custom.js scripts, or an advanced one via a change of the physical files. If you have any doubts if you need the advanced customization or simple setup is enough, address the issue to gateway support.

• if it necessary to change labels and add your own text, use profile.js;
• if it is necessary to change validation and drastically re-design the layout of a page, use custom.js. For example, you can add mode10 validation for credit cards.
• if profile.js and custom.js are not enough, use an advanced customization. This may be necessary if you want to drastically change the structure of the pages such as placement of the elements on the form, visual representation, etc. For example, dividing the fields into separate tabs.

2) To keep your paypages stable, we recommend using profile.js. Despite this script being an ordinary JavaScript file, we strongly discourage you from adding any JS scripts that were not initially there.
3) The profile.js includes fields for both card and account transactions. If you are going to perform only transactions of one type (for example, card), don't remove the fields for another one but simply comment this part of the code using the function.
4) There can be cases when advanced customization is needed. Generally, we discourage advanced customization because when it is used, it makes subsequent maintenance of the pages more difficult. Especially, when software updates are deployed.
4) It is not recommended to use external resources, such as JS scripts and images, for the following reasons:

• this can pose a security threat in cases of if a remote server is compromised;
• external resources can be accidentally removed, and as a result, your page will be displayed incorrectly.

5) Do not change the IDs of the components because they are connected with JS scripts and API fields. In cases when a component ID has been changed, the field will not be processed correctly when submitted to the gateway.
6) When customizing a payment page, it is strongly recommended to change only the page layout. Follow this guideline if more comprehensive changes are needed:

• to change a page’s style, use CSS files;
• to submit any parameters that are not a part of the standard API, use custom fields;
• to change a company’s name, logo, etc., use a branding profile.

7) After the JavaScript file has been changed, you can verify if your syntax is correct using a designated validator.

HPP Customization via the User Interface

General Customization via the User Interface

The steps of applying a general customization are as follows:

1) Download a necessary script (profile.js, custom.js, or both) from the merchant 1000 to your computer.



2) Modify the files according to your needs.

3) Go to the user interface and create a directory where HPP files are going to be stored. The directory must be created for a merchant or account with the corresponding to the merchant or account ID.



4) Create the resources directory.



5) Upload the customized files from your computer to the resources directory.



6) Remove HPP files if they are no longer needed using the Remove button on the user interface. Please note that the default payment pages cannot be removed.

7) To verify if the uploaded pages work correctly, submit the API request.

Advanced customization via the User Interface

The steps of applying an advanced customization are as follows:

1) Create a directory where HPP files are going to be stored. The directory must be created for a merchant or account with the corresponding to the merchant or account ID.



2) If the merchant/account is going to use or customize default pages:

• copy default pages
• download them to a local directory on your computer
• modify the HTML files
• re-upload them through the user interface

3) If the merchant/account is going to use its own pages which have already been customized:

• upload the pages through the user interface

4) Create the /resources directory and upload the elements associated with the HPP:

• if the default pages have been copied to the merchant/account, the /resources directory is created automatically;
• if customization is done from the scratch, the directory must be created manually.

5) Remove HPP files if they are no longer needed using the Remove button on the user interface.

6) To verify if the uploaded pages work correctly, submit the API request.

7) For more detailed steps, review this tutorial.

Using the Adobe DTM Analytics Tagging in HPP

Marketing tags on HPP can be used to create analytics triggers, to track events, etc. From a technical perspective, the tag is a java script. The tool that allows you to work with marketing tags is called Adobe Dynamic Tag Management.
The <! - include src = name.js -> tag is included in HPP html code. Every time when the HPP is opened, the code from embedded name.js file is executed. The file name.js should be placed in a predetermined merchant´s directory on the local server (or in default merchant directory). If there is no file there, the tag is skipped. Adobe Dynamic Tag Management mechanism is supported for the following HPPs:

• gift_card.html
• paypage_account.html
• paypage_card.html
• result.html
• tokenization_account.html
• tokenization_card.html

Error Messages

There may be cases when an integrated platform needs to implement their own error messages, which a customer sees when performing transactions through the hosted payment page. For this purpose, the error message override mechanism is used. To learn about the mechanism review this section of the guide.

Error Messages Overriding

There can be cases when an integrator prefers to use their own error messages instead of the gateway-generated ones. For this purpose, the error message overriding mechanism is used. This mechanism works as follows:

• an integrator can override default user messages within the API with the custom messages;
• default user messages are overridden using associated error codes and developer messages, which contain dynamic parameters within the default messages;
• for the real-time API, an integrator can replace default user messages with custom ones using JavaScript in their own application.
• if you need to replace default user messages with custom ones on HPP, the gateway provides the architecture described in the Custom Messages Implementation via HPP section.
• note that only error codes can be overridden using this mechanism.

Custom Messages Implementation via HPP

1) To override the user messages on the payment pages, it is necessary to implement the getUserMessage function in HPP files located in the directory of the corresponding reseller/merchant (for example, /resources/hpp/2000). The function can be either embedded in the payment page or placed in an external JavaScript file that must be connected to the corresponding payment page.