General Information
General overview of the Hosted Payment Page concept can be found
here.
According to PCI requirements, it is forbidden to store any card data. If non-tokenized card data is stored within the system or any sensitive data goes through the software system, the company goes under PCI scope and subsequent PCI audit. To avoid having cardholder's data uploaded to the software system, Hosted Payment Page mechanism can be used. When HPP is used, all sensitive data is collected through the page and subsequently converted into a token that can be safely used by the software system for processing. Since the page is hosted by gateway service provider, the software application that uses an HPP remains out of scope.
EON Payments provides a simple and secure mechanism for capturing cardholder’s information using a secure HPP (web page to capture account holder’s information, including credit or debit card numbers). Using HPP, the submitter’s application doesn’t touch sensitive account holder's data, and thus remains outside of the PCI scope. The common fields that HPP captures are card number, expiration date, CSC code and optionally address information. HPP seamlessly integrates into the Real-Time HTTPs API and accommodates all of the parameters supported by it.
HPP-related fields
HPP mechanism makes use of the following parameters that can be provided as part of the sale, sale-auth, credit or tokenization API requests.
- notifyURL – the presence of this parameter triggers the appearance of HPP. If definite URL is specified within the notifyURL field, the result of the transaction is delivered to this URL. For example, the notifyURL page with the transaction result may look as shown on the screenshot.
- postNotifyURL – URL, which is used in conjunction with notifyURL. The result of the transaction is delivered to this URL after the callback with the same information is successfully delivered to notifyURL. The format of the callback to this URL is the same as the one used for notifyURL. You can use this parameter if you need to receive a callback within two different systems.
- cancelURL – URL to which a user gets redirected if he or she decides to terminate transaction without completing.
- returnURL – URL to which a user gets redirected after a transaction is successfully processed.
- returnURLPolicy – defines how returnURL is used when a transaction is completed.
If returnURLPolicy is set as
page, a confirmation page is rendered with specified returnURL. If returnURLPolicy is set as
redirect, a user is redirected to the specified returnURL bypassing confirmation page. If returnURLPolicy is set as
redirect-approval, a user is redirected to the specified returnURL only in case of transaction approval. In case of decline, a user is forwarded to the result page (HPP session closed, no further action allowed).
- styleURL – when dynamic styles are needed, URL of a CSS stylesheet that should be dynamically included in the HPP.
- providerData – used to transfer data from the provider that has been received on HPP. It is required to process transactions via PayPal.
- theme – indicates which color theme will be used.
- pageFormat – defines what stages are shown on the hosted payment page.
- isEmbedded – indicates whether header and footer of the hosted payment page are shown within the page.
There are situations when a notify URL fails to reach a merchant system. In such cases, it does not try to reach it again. The information about a failed attempt can be retrieved within the system logs only. However, an information about failed transactions can still be retrieved traditionally via the user interface or a transaction export report.
Additionally, the HPP mechanism allows a user to control the source of notifyURL parameter. It can be pulled from the value specified either within an API request or on the user interface. On the UI, there are two URLs that are stored within the merchant profile in the system and can be used for callback purposes. If notifyURL value should be taken from the API request, it is submitted as it is. If the value of notifyURL should be taken from one of URLs specified in the processing settings of the merchant, the following values preceded by tilde (~) should be submitted:
offline-url – to submit URL used for offline transactions, or
chargeback-url – to submit URL used for returns or chargebacks receiving, e.g.: notifyURL=~offline-url or notifyURL=~chargeback-url.
When cancelURL is used, the HPP is going to have the cancellation option available (cancel transaction button). By default, if a user clicks on the cancel button, he or she will be redirected to the URL, specified within the cancelURL field. Additionally, if the keyword
page is specified as cancelURL field value, then if the customer clicks on the cancel button, he or she will be redirected to the confirmation page (results.html), which will indicate that the transaction was cancelled.
HPP Rendering
There are two ways in which an HPP can be rendered:
1) By generating a payment page via an API call. The most typical way, in which a transaction is processed, is as follows:
- a user initiates a sale, sale-auth, credit or tokenization transaction;
- a software platform submits an API request specifying the value of the notifyURL field to the gateway. This field triggers rendering of a hosted payment page. Additionally, returnURL and cancelURL can be submitted along with the notifyURL field;
- the gateway renders a payment page and returns it to the software platform, which forwards it to the user;
- a user enters secure information and clicks "Submit" button. The transaction gets processed and the result is posted to the URL specified in the notifyURL field;
- a confirmation page with “Continue” button is rendered. When clicking on this button, the user gets redirected to the URL specified in the returnURL field;
- if during the process the cardholder clicks "Cancel" button, further transaction processing gets canceled and the user is redirected to the URL specified in the cancelURL field.
To learn how an HPP is rendered for this scenario, review this
diagram.
2) By generating a payment page via a URL. It is used when a payment page has to be rendered solely by the gateway bypassing a software platform:
- a user initiates a sale, sale-auth, credit or tokenization transaction;
- a software platform submits an API request specifying the values of the notifyURL and processingMode fields to the gateway. The processingMode has to be set as queue;
- the gateway generates an API response containing a particular requestId and returns it to the software platform;
- after receiving a request ID, the software platform forms the URL and passes it to a user. The URL is formed as follows: https://[server-name]/gates/redirects/r671684f1-5c73-4c3d-96ea-0bee3190497a, where r671684f1-5c73-4c3d-96ea-0bee3190497a is a requestId that was returned within the API response;
- the user receives the URL that is available for 10 minutes and follows it to access the hosted payment page;
- after the HPP has been rendered, the user finishes the transaction following the steps described above.
The time during which the page is available to the user can be extended in two cases:
1) If the authenticate API request is sent with the
requestId received in the previous steps, the time during which the page is available can be extended by 15 minutes up to three times.
Authenticate API request submitted for the fourth time will return an error with the following code/message:
L01 (Username or password is invalid).
2) If the invalid card number is submitted via HPP, you should press “OK” button inside the
Reauthenticate pop-up window to extend the session.
To learn how an HPP is rendered for this scenario, review this
diagram.
Note that if GET request is used in an initial call to render HPP, it is advised to use a temporary password instead of the original one, to prevent caching of a password by the browser. In such cases, a temporary password can be acquired by using authentication request. Please, see the integration notes for more information.
HPP Customization
HPP can be configured by each merchant to reflect look and feel of its website or application and accommodate its specific business needs. There are five resources available for customization: paypage_card.html, tokenization_card.html, paypage_account.html, tokenization_account.html, result.html. Pages with _card are used for card processing and pages with _account are used for processing of direct debit transactions.
- paypage_card.html - used for sale, sale-auth and credit operations done with payment cards.
- tokenization_card.html - used for tokenization operations done with payment cards.
- paypage_account.html - used for sale, sale-auth and credit operations done with bank accounts.
- tokenization_account.html - used for tokenization operations done with bank accounts.
- result.html – a page shown to a user once an operation is successfully completed.
Note that these files have to be saved as UTF-8 with the content encoded in UTF-8 within the file as well.
To include custom scripts in any of the HTML files above, separate JS files have to be used. These scripts must be placed in the /resources folder located in a root folder of a corresponding merchant/account. This should be done via
the user interface. References to the external custom scripts have to be specified as follows:
<script language="JavaScript" src="/resources/hpp/[merchant-id]/[script-name]"/>
For example:
<script language="JavaScript" src="/resources/hpp/2000/paypage_card.js"/>
Customized hosted payment pages can look similar to
this one or
this one.
Customizing the HPP color
You can customize the look and feel of your HPP. If you prefer a color theme different from the default one, you have two options.
1) You can pass the desired color in hex format or specify the name of the color in the "theme" field. The system will generate mono-colored theme for you.
2) If you need a more intricate theme with multiple colors, you can build your own. To do so, follow these steps:
- contact our support team to request a custom theme;
- our support team will provide you with an example of a theme as a CSS template;
- in the CSS template, specify the exact colors you want;
- return the modified CSS template to our support team;
- our support team will upload the file to the server;
- you can use the name of the file without the extension as value of the theme parameter in the call and your custom theme will be applied.