During the use of the features, a few fields have special considerations to be aware of. Here we list those fields, which your application should treat correctly to avoid inconsistencies on requests and responses, guaranteeing the right use of our API.
Every request to and response from Worldnet includes an 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 for each feature 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.
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:
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 their features. A few of them may seem similar, but they can differ in small details.
HASH ALGORITHM AND TERMINAL INTEGRATION SETTINGS
The algorithm used to generate the HASH changed to SHA-512, but for older integrations, the platform still accepts HASH calculated with the MD5 algorithm.
Additionally, there's a configuration which can be used to force the SHA-512 algorithm for a specific terminal in Integration > Force SHA-512 Hashing Algorithm.
In case you are still using the MD5 algorithm and the SHA-512 is not forced in your terminal, the fields used for the HASH remain the same and no separator (as :) is necessary between them.
The card types that your account supports are determined by your Acquiring Bank and your Merchant Account. The options our payment gateway provide are:
All live accounts will be set up with the correct card types enabled as per the documentation that Worldnet receive from your Acquiring Bank.
Please send any amendments to your merchant account to our support team so we may keep your account details up to date.
For testing purposes we recommend using the test card numbers in our Testing Guide - Test Resources document.
The 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.
A Custom Field is set up to be one of three types:
Additionally to that, each Custom Field also defines how it is going to be used:
Each feature is going to give more details 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.
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 the custom fields. If it allows, all you have to do is to add to the request as many custom field tags as you need, using its original NAME at the NAME tag attribute, inform the value you desire, then send the request.
Custom fields size limit is 100 but they will not be rejected if they are bigger than 100, they will be shortened.
Example: registering a Secure Token with custom fields to inform 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 chargeback, saving money!
Our Dynamic Descriptor feature provides this capability to our Merchants.
The text that appears on the Card Holders statements will be composed of:
Not all Acquirer Banks/ Payment Processors allow this feature, so you need to know if your Terminal has the right one configured.
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.
Once you configured a Terminal with Dynamic Descriptors, different possibilities are going to be available, for example:
Case 01
| PROPERTY | VALUE |
|---|---|
| Terminal Name | “Merchant Example” |
| Dynamic Descriptor Prefix | “Order N.” |
| Dynamic Descriptor Default Value | “Purchase at Merchant Example” |
| Interface using the Dynamic Descriptor | Other |
| Associated Custom Field to the Dynamic Descriptor | “Order Number” |
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
| PROPERTY | VALUE |
|---|---|
| Terminal Name | “Merchant Example” |
| Dynamic Descriptor Prefix | “Order N.” |
| Dynamic Descriptor Default Value | “” |
| Interface using the Dynamic Descriptor | Other |
| Associated Custom Field to the Dynamic Descriptor | “Order Number” |
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
| PROPERTY | VALUE |
|---|---|
| Terminal Name | “Merchant Example” |
| Dynamic Descriptor Prefix | “” |
| Dynamic Descriptor Default Value | “” |
| Interface using the Dynamic Descriptor | Other |
| Associated Custom Field to the Dynamic Descriptor | “Order Number” |
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.
Worldnet will inform you if your Terminal ID supports multi-currency. Contact our integration 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:
This feature is a complementary service to other features in HP 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.
Each feature of each integration method is going to present details on how to use it, if available, and all you have to do is make sure the terminal in use has this feature settings enabled at its Security & Fraud section, and that your integration is providing the data necessary for the verification.
Read more about this service is available on the MaxMind website.
This feature is also an additional service to existing features in HP and XML integration methods.
Sentinel Defence provides software as a service (SaaS) technology that profiles online transactions and activities to determine whether they initiate from fraudsters or legitimate customers.
The Payment Gateway accepts or rejects transactions based on the Sentinel Defence's fraud analysis, enhancing the fraud prevention and threat detection for payment transactions on the Worldnet platform.
Each feature of each integration method is going to present details on how to use it, if available, and all you have to do is make sure the terminal in use has this feature settings enabled at its Security & Fraud section, and that your integration is providing the data necessary for the verification.
TERMINAL CONFIGURATION
The terminal used to process the transaction must have the Sentinel Defence feature enabled and configured if you want it use on that transaction or any transaction processed by that terminal.
Transactions returned with “REVIEW”, when using Sentinel Defence, need to be manually reviewed by the Merchants. A new report feature on %Selfcare System, allows Merchants to manually accept transactions marked as REVIEW by Sentinel Defence, and additionally, the XML gateway allows the use of the status update service to change a transaction to “APPROVE” or “REJECT”, depending on the merchant's needs.
Be aware that Transactions with REVIEW status are not going to be settled until it's rejected or approved by the merchant.