Real Time (HTTPs) APIs

A token generated by the gateway is comprised of 3 logical parts:

• two-letter account type (see possible values for more information);
• tokenized account number;
• the last 4 digits of the actual account number.

For example, a card number 4111111111111111 will be tokenized as VC84632147254611111111, where:

• VC is the Visa account type;
• 8463214725461111 is a tokenized account number;
• 1111 are the last 4 digits of the actual card number.

This structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.

Convenience fee is a transaction that represents a charge in addition to the original transaction amount for a convenience usage service for credit card payments, which in most cases is a surcharge, that generally is kept by the service provider that facilitates the payment (payment gateway, processor, etc).

Processing of a sale with convenience fee occurs in two phases:

1. Calculating of convenience fee amount;
2. Submitting of sale/sale-auth transaction with retrieved convenience fee value.

The process of obtaining and submitting convenience fee value via API occurs in the following way:
1. The respective request for convenience-fee calculation is submitted: 2. Once the response is retrieved, feeAmount value needs to be extracted from the response: 3. Sale and sale-auth transactions with convenience fee are available only if a cardholder's has approved the transaction to be made.
To process a sale/sale-auth transaction with convenience fee included, feeAmount value is added additionally to the total amount of the transaction in the respective request:
When convenience-fee is involved, the sale through HPP becomes a two-phase process:

• calculation of the convenience-fee - initially, the HPP is rendered to capture all the necessary payment information. When the HPP is processed, the convenience-fee operation is called and the convenience fee itself is calculated.
• processing of the transaction - the HPP is re-rendered with the information already entered by the customer (in the previous phase) and with the convenience-fee, visible as a separate field, and, also, added to the total amount of the transaction. At this point, a card holder has an option of either accepting the payment with either convenience-fee and completing the sale, or canceling the entire transaction.

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.

UniCharge 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.

HPP can handle both card-present and card-not-present transactions. When a card-present transaction is desired, regular or encrypting MSR can be used.

HPP supports two modes of card-present transactions handling:

• Automatic mode. After the page is loaded, a cursor must be placed in the account number field (setting focus to the field). At this point, the card can be swiped (the system will automatically differentiate between account number, keyed into the page itself, swiped account data or manually keyed card data using MSR). Once the swipe is made and account data from the card is successfully read, HPP is going to automatically recognize the end of the account data, parse it and populate the values into the appropriated fields.
• Manual mode. After the page is loaded, a user must press «Scan» button on the HPP to enable capture of the information from the MSR. Once pressed, the label of the «Scan» button is changed to «Stop» and the reading process begins. The card can be swiped at that time (the system will automatically differentiate between swiped account data and card data, manually keyed using MSR). User can press «Stop» button to pause the reading process (for example, if some other input from the keyboard is required). Once the swipe is made and account data from the card is successfully read, the reading process paused automatically and the label of the «Stop» button is changed back to «Scan». No further input from the MSR will be captured until «Scan» button is pressed again.

Please note, that MSR must be configured to work in Keyboard Emulation mode (normally enhanced by default). To check if Keyboard Emulation mode is enabled, please, open Notepad and make a swipe.

For additional information on configuration of MSR ID TECH SecureKey M series please see ID TECH Configuration Guide.

Overview

Traditionally, to take an application out of PCI scope, payment pages are used. However, there are cases when use of the payment pages is feasible or not desirable (for example, if the application, which needs to accept credit cards, uses AJAX-based interface or wants to utilize its own payment form). For such cases, an alternative JavaScript-based solution is available.

Proxynization API is the JavaScript library that can be embedded in an existing locally hosted payment page; proper usage of proxynization API keeps the payment page and its underlying application out of PCI scope.

The following steps should be taken to utilize proxynization functionality:

• Download api.proxynization.js script and include it in your HTML page. Note that no additional settings including the user interface or server configuration are needed;
• Use authentication request to receive a temporary password, which is valid for 10 minutes;
• Submit the proxynization request with previously received temporary password to get a proxy number;
• Use received proxy number for subsequent sale, credit and tokenization requests to the gateway.

See Workflow section below for more information.

Security constraint

JavaScript by its nature has a security limitation. Since it is client-side language, its source code is entirely accessible. Therefore, it is impossible to secure passwords within JavaScript. Consequently, no JavaScript call can be used to invoke a gateway operation (such as sale or tokenization request) because it is impossible to properly authenticate the caller.
To keep an application out of scope, JavaScript is used to generate a temporary token (proxy), which functions as a replacement for the actual account number. This proxy can be subsequently used in the server-side call to the gateway, utilizing appropriate credentials (which are secured, because everything happens at the server side).

In order to secure the script, temporary password key can be generated using server-side call and should then be assigned to proxynization API object to enable processing.

Workflow

1. Download api.proxynization.js script.
You can either download a default script and customize it using data associated with your server or contact gateway support to request a script that has already been adjusted to your needs.
If you have your own script, skip this step and proceed to step 2.
2. Include api.proxynization.js.
Copy the following lines and paste them to your HTML page. This will enable the proxynization functionality within your application.

 
<script type =" text/javascript" src="https://[server-name]/services/api.proxynization.js"></ script>
 

3. Implement the callback function.
Callback function is going to be invoked once proxynization response is returned from the gateway. The gateway generates a function call, which invokes the pre-defined callback function and passes the proxynization results into it. Post-proxynization logic (such as submission of the form) should be included in the callback function.

The function must declare three parameters: responseCode, responseMessage and proxyNumber:

• responseCode - gateway generated response code. Possible values are listed in the table.
• responseMessage - gateway generated response message, associated with the responseCode value. Possible values are listed in the table.
• proxyNumber - gateway generated temporary proxy number.

Example of callback function is provided below:

 
function clientCallback(responseCode, responseMessage, proxyNumber){
	if(responseCode == "A01"){
		document.getElementById('accountNumber').value = proxyNumber;
		paymentForm.submit();
	} else{
		alert(responseMessage);
		return false;	}}
 

4. Implement the authentication (see integration notes) logic.
Obtain temporary password from the gateway and assign it to the ProxynizationAPI object. To obtain the temporary password, submit authentication request, using your credentials: https://[server-name]/gates/xurl?requestType=authentication&userName=*****&password=*****&contextType=proxynization
Example of the server-side code is provided below:

 
ProxynizationAPI.password = '<?php echo (getPass()); ?>';
 

Example of the final JavaScript code is provided below:

 
(ProxynizationAPI.password = '7e850d1d-0f94-4281-92f9-2c2c8bc8f70e';) 
 

Note that temporary password (such as 7e850d1d-0f94-4281-92f9-2c2c8bc8f70e) is dynamically obtained from the gateway every time when the page is refreshed. It is valid for 10 minutes and can be used only once.
5. Implement the proxynization call.
Proxy number of the card can be retrieved in either of two ways:

1) Payment form implementation.
For this purpose, implement the payment form and insert a proxynization call within form's submit action.
process() function takes two parameters:

• The first parameter can either be the value of account number, or it can be ID of the component, from which the value can be obtained. If the value of the parameter starts with a hashtag (#) symbol, the first parameter is assumed to be the ID of the component. If a hashtag is not present, the first parameter is assumed to be an account number;
• The second parameter is the name of the callback function (previously implemented, see step 2), that will be called when proxynization call is completed.

Example of the proxynization call is provided below:

 
<input type="button" onClick=
"ProxynizationAPI.process('#accountNumber','clientCallback');"/>
 

2) Proxynization API call submission.
For this purpose, submit the proxynization API call with the temporary password obtained in step 4:
https://[server-name]/services/proxynization?accountNumber=4111111111111111&userName=myUsername&password=7e850d1d-0f94-4281-92f9-2c2c8bc8f70e&contextType=proxynization
Proxynization call will return the proxy number of the card.
responseCode= A01, responseMessage=Approved, accountNumber=09ae55d5-8428-4274-ace7-21bcdd704390

How to use received proxy number

Proxynization call is used to retrieve proxy number of the card. This proxy number is valid for 10 minutes and can be used subsequently for sale, credit and tokenization requests to the gateway. See the following link to review an example of the sale request with proxy number. There are no limits for the number of times that the proxy value can be used within 10 minutes, and it can be used even if previous transaction attempts failed.
The proxy value should be submitted within the accountNumber field. To indicate that the proxy number is specified within the accountNumber field, its value should be preceded by an asterisk (*).

Split payments mechanism allows merchants to split a fixed amount or a percentage of the payments between up to 9 different third parties (10 with the original merchant included).

Split scenario should be specified within an original transaction. There are 2 possible methods to create a split payment on a transaction:

• to embed the rules directly into the transaction via the splits parameter, which is allowed to be used in real-time API transactions only;
• to use predefined rules called a split schema, which is a template with a set of predefined split payouts. The template is primarily used in situations when the same split rules are repeatedly used or batch processing is required; a split schema should be created in advance.

Directly embedding the split rules within a transaction allows the split rules to be customized for each payment at both the total transaction or specific items within a transaction level. In order to create a split transaction, the splits field should be included in the sale API call. The splits field is formatted as follows: splits=(accountID=*affiliate001;amount=100), where

• accountID is either internal or external identifier of the affiliate (see Reference Field Type for more information). The submitted value can be either account ID/code or merchant ID/code. If merchantId or merchantCode value is submitted, the system will automatically use the first account under this merchant for further transaction processing.
• amount is the amount to be transferred to this affiliate The amount field can either be a fixed amount or a percentage. See integration notes for more information about amount field.

For cases when multiple items are included in a single transaction, you can apply either the split scenario to the overall transaction or a unique split scenario to each of the items within the transaction. The items field with splits subrecord included can be used to apply different split rules to each item in a single transaction. An item plays either an informational or functional role within the transaction request. When an item plays an informational role, the transaction can include one or more items and the split payment scenario is applied to the transaction as a whole, the total of all the items in the sale transaction. When an item plays a functional role, the transaction can include one or more items and each item specified in the transaction has its own split payment scenario applied to it.

In accordance with NACHA ‘WEB Debit Account Validation Rule’, an ACH account should be validated prior to its first use and before any change to the account number. To do so, there are two ways to use account-verification operation.

• If a given bank account needs to be stored for subsequent processing such as a part of recurring billing it is recommended to validate it before storing it or tokenizing it by using account-verification operation.
• If there is an immediate need to process a transaction and there is no certainty that the account was previously validate it, it is possible to use ‘isVerificationEnabled’ flag included in sale request.

At the moment the logic works as follows:

• If isVerificationEnabled=1, the account-verification request is sent automatically before the sale is processed.
• If isVerificationEnabled=0 (default value), no account-verification request is sent, only the sale is processed.

When deciding how often to verify any particular account you should be mindful with the associated costs.