support@protx.com
 
Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9

VSP Direct 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 another language 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
 


VSP Direct payment requests are very simple. A payment begins with the shopper ordering goods or services from your site. Your interaction with your shopper is entirely up to you.

When they are ready to pay, you will first collect their name, delivery address, contact details (telephone number, e-mail address and so forth) and perhaps allow them to sign up for quicker purchases in future. You will total the contents of the basket and summarise its contents for them before asking them to continue.

Your scripts should then store everything about the transaction and shopper in your database for future reference. You will NOT need to store any card details unless you wish to because Protx will hold these securely for you.

Next you would present the shopper with a 128-bit SSL secured payment page for them to enter their card and billing address details. The page should contain the following fields;

  •   The Cardholder's Name as it appears on the card
  •   The Card Type (Visa, MasterCard, American Express, etc)
  •   The full Card Number without spaces or other separators
  •   The Start Date (if printed on the card)
  •   The Expiry Date
  •   The Issue Number (for some UK Maestro and Solo cards only)
  •   The Card Verification Value. (called CVV or CV2 value. The extra three digits on   the signature strip of most cards, or the 4 numbers printed on the front of an   American Express card)
  •   The Card Holder's Billing Address, including the Post Code. (if you have not   already asked for it and stored it in your database)

This page is submitted to a script on your server that retrieves and pre-validates those values (checking all fields are present, expiry dates are not in the past, the card number field only contains numbers etc.) before constructing an HTTPS POST containing your own unique reference to the transaction (which should be stored alongside the order details in your database) and the correctly formatted data from your form. This HTTPS POST is sent to the Protx VSP Direct gateway.

Back to top


 Initial Transaction Registration
 


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 Direct 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.

Protx validates the data sent to us, checking that it has come from a valid source and that all required information is present, before creating a transaction in our database to securely hold all the data passed to us, contacting the bank for authorisation and replying to you, in real-time, in the response part of the same HTTPS POST. In practise this takes about 2-3 seconds to complete.

The same script on your server that initiated the POST simply reads the response from that POST to determine whether the transaction was authorised or not. It then updates your database with transaction references value and the authorisation code (where appropriate) before displaying either a completion page to your shopper, or an error page explaining why the payment was not accepted.

The required fields are as per the table below (Appendix A1 : Payment Registration Protocol).

Back to top


 Required Fields - What is the Protocol?
 


A protocol, in reference to computers, 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, let's say 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

Download the VSP Server and Direct Shared Protocols for 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.
CardHolder Alphanumeric (Max 50 characters)
The card holder's name

This should be the name displayed on the card.
CardNumber Alphanumeric (Max 20 characters)
The credit or debit card number with no spaces

The full card number is required.
Optional:
StartDate		 Numeric (4 characters)
The Start date (required for some Switch, Solo and Amex) in MMYY format

The start date MUST be in MMYY format i.e. 0699 for June 1999. No / or - characters should be included.
ExpiryDate Numeric (4 characters)
The Expiry date (required for ALL cards) in MMYY format

The expiry date MUST be in MMYY format i.e. 1206 for December 2006. No / or - characters should be included.
Optional:
IssueNumber		 Numeric (Max 2 characters)
The card Issue Number (some Maestro and Solo cards only)

The issue number MUST be entered EXACTLY as it appears on the card. e.g. some cards have issue number "4" others have "04".
Optional:
CV2		 Numeric (Max 4 characters)

The extra security 3 digits on the signature strip of the card, or the extra 4 digits on the front for American Express Cards

N.B: If AVS/CV2 is ON for your account this field becomes compulsory.
CardType Alphanumeric (Max 15 characters)
"VISA", "MC", "DELTA", "SOLO", "SWITCH", "UKE", "AMEX", "DC" or "JCB"

MC is MasterCard, UKE is Visa Electron. AMEX and DC (DINERS) can only be accepted if you have additional merchant accounts with those acquirers.
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

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

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

This field is provided for your records only.
Optional:
Basket		 Alphanumeric (Max 7500 characters)
See the next section 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:
GiftAidPayment		 Flag
0 = This transaction is not a Gift Aid charitable donation(default)
1 = This payment is a Gift Aid charitable donation and the customer has AGREED to donate the tax.

Only of use if your vendor account is Gift Aid enabled. Setting this field means the customer has ticked abox on your site to indicate they wish to donate the tax. See Gift Aid rules for more details.
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:
ClientIPAddress		 Alphanumeric (Max 15 characters)

The IP address of the client connecting to your server making the payment.

This should be a full IP address which you can obtain from your server scripts. We will attempt to Geolocate the IP address in your reports.
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


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 test-purchase.asp and vsp_purchase.asp. These files deal with the initial transaction registration and the handling of the reply POST from PROTX, respectively. Along with this there are also other files which handle the 3D secure callback process and the registration of Refund, Release and Repeat transactions.


  • includes.asp
    Some common configuration options such as specifying your Vendor Name, etc.


  • callback.asp
    Handles the 3D-Secure callback and send information back to Protx. Used in 3D-Secure transactions only.


  • test-purchase.asp
    Sets parameters for a payment transaction.


  • test-refund.asp
    Sets parameters for a refund transaction.


  • test-release.asp
    Sets parameters for a release transaction.


  • test-repeat.asp
    Sets parameters for a repeat transaction.


  • vsp_purchase.asp
    Contacts Protx to execute a payment transaction.


  • vsp_order_refund.asp
    Contacts Protx to execute a refund transaction.


  • vsp_order_release.asp
    Contacts Protx to execute a release transaction.


  • vsp_order_repeat.asp
    Contacts Protx to execute a repeat transaction.




Other scripting languages

As you can see from this section the ASP VSP Direct 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 it will be far to time consuming to achieve then you would need to consider choosing an already integrated shopping cart with Protx. There are many 'off the shelf' shopping carts available that have already been integrated with Protx , please look at our VSP Direct 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