Protx send an HTTPS POST to the Vendor's NotificationURL

(N.B: ALL code examples and references to integration kit files within this document are related
to the ASP kit ONLY. To download kits in other languages please visit the Downloads page.)

The NotificationURL is a value that is supplied to Protx in the initial HTTPS POST
(see VSP Server Custom Integration: Step 2). The NotificationURL is a page resident on your website/server which is set up to handle the response from the Protx VSP system in relation to a transaction. Was the transaction a success? Was it declined? Perhaps somewhere in between - there might have been an error in the process. Whatever the result of the transaction, the VSP system will return this result to your Notification page, hence the name.

This page can have multiple functions or remain quite simple. Ideally the page will take the status that Protx return to it and update the database/shopping cart accordingly. This means that a transaction created at 12.00pm might be logged in your database as 'waiting for response from Protx' and at 12.01pm, once the 'Status' is returned by Protx you can then update the transaction on your database to suggest 'Protx tell us this transaction is now OK'. This would negate a reliance on the VSP Admin area to keep track of the status of a transaction and would allow for you to rely on your own database from where you can see whether the transaction was authorised, declined or otherwise.

The real importance and the ultimate function of the Notification is two fold:

•   Receive and handle the status of the transaction
•   Reply to Protx with a status and a redirect URL

The VSP system has now obtained an authorisation from the bank, received a decline from the bank, or experienced an error.

Protx will return one of the following Status' to your NotificationURL:

•   OK- the bank have authorised the transaction


•   NOTAUTHED- the bank has not authorised the transaction


•   REJECTED- the transaction has been rejected by your Protx rule base


•   ERROR- a technical/communication problem has failed the transaction


•   ABORT- if the Shopper cancelled the transaction on the payment page

The 'vps_handle_protx_response.asp' page is already built to handle the responses listed above and is called the 'NotifcationURL'. It will receive the status from the POST and act accordingly to that status. If the Status is OK then the process will continue on to run the security key and transaction information through the MD5 Hash algorithm (explained below), as per the below screenshot.

The first thing to do, in terms of code, would be to call up your database to retrieve any information about the transaction. You would use the information passed in the POST to establish which transaction you would want information about from your database, importantly the SecurityKey, as below:

Once you have retrieved the relevant information from your database, the next step is to check the integrity of the data that was sent back from Protx using the MD5 Hash algorithm. This is commonly used in applications to check whether data received has not been tampered with. You will achieve this by generating your own MD5 Hash string and comparing this with the MD5 Hash string posted to your notification URL by Protx. The MD5 Hash string we return to you is in a field called VPSSignature. If the VPSSignature and your MD5Hash string do not match (and you have correctly implemented this aspect of the VSP Server integration) then this will suggest that the response returned to your notification URL has been tampered with. To give you an idea, the following is a simplified example of what an MD5 Hash string will look like:

E475BFB404E814FC5DDB382AA864B76F

The above hash string is a MD5 Hash of the word PROTX. It is important to note that the MD5 Hash algorithim is also case sensitive. For example, if we were to use the MD5 Hash algorithem for the word protx in lower case the string will be as follows:

D3F5D2C581D5C25BCE345D8BAD419F97

Therefore, in order to generate an MD5 Hash string to compare with the VPSSignature returned from Protx you need to generate a string with the same fields, in the same order and in the same case that Protx used to generate the VPSSignature. These fields are as follows:

•   VPSTxId
•   VendorTxCode
•   Status
•   TxAuthNo
•   VendorName
•   AVSCV2
•   Security Key
•   AddressResult
•   PostCodeResult
•   CV2Result
•   GiftAid
•   3DSecureStatus
•   CAVV

Like the following example, the values of these fields will be concatenated together in preparation for it to be hashed:

{48B881D2-C2C3-7G33-B12C-E722DBC91D00}PROTX1234OK9191myvendornameALL MATCHDGYTRDSN88MATCHEDMATCHEDMATCHED0OKHBGS765F9HJK23Y9VSW212

N.B: The 3DSecureStatus and the CAVV value will only make up the string if this is a 3D Secure transaction. You will only include values relevant to the transaction.

Note that in the above example the VSP Vendor name is in lower case, this is important as Protx will generate the VPSSignature with your VSP Vendor name in lower case. If you generate a string with the VSP Vendor name in upper case or mixed case, the VPSSignature will not match.

We can look to the ASP integration kit as an example;

In the ASP integration kit we supply an MD5Hash.dll which you will need to register on your server. (Look to 'asp-server-readme.html' that comes with the kit for instructions). As MD5 is a widely-used cryptographic hash function you will find that the method of deployment will depend upon what technology you use to integrate VSP Server. For example, with PHP, the MD5 Hash function is inbuilt so there is no need to install additional components (http://uk.php.net/md5). Here is how we perform the first step in ASP.

On line 44 we can see that an instance of the MD5Hash object is created in order to create a hash string. Then from line 47 to 60 we concatenate all the values required for the MD5Hash and assign them to a variable called message. Some of these values would have been received from the notification Post and some of the values will already be known such as the VSP Vendor Name (which must be in lower case). The SecurityKey and the VPSTxId would have been captured earlier from our response to your transaction registration and stored in a database (VSP Server Custom Integration: Step 2).

The next set will be to use the MD5 Hash object to hash the message. We can see this on line 63 of the above example code as it is assigned to the variable hash. The next step is to compare the MD5 hash string we have generated and assigned to the variable hash with the VPSSignature returned by Protx. We can see this on line 66 where the two values are compared so we can determine whether the transaction has been tampered with and can take the appropriate action.


Common Problems Encountered


If you are having problems getting your MD5Hash string to match with the VPSSignature then you will need to check that you have included all the values in your message before it is hashed. You need to include all values returned by Protx and every character has to be in the same order and in the same case. This is why it is important to not include or remove any additional spaces and also include the VSP Vendor name in lower case. It is also important to note that there are differences between the VSP Simulator and the Test / Live server and the way that they construct the message before generating the VPSSignature. The VSP Simulator will assume that every transaction is a 3D Secure transaction and therefore, will return the 3DSecureStatus and CAVV for every transaction. You will need to make sure that you include the value of these fields when you contruct your string to be hashed. The Test and Live server will only return the 3DSecureStatus and CAVV value if you have 3D Secure enabled on your Protx account.

If a status OTHER than OK is received, the 'vps_handle_protx_response.asp' page is written to handle the alternative responses and passes the Shopper to a relevant page within the Protx kit.

Responses and appropriate pages are below, all pages are provided in the kit and this example is for the ASP KIT ONLY.

If a response is received other than OK and listed above, the user will be redirected to the appropriate page, an example of a 'NOTAUTHED' response is below:

As in the example above, you will see the status received from the POST is 'NOTAUTHED' and the page then constructs a response (covered in a moment) and importantly, redirects the Shopper to the 'defaultNotAuthedURL' which is listed above. Each status other than OK will have a corresponding page within the kit. The way the 'vps_handle_protx_response.asp' page handles the above status in the POST is very similar to the way it will handle any Status that is other than OK.

Once the Status has been received in the POST from Protx your NotificationURL (by default the 'vps_handle_protx_response.asp') will handle that response, and will then get ready to respond back to Protx in the POST.