Special Fields and Parameters

When integrating to the gateway, note that several fields have special considerations to be aware of. Those fields are listed here; your application should treat these correctly to avoid inconsistencies on requests and responses.

Every request to and response from the Gateway includes a SHA-512 HASH parameter. This is a security element to ensure that none of the sensitive request or response data has been modified by a “man-in-the-middle” attack. This is achieved by including all the sensitive fields into a string, which varies per request type, along with the Shared Secret, configured per terminal. This string is then used as the basis of an SHA-512 HASH.

When explaining the data structure for requests and responses, our API Specification is going to present in each section the formation rule of its Request HASH and its Response HASH. Those rules are going to look like this:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

The “:” (colon) used in the example above is the separator used to concatenate the elements in a string and it ALWAYS NEEDS TO BE ADDED to define the separation of two elements.

It's important to understand that the separator should only be used to separate two elements with values.

• element[1]value
• element[1]value:element[2]value
• element[1]value:element[2]value:element[n]value

For example, if a HASH rule formation defines an element which your request doesn't have, you can't use the separator for that element.

Consider a HASH for the following data using the structure presented above:

• TERMINALID: 678002
• ORDERID: 300145858
• AMOUNT: 325.56
• DATETIME: 15-3-2006:10:43:01:673
• SECRET: x4n35c32RT

Consider sha512 your method to apply the SHA-512 encryption, which receives the string formed with the data elements separated by the colon.

String hash = sha512("678002:300145858:325.56:15-3-2006:10:43:01:673:x4n35c32RT");

The final hash string variable would have the value of:

5b39821025c33a3c37560196f36af68668e46e82afc4017434d72e62dbc4c06781afc6364e992d5594656fb185c901ece65adf85e8822832b8985f602e533eba

Note that the sha512 method should always use a character encoding of UTF-8, when appropriate, as should all data sent to the payment gateway.

Remember to implement the specific hash rule for each request and response you decide to use from our solutions, exactly as they are described in each section. A few of them may seem similar, but they can differ in small details.

The card types that are supported by the Gateway in the US are:

• VISA
• VISA DEBIT
• MASTERCARD
• DEBIT MASTERCARD
• AMEX
• DINERS
• JCB
• DISCOVER
• CUP SECUREPAY (Requires special setup and pricing)

The card types that are supported by the Gateway in Canada are:

• VISA
• VISA DEBIT
• MASTERCARD
• DEBIT MASTERCARD
• AMEX

Please note that Interac Debit (Canada) is not supported.

For testing purposes we recommend using the test card numbers in our Testing Guide.

The following is a list of currency types supported by the Gateway. Other may be added upon request.

Custom Fields allow you to send data to our systems with transactions in name-value pairs so that it is stored and can be included in reports, receipts and for other uses. There are two different types of custom fields: Explicit and Implicit.

• Explicit Custom Fields: All the custom fields that are mentioned in this document are explicit custom fields, all custom fields in the XML gateway are also. They must be pre-configured in the SelfCare System (Settings → Custom Fields) for the particular Terminal ID that you are using.
• Implicit Custom Fields: Any other fields that are sent to the Hosted Payment Page are considered to be implicit custom fields. These will be returned in the response to the Receipt Page, but will not be stored, sent to the Background Validation URL or available in any reporting features. Implicit custom fields are not supported by the XML gateway.

A Custom Field is set up to be one of three types:

• 1. Boolean: Accepted values are “0”, “1”, “true” or “false”.
• 2. Numeric: Any numeric only value.
• 3. String: Any value containing only alphanumeric characters, spaces or the following characters: '-&*()_+:;@#|.,/

Additionally to that, each Custom Field also defines how it is going to be used:

• 1. Virtual Terminal: defines it can be used on virtual terminal.
• 2. Payment Page: defines it can be used on payment pages.
• 3. Bulk Payment: defines it can be used with bulk payments.
• 4. Subscription: defines it can be used with subscriptions.
• 5. Mandatory: defines that, wherever is used, is mandatory.
• 6. Show on Receipt: defines it should appear on receipts.

More details will be provided in each section about the use of the Custom Fields in their requests and responses, but be aware that the use of a Custom Field is limited by its configuration.

The configuration of Custom Fields involve two main steps: one realized at the Gateway side and another done at the Merchant side.

• 1. Gateway Side: The desired Terminal must be enabled with the Custom Fields feature.
• 2. Merchant Side: The Merchant needs to configure the Terminal settings on the SelfCare System with the list of Custom Fields which should be available for this Terminal, detailing the interfaces in which they should be used (XML, HPP, other) and the language in which that custom field is available for.

In case your application requires to use Custom Fields with Subscriptions, there's still one more configuration step: under the relevant Stored Subscription, the Custom Field needs to be selected.

After that, you can use start using the Custom Fields in your integration, but be sure all the Custom Fields you use are still in place and configured as you expect before putting your integration live.

To use a custom field with a request, first verify if the request you want to use allows custom field. If so, add to the request as many custom field tags as you need, using its original NAME at the NAME tag attribute and then send the request.

Example: registering a Secure Card with custom fields to include the client's loyalty system id (custom field ClientLSID) and the current amount of accumulated points (custom field ClientLSCP).

<SECURECARDREGISTRATION>
    ...
    ...
    <CUSTOMFIELD NAME="ClientLSID">343f34fsg68laocaw</CUSTOMFIELD>
    <CUSTOMFIELD NAME="ClientLSCP">2650</CUSTOMFIELD>
    ...
</SECURECARDREGISTRATION>

Transaction descriptors describe a particular payment transaction in order to help the Card Holder to identify this transaction on his/ her bank statement or online bank interface. It's a good practice which helps Merchants to minimize the risk of chargebacks.

Our Dynamic Descriptor feature provides this capability to our Merchants.

The text that appears on the Card Holders statements will be composed of:

• 1. A Prefix, which is a static text value up to 12 characters long that is the same for every transaction followed by;
• 2. The Dynamic Value, which can be, depending on the terminal settings and the transaction's data: sent in by the website with the transaction, as a Custom Field; adopt the default value defined at the terminal's configuration of the Dynamic Descriptor feature, or; the Terminal Name.

This feature works together with the Custom Field feature and has basically two main steps: one realized at the Gateway side and another done at the Merchant side.

• 1. Gateway Side: The desired Terminal must be enabled with the Dynamic Descriptor feature and optionally it also can have a Dynamic Descriptor Prefix and a Default Value.
• 2. Merchant Side: Optionally, the Merchant can configure the Terminal settings on the SelfCare System pointing out the custom field to be used by each interface (XML, HPP, other) as the value for the Dynamic Descriptor.

Once you configured a Terminal with Dynamic Descriptors, different possibilities are going to be available, for example:

Case 01

If a Transaction is sent to the gateway with a custom field order number “1805000453”, the Card Holder would see in his/ her bank statement the following additional information for the purchase: “Order N * 1234”.

If a Transaction is sent to the gateway with no order number, the Card Holder would see in his/ her bank statement the following additional information for the purchase: “Purchase at Merchant Example”.

Case 02

If a Transaction is sent to the gateway with a custom field order number “1805000453”, the Card Holder would see in his/ her bank statement the following additional information for the purchase: “Order N * 1234”.

If a Transaction is sent to the gateway with no order number, the Card Holder would see in his/ her bank statement the following additional information for the purchase: “Merchant Example”.

Case 03

If a Transaction is sent to the gateway, the Card Holder would see in his/ her bank statement the following additional information for the purchase: “Merchant Example”.

Some Acquiring Banks support Multi-currency Terminals. They allow Merchants processing transactions in one of a number of pre-defined currencies for a Terminal. These Terminals have their own terminal ID and may be identified with the letters ‘MC’ after the terminal ID.

It's important to understand that, when processing transactions with one of those Terminals using an integration, your solution has to consider that the Currency Type must be added to the request HASH calculation and is going to be added to the response HASH calculation. Details on the HASH calculation for requests and responses involving Multi-currency Terminals are provided by each feature when explaining the HASH body field.

We will inform you if your Terminal ID supports multi-currency. Contact our support team if you have any questions relating to multi-currency terminals.

The signature field is used by some of the features' requests, and follows a set of rules to be formed, as such:

• - The SIGNATURE field is a string of characters. Each set of 4 characters represents a point on a 300 pixel wide x 100 pixel tall canvas.
• - Each set of 4 characters is comprised of 2 chars to represent the X value (pixel distance right from left side) and 2 chars to represent the Y value (pixel distance from down from top).
• - Each 2 char value is a base 28 encoded decimal number (similar to hex which is base 16). Possible values for each character are any numerical digit and the letters from “a” to “r” inclusive (“a” = 10, “b”= 11, etc. just like in hex, but up to “r” = 28). For example “3bac” can be calculated as: (3 x 28¹) + (11 x 28⁰) = 84 + 11 = 95 from the left and (10 x 28¹) + (12 x 28⁰) = 280 + 12 = 292 from the top, hence 3bac is a point at 95×292 pixels from the top left.
• - To include a space between 2 points (no line drawn on signature canvas) include a 0x0 point (encoded as “0000”) in the string.
• - Points outside the bounds of the 300×100 pixel canvas will not be rendered, and should not be included.
• - The SIGNATURE string can be a minimum length of 4 characters (1 point) and a maximum of 1600 characters (400 points).
• - The recording canvas should always have a 3:1 width to height ratio.
• - If the canvas that the signature is recorded on is of a larger size, the magnitude of the X and Y values should be scaled down proportionately to a 300×100 boundaries respectively.
• - Example SIGNATURE string: “4i1m621m00005a125a2e” will draw a 40×40 pixel “plus” symbol in the middle of the canvas.

MaxMind MinFraud is a complementary service that works with the HPP and XML integration methods.

When used, this service provides a score for the transaction between 0.01 and 100 (riskScore), effectively the percentage chance that it could be fraudulent.

Certain fields are required for performing fraud scoring on the transaction using the MaxMind MinFraud service. There is no charge for this service, and it can be enabled in the Terminal Setup section of our SelfCare System (Merchant Portal).

To use this service, make sure the terminal in use has this feature enabled and that your integration is providing the data necessary for the verification.