Protx Support: VSP Form

Step 1

Step 2

Step 3

Step 4

Handling the Protx encrypted response (decoding/Storing and displaying): Step 4

		Quick Links:

		The fields passed back from Protx and the different responses

		The returned Crypt string

		Decoding the encrypted response

		Success and Failure page

		Storing the additional information

		Displaying the transaction responses

		The email notifications

		Fraud results returned back

The fields passed back from Protx and the different responses:

Once the transaction has been authorised, Protx will respond back to you to with information about the transaction and re-direct the customer to either your success or failure URL.

Appended to the Success URL or Failure URL is an encrypted field, again called Crypt, which contains the status of the transaction, the reference codes for those transactions and the results of the AVS/CV2 fraud checking. The fields and the values which are passed back are as follows:

Name	Format	Values	Comments
Status	Alphanumeric (Max 15 characters)	"OK" - The transaction was authorised by the bank and funds have been taken from the customer "MALFORMED" - Input message was missing fields or badly formatted - normally will only occur during development and vendor integration. "INVALID" - Transaction was not registered because although the POST format was valid, some information supplied was invalid. E.g. incorrect vendor name or currency. "ERROR" - A code-related error occurred which prevented the process from executing successfully. "NOTAUTHED" - The transaction was not authorised by the acquiring bank. No funds could be taken from the card. "REJECTED" - The VSP System rejected the transaction because of the rules you have set on your account. "3DAUTH" - The VSP System rejected the transaction because of the rules you enabled.	If the status is not OK, the StatusDetail field will give more information about the status. Please notify PROTX if a Status report of ERROR is seen, together with your VendorTxCode and the StatusDetail text. 3DAUTH is only returned if 3D-Authentication is available on your account AND the card and card issuer are part of the scheme. A Status of 3DAUTH only returns the StatusDetail, MD, PAReq, 3DSecureStatus and ACSURL fields. The other fields are returned with other Status codes only.
StatusDetail	Alphanumeric (Max 255 characters)	Human-readable text providing extra detail for the Status message	Always check StatusDetail if the Status is not OK.
VendorTxCode	Alphanumeric (Max 40 characters)	Your unique Vendor Transaction Code	Same as sent by your servers to our server in step 2.
VPSTxId	Alphanumeric (Max 38 characters)	Protx ID to uniquely identify the Transaction on our system	You should store this value and quote it to us if you have a query about the transaction. Not present when Status is 3DAUTH.
TxAuthNo	Numeric (Long integer)	The Protx authorisation code (also called VPSAuthCode) for this transaction	Only present if Status is OK.
Amount	Numeric	The total value of the transaction.	Should match that sent in A1. Included to allow non-database driven users to react to the total order value.
AVSCV2	Alphanumeric (Max 50 characters)	Response from AVS and CV2 checks. Will be one of the following: "ALL MATCH", "SECURITY CODE MATCH ONLY", "ADDRESS MATCH ONLY", "NO DATA MATCHES" or "DATA NOT CHECKED"	Should be kept secret from the Customer but stored in your database. Not present when Status is 3DAUTH..
AddressResult	Alphanumeric (Max 20 characters)	"NOTPROVIDED", "NOTCHECKED", "MATCHED", "NOTMATCHED"	The specific result of the checks on the cardholder's address numeric from the AVS/CV2 checks. Not present when Status is 3DAUTH.
PostCodeResult	Alphanumeric (Max 20 characters)	"NOTPROVIDED", "NOTCHECKED", "MATCHED", "NOTMATCHED"	The specific result of the checks on the cardholder's post code numeric from the AVS/CV2 checks. Not present when Status is 3DAUTH.
CV2Result	Alphanumeric (Max 20 characters)	"NOTPROVIDED", "NOTCHECKED", "MATCHED", "NOTMATCHED"	The specific result of the checks on the cardholder's CV2 code from the AVS/CV2 checks. Not present when Status is 3DAUTH.
3DSecureStatus	Alphanumeric (Max 20 characters)	"NOTCHECKED" - No 3D Authentication was attempted for this transaction. Always returned if 3D-Secure is not active on your account. "OK" - The 3D-Authentication step completed successfully. If the Status field is 3DAUTH, this means the card is part of the scheme. If the Status field is OK too, then this indicates that the authorized transaction was also 3D-authenticated and a CAVV will be returned. Liability shift occurs. "NOAUTH" - Returned with a Status of 3DAUTH. This means the card is not in the 3D-Secure scheme. "CANTAUTH" - Returned with a Status of 3DAUTH. This normally means the card Issuer is not part of the scheme. "NOTAUTHED" - The cardholder failed to authenticate themselves with their Issuing Bank. "ATTEMPTONLY" - The cardholder attempted to authenticate themselves but the process did not complete. A CAVV is returned anyway and liability shift occurs for Visa cards only. Check VSP Admin."MALF ORMED","INVALID","ERROR" - These statuses indicate a problem with creating or receiving the 3D-Secure data. These should not occur on the live environment	This field holds the results of the 3D-Authentication steps carried out by VSP Direct and the Protx MPI. If 3D-Secure is not active on your account, this field will always contain the value NOTCHECKED.
CAVV	Alphanumeric (Max 32 characters)	The encoded result code from the 3D-Secure checks. Holds the Visa CAVV or the MasterCard UCAF depending on the card type used in the transaction	Only present if the 3DSecureStatus field is OK AND the Status field is OK.

The returned Crypt string:

The returned crypt string is in the same format as the original string and should contain all the other transaction information in plain text as Name=Value fields separated by '&' characters.

This crypt string would be returned to you encrypted using a Simple XOR algorithm with the pre-registered encryption password provided by Protx and subsequently Base64 encoded to allow safe transport in an HTML form from Protx and would look as follow:

Crypt="b1cZVgcRHDUwLSstXgFBZQsAQApaUnF9SmQOJQxAHycEBkAEWEULOAEwKiYATEwUe2JRdg0QK"

The VSP Form system will append to the Success URL or Failure URL a field called CRYPT, in the manner:

[ResponseURL]?crypt=[encrypted_information]

e.g.

http://www.YourSuccessPage.co.uk/completed.asp?crypt=b1cZVgcRHDUwL
SstXgFBZQsAQApaUnF9SmQOJQxAHycEBkAEWEULOAEwKiYATEwUe2JRdg0QK

If you have passed additional "name=value" pairs to the SuccessURL or FailureURL, such as the customer's name and delivery address and perhaps your own order reference, then these will be appended as extra "name=value" pairs to the Success / Failure URL. When redirection occurs the VSP Form system will append to the SuccessURL or FailureURL not only a field called CRYPT but also the extra "name=value" pairs in the following manner:

[ResponseURL]?CustomerName=protx&DeliveryAddress=London&OrderRef=123abc&crypt=[encrypted_information]

e.g.

http://www.YourSuccessPage.co.uk/completed.asp?CustomerName=protx&DeliveryAddress=London&OrderRef=123abc&crypt=b1cZVgcRHDUwL
SstXgFBZQsAQApaUnF9SmQOJQxAHycEBkAEWEULOAEwKiYATEwUe2JRdg0QK

These additional "name=value" pairs can then be gleaned from from the returned string - please note that the additional "name=value" pairs are subjected to encryption and can be pulled as straight values from the returned string as desired. For more information please click here

Decoding the encrypted response:

This crypt string is decoded in the same manner that your original script was encoded, using the same encryption password (which is unique to your Protx account) and is done within the Completed or Not Completed file provided within the integration kits and would look as follows:

You need to ensure that you do not remove this from the kit or if you are writing your own script then you must enter this coding where you are capturing the returned crypt string. The actual coding for performing the encryption is written within the functions.asp file provided in the integration kits.

The Crypt field contains the plain text as Name=Value fields separated by '&' characters, subsequently encrypted using the simple XOR routine and your pre-registered password, then Base64 encoded. This is exactly the same process your scripts performed at the transaction registration stage. To read the contents, you must Base64 decode the field, then XOR it with your password, then split the contents out into manageable fields. Routines to perform this (Base64Decode, SimpleXOR and GetToken) are included in the kits and can be used in your own script pages.

Once decoded, it would look as follow:

An 'OK' Status

Crypt=Status=OK&VendorTxCode=shuklas-200609141348-60635
&VPSTxId={000000C2-03B6-0001-0000-CD75C9820171}&TxAuthNo=3236348
&Amount=6.99&AVSCV2=ALL MATCH&AddressResult=MATCHED&PostCodeResult=MATCHED
&CV2Result=MATCHED&GiftAid=0

An 'ABORT' Status

Crypt=Status=ABORT&StatusDetail=The Customer ABORTED the transaction by clicking the CANCEL button on the payment
screen.&VendorTxCode= shuklas-200609141348-60635&TxAuthNo=000000&Amount=6.99

IMPORTANT: URL encoding issue when performing decryption

During recent months we have become aware of an important URL encoding issue which is encountered when performing decryption on the returned CRYPT string. When data is passed to our system it needs to be URL encoded, which means that any spaces passed will need to be replaced with a + where necessary (or '%20' depending on the URL encoding used). The problem that we have seen is that when using JSP or PHP (version 4.0 or above) scripting languages only (we have not seen these issue with ASP, ASP.Net nor Coldfusion), any plus characters (+) present in the CRYPT string are being replaced with spaces before you run the decode routine runs on your completion page (either SuccessURL or FailureURL).

In essence our system redirects the user to your SuccessURL / FailureURL with the crypt string attached (with '+' characters replacing any spaces). Your system takes this string, the JSP / PHP is then removing the plus characters and puts the spaces back - Your completion page then tries to decode the string, but it cannot, because it cannot handle the spaces.

The solution to this issue is to add a string replace function to your SuccessURL / FailureURL pages and insert it before the CRYPT string is decoded - this string replace function will basically look for spaces in the CRYPT string and replace any spaces it finds with the '+' character, code examples for this function could be;

PHP: $CRYPT = str_replace(" ","+",$CRYPT)

JSP: sCrypt = sCrypt.replaceAll("[\n\r]", "")

Success and Failure page:

From the response sent back to you within the crypt string, the customer will be re-directed to your SuccessURL (in the event the authorisation was successful), or your FailureURL (in all other circumstances) which you provided within the original crypt string that was sent to register the transaction (See step 2).

Only an "OK" status is sent to your success URL and any other statuses will be sent back to the Failure URL.

You are therefore required to set up the two additional web pages to handle the re-direction of your customer back to your site. Examples of these pages can be found within the integration kits ('completed' and 'notcompleted') which can be downloaded

N.B. In FORM based transactions, Protx cannot guarantee to return the customer to your web site. If the customer closes their browser mid-way through a transaction, or if something goes wrong at any redirect stages e.g. there is a problem with the success and failure URL's then it will be up to you to check the status of the transactions on the VSP Admin reporting screens.

Storing the additional information :

You are not required to store any of the information sent to you in a database, but if you have access to one, you may wish to do so, by simply pulling the information from the crypt string and placing it against the VendorTxCode.
Back to top

Displaying the transaction responses:

You may wish to display some of the information contained in the crypt field to your customer, especially the reason for failure (if authorisation could not be taken). This will need to be added to your failure page to extract this information from the crypt field and displayed. In the following example we can see how the notcompleted page uses a conditional statement to write the appropriate message to the customer when the transaction is not successful.

N.B: The above coding is an ASP example and you will be required to amend and customise the code above in order to write the values into your own database.
Back to top

The email notifications:

Potentially two emails will be sent to the shopper and / or yourself. You and / or the shopper will receive an e-mail notification (if you supplied an email address in the VendorEMail and / or CustomerEMail field within the original crypt string) with all these details along with the information you passed through with the original crypt string.

N.B. Protx cannot guarantee that the e-mail notifications will always arrive, however, since we have no control over what happens to it when it leaves our servers. You should not rely solely on e-mail confirmation, but regularly check your VSP Admin pages for new orders (see later).

The e-mails are sent out via our ISP relay service as HTML and if we are unable to deliver the e-mail the first time for whatever reason, they are held in a queue and we will try to resend it a further 5 times. If they are still undeliverable after that, they are cancelled.

Please check to make sure you are not using spam software that might be blocking our emails. If HTML emails are an issue for your email client, you can change them to be sent out in plain text in your Protx VSP Admin reports pages. (Log in with your User account, go to the 'Administration' button, choose 'Account Parameters', and at the bottom of this section, labeled 'Display and Mail Settings', and where is says : 'Send HTML e-mails', un-tick the tick box and they will go out as plain text.)

The Confirmation E-mail to the Customers will look like this:

You cannot customise the format of confirmation e-mails. You are able to have your Company logo placed onto the top left of the E-mail. You can also pass a Description field or an E-mail content field to inform your customer's as to what they have purchased. Finally, you can state at the bottom of the e-mail the address that your Customers need reply to if they have any queries.

Please note, Protx cannot guarantee Confirmation E-mails will be delivered as we cannot control recipient's Email Spamming filters or the Internet in general.

If you do not receive this, Protx are unable to re-send them as we do not store confirmation e-mails on our database.

We cannot stress the importance of NOT relying on confirmation e-mails to confirm a transaction. It is strongly recommended that you log into your Protx Admin area at the end of each day to view all transactions that have gone through our system from your website.

Fraud results returned back:

When a transaction has been successfully authorised, the crypt string will contain information regarding the AVS/CV2 result. This is, however, for information purposes allowing you display this information upon your success or Failure page.

With VSP Form, you are unable to set your own rule bases and this can only be done within the VSP admin area. More information about fraud screening and rule bases can be found in the downloads section of the website.