support@protx.com
 
Step 1 Step 2 Step 3 Step 4

VSP Form Custom Integration: Step 1

Capturing information and formatting it ready to send to Protx

(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.)

 
Quick Links:
Capturing Information
Importance of Storing information
Required and Optional fields
Protx Integration Kits
Formatting the shopping basket contents
Customising the Success & Failure URLs ("Name=Value" pairs)
Receiving Confirmation emails




 Capturing Information
 

A payment begins with the shopper ordering goods or services from your site. This process can be as simple as selecting an item from a drop down list, or can involve a large shopping basket containing multiple items with discounts and delivery charges. Your interaction with your shopper is entirely up to you and the VSP Form system puts no requirement on you to collect any specific set of information about your shopper.

However, it is generally a good idea to identify the shopper by name, e-mail address, delivery and billing address, Delivery and Billing Postcode and telephone number and store these details in your session alongside details of the shopper's basket contents or other ordered goods for your own reference. With our VSP Form payment solution YOU ARE NOT REQUIRED TO COLLECT CREDIT OR DEBIT CARD DETAILS as this is all done by Protx.

All your site needs to do is calculate the total cost of the order in whichever currency your site operates and present the user with a confirmation page, summarising their order, containing the transaction detail in an encrypted hidden field (see Step 2) and then redirect your shopper to our secured payment page to enter their payment details.

Back to top


 Importance of Storing information
 


If you do choose to capture additional information about your shopper then we cannot stress how vital it is that you store your transaction information within your database as Protx will not capture this for you. If you do not capture this information, you may have difficulty in knowing what was purchased from your site.

Having a basic database will also allow you to capture and store additional information after the transaction has been completed. If you are unable to do this then we recommend that you use a shopping cart that has already integrated with Protx. Please refer to our carts guide by clicking here

N.B: Protx cannot accept any responsibility/liability for any cart problems or difficulties you encounter should you wish to use a shopping cart as this is external software.

Back to top


 Required / Optional Fields:
 


Prior to re-directing your shopper to our payment page, your server-side script, ideally, will need to build an order confirmation page, displaying the full details of the purchase to the shopper, including their billing and delivery addresses, basket contents, total order value and contact details.

This script will also place a form on that page with the action set to the Protx VSP Form registration page. That form will also contain four hidden fields which are required for the transaction to be processed:


Name Values
VPSProtocol "2.22" in this release
TxType "PAYMENT", "DEFERRED" or "AUTHORISE" More information about the payment types can be found by clicking here
Vendor Vendor Login Name
Crypt All other transaction information encrypted then encoded.


The contents of the crypt field are built by your script which contains sensitive information about that specific transaction such as:
  •  A unique reference to this transaction that you generate (called the VendorTxCode).


  •  Total transaction value and currency.


  •  The URLs of the order Success and Failure pages.


  •  Shopper e-mail address for confirmation e-mails.


  •  Your e-mail address for notification e-mails.


  •  Billing and Delivery Addresses and Post Code.


  •  Basket Contents and a Description of Goods.
There are several compulsory fields which are required in order for us to process the transaction but you can also include other optional information for your reference. The below table lists all the fields which you are required to submit within the crypt field with each transaction:


Name Format Values Comments
 VendorTxCode  Alphanumeric (Max 40 characters)
Vendor Transaction Code

This should be your own reference code to the original transaction.
Amount Numeric (1.00 to 100,000.00)
Amount for the Transaction containing minor digits formatted to 2 decimal places where appropriate

Must be positive and numeric, and may include a decimal place where appropriate. Minor digits should be formatted to two decimal places. e.g. 5.10, or 3.29. Values such as 3.235 and 2.3 will be rejected.
Currency Alphanumeric (3 characters)
Three-letter currency code to ISO 4217 Examples: GBP, EUR and USD

The currency must be supported by one of your VSP merchant accounts or the transaction will be rejected.
Description Alphanumeric (Max 100 characters)
Free text description of goods or services being purchased

The description of goods purchased is displayed in the Administrative screens for your future reference.
SuccessURL Alphanumeric (Max 2000 characters)
Full qualified URL (including http:// or https:// header).

The URL of the page/script to which the user is redirected if the transaction is successfully authorised. You may attach parameters if you wish, but the VSP will also send an encrypted field containing important information appended to this URL (see below).
FailureURL Alphanumeric (Max 2000 characters)
Full qualified URL (including http:// or https:// header).

The URL of the page/script to which the user is redirected if the transaction is successfully authorised. You may attach parameters if you wish, but the VSP will also send an encrypted field containing important information appended to this URL (see below).
Along with the required fields that need to be sent there are also optional fields, for example the Billing Address, Billing Postcode and Shopping Basket Contents.
Optional:
BillingAddress		 Alphanumeric (Max 200 characters)
Free format field for the shopper's Billing Address without the Post/Zip code

If provided this information will populate the Billing Address edit box on the card input screens. This information is required if Address Verification (AVS) is used by your site.
Optional:
BillingPostCode		 Alphanumeric (Max 10 characters)
The Post code or Zip code of the shopper's billing address

If provided this information will populate the Billing Post Code edit box on the card input screens. This information is required if Address Verification (AVS) checks are on.
Optional:
DeliveryAddress		 Alphanumeric (Max 200 characters)
Free format field for the shopper's Delivery Address without the Post/Zip code

This information is not used in AVS checks but is held on the reporting systems for your records.
Optional:
DeliveryPostCode		 Alphanumeric (Max 10 characters)
The Post code or Zip code of the shopper's delivery address

This information is not used in AVS checks but is held on the reporting systems for your records.
Optional:
CustomerName		 Alphanumeric (Max 100 characters)
The name of the shopper.

The shopper's name will appear in the cardholder name box on the payment pages.
Optional:
ContactNumber		 Alphanumeric (Max 20 characters)
The telephone number on which to contact the shopper.

The information is not used in shopper validation at present and is available for reporting purposes only.
Optional:
ContactFax		 Alphanumeric (Max 20 characters)
The fax number on which to contact

The information is not used in shopper validation at present and is available for reporting purposes only.
Optional:
Basket		 Alphanumeric (Max 7500 characters)
Details of the shopping basket. Format of the Basket field can be found here

This field can use to supply details of the shopper's order. Future versions of the system will use this field to supply Line Item detail for purchase cards.
The below table lists all the additional fields which you can submit within the crypt field with each transaction to determine how you wish Protx to handle the transaction and information regarding the email notifications which is sent.
Optional:
CustomerEMail		 Alphanumeric (Max 255 characters)
The shopper's e-mail address

The current version of VSP Server does not send confirmation e-mails (although future version will) to the shopper. This field is provided for your records only.
Optional:
AllowGiftAid		 Flag
0 = No Gift Aid Box displayed (default)
1 = Display Gift Aid Box on payment screen

This flag allows the gift aid acceptance box to appear for this transaction on the payment page. This only appears if your vendor account is Gift Aid enabled.
Optional:
ApplyAVSCV2		 Flag

0 = If AVS/CV2 enabled then check them. If rules apply, use rules. (default)
1 = Force AVS/CV2 checks even if not enabled for the account. If rules apply, use rules.
2 = Force NO AVS/CV2 checks even if enabled on account.
3 = Force AVS/CV2 checks even if not enabled for the account but DON'T apply any rules.

Using this flag you can fine tune the AVS/CV2 checks and rule set you've defined at a transaction level. This is useful in circumstances where direct and trusted shopper contact has been established and you wish to override the default security checks.
Optional:
Apply3DSecure		 Flag

0 = If 3D-Secure checks are possible and rules allow, perform the checks and apply the authorisation rules. (default)
1 = Force 3D-Secure checks for this transaction if possible and apply rules for authorisation.
2 = Do not perform 3D-Secure checks for this transaction and always authorise.
3 = Force 3D-Secure checks for this transaction if possible but ALWAYS obtain an auth code, irrespective of rule base.

Using this flag you can fine tune the 3D Secure checks and rule set you've defined at a transaction level. This is useful in circumstances where direct and trusted shopper contact has been established and you wish to override the default security checks.



Back to top


 Protx Integration Kits
 


If you are performing a custom integration, we recommend that you use one of the integration kits which we provide. These kits include the basic coding required for setting up your site to use with Protx.

N.B: These kits are basic templates which require you to amend and add to the coding in order to customise into your site. They are not a complete cart software package.

Within these integration kits you will find the following files:

  •  submit1
    A simple form that generate a unique transaction code (which you can override if you wish) and allows you to specify an amount, currency and descriptions of goods.


  •  submit2
    A further form to allow you to specify delivery details, e-mail addresses and basket contents.


  •  submit3
    A summary page that illustrates how your final confirmation screen should be constructed. It walks you through creating the FORM fields to POST to Protx, specifically detailing how to build the encrypted CRYPT field.


  •  completedAn example "Payment Successful" page, which illustrates how to read the information in the encrypted field sent back by protx after the transaction completes.


  •  notcompleted
    An example "Payment Failed" page. This illustrates how to determine the reason for payment failure, and how to extract the encrypted information returned by Protx.


  •  functions
    An ASP include file that contains default settings and useful subroutines that perform the encryption/decryption and encoding/decoding.




The files provided above may vary depending on the scripting language you are using, however, all the integration kits will detail how to perform all of the above.

As you can see from this section the ASP VSP Form Kit has been referenced, we also have other kits available in other popular scripting languages. All the other kits still follow exactly the same principles. Please go to Downloads page for the Kits and integration documents.

If you require our Integration guides, please click here

It is suggested that you download both the Integration kit and the Guide on this page.

The Submit 1 and Submit 2 files will deal with capturing the information and formatting it ready to be encrypted and POSTed to Protx.



Submit1

The Submit1 page functions by generating a VendorTxCode and captures the following mandatory fields:
  •  Amount


  •  Currency


  •  Description

These fields are then posted to Submit 1 which will capture the remaining fields for the transaction.



Submit2

This file traps the previous information that you passed from Submit 1. It then allows you to capture other relevant information associated such as:
  •  A shopper Email: CustomerEMail


  •  A shopper Name: CustomerName


  •  A Vendor Email Address: VendorEMail


  •  A Delivery Address: DeliveryAddress


  •  A Delivery Postcode: DeliveryPostCode


  •  A Billing Address: BillingAddress


  •  A Billing PostCode: BillingPostCode


  •  A Contact Number: ContactNumber


  •  A Contact Fax Number: ContactFax


  •  The Gift Aid Option if you are a Registered Charity: AllowGiftAid


  •  An AVS/CV2 RuleBase if you require: ApplyAVSCV2


  •  A 3D Secure RuleBase if Required: Apply3DSecure

All this information collected within these two files are then passed onto the Submit 3 file which then Encrypts the information, see step 2.

You will need to make sure that you follow the above table accordingly when sending the required fields through to Protx. You will need to make sure that the field names are passed exactly as we state (being case sensitive). If you pass the field names in the incorrect case, our system will not recognise what you are trying to send through to Protx.

Make sure you follow the format stated in the above tables correctly for each field you send through to Protx. An example of this would be if you do not pass the Amount field to two decimal places, this would then generate error messages from the Protx system (please refer to our errors page).

Back to top


 Formatting the shopping basket contents
 

As you can see you can also pass over the shopping basket to Protx, this will be shown in the Protx VSP admin area where you will be able to view the items your shopper has bought.

The shopping basket contents can be passed in a single, colon-delimited field, in the following format:
  1.   Number of lines of detail in the basket field
  2.   Item 1 Description
  3.   Quantity of item 1
  4.   Unit cost item 1 without tax
  5.   Tax applied to of item 1
  6.   Cost of Item 1 inc tax
  7.   Total cost of item 1 (Quantity x cost inc tax)
  8.   Item 2 Description
  9.   Quantity of item 2......etc


  10.   Cost of Item inc tax
  11.   Total cost of item


IMPORTANT NOTES:

  •   The line breaks above are included for readability only. No line breaks should be   included; the only separators should be the colons.


  •   The first value "The number of lines of detail in the basket" is NOT the total   number of items ordered, but the total number of rows of basket information. In   the example below there are 6 items ordered, (1 DVD player and 5 DVDs) but the   number of lines of detail is 4 (the DVD player, two lines of DVDs and one line for   delivery)


Would be represented thus:

Items Quantity Item Value Item Tax Item Total Line Total
Pioneer NSDV99 DVD-Surround Sound System
 1 £424.68 £74.32 £499.00 £499.00
Donnie Darko Director's Cut
 3 £11.91 £2.08 £13.99 £41.97
Finding Nemo
 2 £11.05 £1.94 £12.99 £25.98
Delivery
 --- --- --- --- £4.99


Would be represented thus:

4:Pioneer NSDV99 DVD-Surround Sound System:1:£424.68:£74.32:£499.00: £499.00:Donnie Darko Director's Cut:3:£11.91:£2.08:£13.99:£41.97: Finding Nemo:2:£11.05:£1.94:£12.99:£25.98: Delivery:---:---:---:---:£4.99

If you wish to leave a field empty, you must still include the colon. e.g.

DVD Player:1:£199.99:::£199.99


Back to top


 Customising the Success & Failure URLs ("Name=Value" pairs)


If you wish to pass more fields through to Protx that are not stated in the above tables, then you can do so by appending them to the end of the Success and Failure URLs in the form of "Name=Value" pairs.

In a normal redirection process, where no extra values are attached to the Success or Failure URLs, The VSP Form system will append to the SuccessURL or FailureURL a field called CRYPT in the following manner:

[ResponseURL]?crypt=[encrypted_information]

e.g.

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


This returned crypt field will potentially only contain the following "name=value" pairs;

  •  The status of the transaction: Status


  •  More descriptive information about the status: StatusDetail


  •  Confirmation of Transaction Id: VendorTxCode


  •  Unique Protx Id for transaction: VPSTxId


  •  Authorisation Code (if transaction successful): TxAuthNo


  •  Confirmation of transaction amount: Amount


  •  AVSCV2 results: AVSCV2


  •  Individual Address result: AddressResult


  •  Individual PostCode result: PostCodeResult


  •  Individual Security Code (CV2) result: CV2Result


  •  Confirmation of Gift Aid: GiftAid


  •  3D Secure Results: 3DSecureStatus


  •  CAVV value passed back if 3DSecureStatus is OK: CAVV


Therefore if you wish to pass 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 you will need to append these extra "name=value" pairs to the Success / Failure URL upon transaction registration. 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


The Success URL and Failure URL field should point to scripts on your server that extract the information in the crypt field and use it to update your database (if you have one) and/or format an appropriate response page for the shopper. This is not compulsory, however, and you may choose to simply direct shoppers to a static HTML page that ignores the contents of the crypt field.

In such cases, you will need to manually check the VSP Admin report pages to determine if a transaction succeeded or failed. In fact, we recommend you always check the VSP Admin pages before sending any goods just to confirm the status of each transaction. For more information please click here
 
Back to top


 Receiving confirmation emails:


As you use VSP Form, you are able to receive Confirmation E-mails both to yourself as the Vendor and also to your shopper. As stated in the above tables, in order to receive Confirmation E-mails you will need to pass two fields titled "VendorEMail" and "CustomerEMail" (remember these are case sensitive). If you pass Protx valid e-mail addresses within these fields, then our system will always automatically generate and send out a confirmation e-mail.

The two fields are optional; if you do not pass these fields then no confirmation e-mail will be generated. If you wish to use multiple email addresses, you should add them using the: (colon) character as a separator. e.g. myemail@myemail.com:anotheremail@anotheremail.com

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




  •  The Confirmation E-mail to the shoppers 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 shopper's as to what they have purchased.  Finally, you can state at the bottom of the e-mail the address that your shoppers 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.


Once you have captured all the information and formatted it correctly, you will then need to encrypt the sensitive information and POST this to Protx (STEP 2).
Back to top
 

 © Copyright 2008 Protx Limited (a division of Sage (UK) Limited)    Terms of Use | Security Policy | Privacy Policy | General Feedback | Webmaster