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

VSP Server Custom Integration: Step 1

Collecting and Formatting the information to POST 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:
Overview
Initial Transaction Registration
Required Fields - What is the Protocol?
Formatting the Basket Contents
Importance of Storing Data
Summary of the Files in the Kit
Is this too much for me?
 




 Overview


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 Server system puts no requirement on you to collect any specific set of information.

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. You should store these details in your session alongside details of the Shopper's basket contents or other ordered goods.

                YOU DO NOT NEED TO COLLECT CREDIT OR DEBIT CARD DETAILS.

All your site needs to do is calculate the total cost of the order in whatever currency your site operates and present the Shopper with a confirmation page, summarising their order. At this stage (before your Shopper is present with the Protx Payment page) your cart has built up the required fields and optional fields for the contents of the POST for the initial transaction registration.

Back to top


 Initial Transaction Registration


Once the Shopper has clicked Continue, a script on your web server will construct a payment registration message (see Appendix A1 below) and POST it via HTTPS to the VSP Server transaction registration URL.

This POST contains your VSP Vendor Name, assigned to you by PROTX when your account is created, and your own unique reference to this payment (in a field called VendorTxCode, which you must ensure is a completely unique value for each transaction).

The message also contains the total value and currency of the payment, and billing address details for the Shopper if you have collected them. You can specify a brief description of the goods bought to appear on the payment screen and optionally provide a URL for the PROTX servers to call you back on once the payment process is complete (this is called the Notification URL).

Because this message is POSTed directly from your servers to ours across a 128-bit encrypted session, no sensitive information is passed via the Shopper's browser, and anyone who attempted to intercept the message would not be able to read it. Using VSP Server you can be assured that the information you send us cannot be tampered with or understood by anyone other than us. Your script sends the payment registration message in the Request object of the HTTPS POST and the response from our server is in real time in the Response object of the same POST.

Back to top


 Required Fields - What is the Protocol?


A protocol, in reference to IT Technology, is a set of rules governing the format of messages that are exchanged between computers. This means that certain information must be provided and in a certain format, all viewable in the Protx Protocol.

To successfully create a transaction, for example, 8 key pieces of information must be collected on your website and securely passed to Protx. Some of those pieces of information will have limitations in terms of format. Perhaps they must be numeric, or alpha characters only and may have maximum and minimum lengths.

Providing the protocol is followed strictly, there will then be no reason why the transaction would be failed for erroneous or malformed submission reasons.


Appendix A1 : Payment Registration Protocol

Name Format Values Comments
VPSProtocol Alphanumeric (Fixed 4 characters)
2.22 in this release

Default or incorrect value is taken to be 2.00
TxType Alphanumeric (Max 15 characters)
PAYMENT / DEFERRED or PREAUTH

See companion document VSP Server and Direct Shared Protocols other transaction types (such as Refund, Releases, Aborts and Repeats).
Vendor Alphanumeric (Max 15 characters)
Vendor Login Name

Used to authenticate your site. This should contain the VSP Vendor Name supplied by Protx when your account was created.
 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.
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:
NotificationURL		 Alphanumeric (Max 255 characters)
Full qualified URL (including http:// header). The NotificationURL must be an HTTP and NOT an HTTPS URL

Callback URL to which Notification POSTs are sent. If the NotificationURL is not provided, the VSP will send the response to the default URL in the Vendor records set up when your account was created.
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:
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:
Basket		 Alphanumeric (Max 7500 characters)
See the next page for the Format of the Basket field

This field can be used 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.
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


 Formatting the 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 n inc tax
  11.   Total cost of item n


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


Which 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


 Importance of Storing Data


We cannot stress how vital it is that you store your transaction information within your database (VPSTxId, VendorTxCode and security key) along with other Shopper details, not only does this allow you to track shopper information but you can automate more than just payments. VSP Direct and VSP Server place you in control of your transactions. Because you will have your own secure database servers and web servers on which you store details of your Shoppers and their transactions, you may well wish to automate many of the daily procedures, such as RELEASING and ABORTING DEFERRED transactions, REPEATING regular payments or issuing REFUNDS to Shoppers.

Back to top


 Summary of the Files in the Kit


The files that drive the Purchasing process and require the most modification are vps_order_purchase.asp and vps_handle_protx_response.asp. These files deal with the initial transaction registration and the processing of the callback from PROTX, respectively. Along with this there are also other files which handle the responses back from Protx for example, ABORTED or REJECTED transactions.


  • includes.ini
    Some common functions used by the kit. You should NEVER need to edit this file.


  • protx.ini
    This contains lots of settings which you will need to tailor for your own site, including your company name, server IP, transaction currency, internal paths etc.


  • your_site.ini
    A place to add your own settings.


  • vps_handle_protx_repsonse.asp
    The script which deals verifies order details with the protx server.


  • vps_order_purchase.asp
    Sends initial order details to protx and acts appropriately according to the response - either redirecting to protx or giving an error.


  • vps_order_abort.asp
    The page to which a Shopper will be redirected if their order is aborted while on the protx site.


  • vps_order_complete.asp
    The page to which a Shopper will be redirected from the protx site when an order has been successfuly completed.


  • vps_order_error.asp
    The page to which a Shopper will be redirected from the protx site if an error occurs within protx itself. This should never be used, but it is worth having in place just in case.


  • vps_order_notauthed.asp
    The page to which a Shopper will be redirected from the protx site if their order is rejected by the bank.


  • vps_order_rejected.asp
    The page to which a Shopper will be redirected from the protx site if their order is rejected by Protx.


  • vps_order_tamper.asp
    The page to which a Shopper will be redirected from the protx site if their order is discovered to have been tampered with.




Other scripting languages

As you can see from this section the ASP VSP Server 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.

Back to top


 Is this too much for me?



IMPORTANT

At this initial stage, If you feel that you cannot carry out any of the above or far to time consuming to achieve then you would need to look away from a custom integration and choose an already integrated shopping cart with Protx there are many 'off the shelf' shopping carts available that have been integrated with Protx , please look at our VSP Server Shopping Carts section.

Back to top

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