Installing Select Pro

Select Pro is provided as a jar archive along with some example Java and html files that will constitute a fully-working, if basic, merchant site. Before you are able to make use of any Select Pro facilities you need to set up a working Select server so that Web-Merchant/WM is able to carry out the initialisation of your installation. This process results in the generation of your encryption keys and various other information is copied to your installation. You will then be ready to send transactions to Web-Merchant/WM. The simple merchant site provided in the distribution can then be used as the basis of for your integration with Web-Merchant/WM.

Summary of Installation Process
  1. obtain and install Java Development Kit and Java Servlet Development Kit
  2. obtain and install a servlet server
  3. unpack the Select Pro tar or zip archive
  4. configure the servlet server to run the Select and example servlets
  5. call the SimpleWeb-Merchant/WMServlet to ensure your servlet server is running correctly
  6. ask Web-Merchant/WM support to initialise your installation
  7. configure and run the BuyThis servlet to confirm functioning of the connection to Web-Merchant/WM

The release

Select Pro is provided as a tar or zip archive which unpacks to provide the following directories: You will also have the following directories unpacked from the documentation archive: These directories should be used as the basis for your installation. If necessary files can be moved to other locations as required by your server but we strongly recommend that you retain this directory structure so that we are better able to provide you with support in setting up your installation. In what follows <basedir> refers to the directory that contains these Select Pro directories.

Cryptix

Select Pro makes use of the Cryptix implementation of the Java Cryptography Extensions, version 1.1. This is open-source software that we include with the Select Pro distribution. Note that the currently available version of Cryptix on the Cryptix web site does not work with Select Pro. See http://www.cryptix.org/ for more details on Cryptix, and in particular read the Cryptix General Licence.

Other required software

The following additional software is required in order to run Select Pro: These are available for free download. Note that we cannot guarantee that Select Pro works with later releases of these packages, so ensure that you use the specific release quoted above.

These files can be placed in the lib directory of the Select Pro release alongside the Select and Cryptix jar archives.

Servlet Servers

You will need a server capable of support Java Servlets release 2.0. See http://www.javasoft.com/products/servlet/runners.html for the growing list of suitable servers. We have particular experience with using Apache with the Apache JServ servlet engine and JRun with a variety of commercial web servers but there are many other options.

Configuring Your Servlet Server

These notes give general configuration information but the specifics of how a particular piece of configuration is done will vary from server to server. Be aware that you may not be able to use any example configuration verbatim. We give examples for Apache JServ and for JRun which can be used "as is".

CLASSPATH

The classpath for your servlet server should contain the following:

Note that the full file name of jar files must be given, not just the name of the directory containing the jar file.

If you use the directory structure as provided in the release, unpacked into <basedir>, then the names are as in parentheses above.

Note that some servlet servers may not allow you to add to the CLASSPATH (so far encountered for Java Web Server running as an NT service). In this case you will have to place the release components relative to a directory in the built-in CLASSPATH. The jar files will have to be unpacked into this same directory, retaining the full hierarchy of files. This can be done using Winzip or the jar utility.

For Apache JServ you set the CLASSPATH as follows in your JServ properties file (the file named by ApJServProperties in your Apache configuration file). 

wrapper.bin=<jdk dir>/bin/java
wrapper.classpath=<basedir>/config
wrapper.classpath=<basedir>/java
wrapper.classpath=<basedir>/lib
wrapper.classpath=<basedir>/lib/select.jar
wrapper.classpath=<basedir>/lib/cryptix.jar
wrapper.classpath=<apache jserv dir>/lib/apache-jserv.jar
wrapper.classpath=<jsdk dir>/lib/jsdk.jar
wrapper.classpath=<jdk dir>lib/classes.zip
wrapper.bin.parameters=-Djava.compiler=none
For JRun, you set the CLASSPATH as follows in the jsm-default/properties/jsm.properties file (this has been wrapped for clarity; the data should be entered all on one line): 

java.classpath=<basedir>/config:<basedir>/java
:<basedir>/lib:<basedir>/lib/select.jar
:<basedir>/lib/cryptix.jar:<jsdk dir>/lib/jsdk.jar
:<jdk dir>lib/classes.zip
... plus the standard entries for JRun itself.

Important: you should ensure that you do not use the JSDK-like library servlet.jar supplied with JRun -- it is incomplete and does not work properly. Fetch and use the real JSDK version 2.0 from Sun, jsdk.jar as above.

Servlet configuration

All servlet servers provide some way of mapping a name as used in the URL to a particular Java class. Requesting the URL will then call the Java class to be loaded and executed. Select Pro itself only requires the Select servlet but in order to help you with testing your installation and getting started with an integration we include several other servlets. You will need to install the following:
com.WM.select.merchant.SelectHandler
The Select servlet that will be used by Web-Merchant/WM to communicate with your server. Note that if you call this servlet directly you will see a server error as it only responds to the Web-Merchant/WM Select Protocol (i.e. signed, encrypted requests from Web-Merchant/WM).
examples.SimpleWeb-Merchant/WMServlet
A very simple example servlet that you can use to confirm that you have a working servlet server.
examples.BuyThis
An example of a payment page that creates a purchase token for submission to Web-Merchant/WM. This can form the basis of your integration with Web-Merchant/WM.
examples.CurrTest
A demonstration of Select Pro multi-currency utilities, which then connects to BuyThis for submission of the payment to Web-Merchant/WM.
These servlets are described in more detail later.

For an Apache JServ installation the following lines in a servlets properties file achieve this: 

servlet.select.code=com.WM.select.merchant.SelectHandler
servlet.simple.code=examples.SimpleWeb-Merchant/WMServlet
servlet.buythis.code=examples.BuyThis
servlet.currtest.code=examples.CurrTest
If this properties file is for zone "examples" then a URL of the following form will call the SimpleWeb-Merchant/WMServlet: 

http://<server name>/examples/simple
For JRun the equivalent file is services/jse/properties/servlets.properties and the lines to be added are exactly as above (ie. servlet.<url-alias>.code=<class name>).

Configuring Select Pro

Select Pro requires certain configuration information in order to run. This is set up in the select.properties file, which should be in a directory on your server CLASSPATH. In addition there are other properties files, but these should not be edited.

The Select servlet calls various handlers to deal with different aspects of Select communications with Web-Merchant/WM. The Java classes to use for these handlers are specified in the select.properties file.

Select Handlers

The first two handlers are standard Web-Merchant/WM handlers and must not, in general, be changed. If you have special requirements in the area of initialisation or update then discuss this with us. If you install your own handlers then we cannot be responsible for the results. The third one, for the authorisation call-back, is available for you to configure to your requirements. All of these handlers are extensions of SelectServlet, which automatically handles the signed and encrypted Select protocol. Hence you cannot test them by calling them directly as ordinary servlets. See below for advice on testing your own AuthResponseServlet.
com.WM.select.merchant.Web-Merchant/WMInitHandler
The handler called to initialise your merchant installation. This will cause the generation of your encryption keys and will also copy over certain information from Web-Merchant/WM that is needed by your installation.
com.WM.select.merchant.MerchantUpdateHandler
The handler called to carry out regular updates to your installation. Currently this is the daily update of the exchange rates properties files.
examples.AuthResponseServlet
The handler for the call-back from Web-Merchant/WM when a transaction has been authorised. This class is given as an example but you are free to provide whatever handler you wish, provided it extends SelectServlet.

select.properties

The select.properties file should be in a directory in your servlet server classpath. You will probably need to restart your servlet server to ensure this file is reloaded after changes. The following is an example of a suitable select.properties file: 

basedir=<basedir>
keystore=config/keystore
logdir=logs/select-log
currencyconfig=config
merchantconfig=config
purchaseURL=https://select.WM.com/wcc/purchase
authResult.file=htdocs/authresponse.html
authResult.dump=logs/authresponse.log
security.providerName=Cryptix
security.providerClass=cryptix.provider.Cryptix
servlet.mercInit.code=com.WM.select.merchant.Web-Merchant/WMInitHandler
servlet.mercUpdate.code=com.WM.select.merchant.MerchantUpdateHandler
servlet.authResult.code=examples.AuthResponseServlet
All directories mentioned in this file should exist and be writable by the web server user before you try to initialise your site. The meaning of the items in this file are as follows:
basedir base directory for all the subsequent directories named in this file. Set this to the directory in which you unpacked the Select release for the standard installation. All the following directory locations can be left unchanged, unless you have reasons for wanting to put the information elsewhere. We strongly recommend that you do not change these file and directory locations. We can more easily provide support for you if you use the standard structure.
keystore directory to contain the encryption keys.
logdir directory for logging of all communications to and from Web-Merchant/WM
currencyconfig directory to contain exchange rate information. Regular exchange rate updates will be written to this directory.
merchantconfig directory to contain merchant information required by Select
purchaseURL the URL to which to send payment transactions. You may change this to use a test server at Web-Merchant/WM under certain circumstances, but usually this should be left as it is.
authResult.file path of a file that is sent back as the authorisation response by the AuthResponseServlet provided with this release. If this is not a valid file name then the servlet constructs a standard response. See java/examples/AuthResponseServlet.java for details. This parameter is commented out in the standard select.properties in the distribution.
authResult.dump path of a file to which a brief summary of all authorisation responses will be appended. Included for demonstration purposes only: see java/examples/AuthResponseServlet.java for details. This parameter is commented out in the standard select.properties in the distribution.
security.providerName, security.providerClass Specifies which security provider to use - by default Select Pro uses Cryptix as supplied with the release.
servlets.mercInit.code the class used for initialising your server. You would not normally change this.
servlets.mercUpdate.code the class used for updates to your site (exchange rates and encryption keys). You would not normally change this.
servlets.authResult.code fully qualified name of the class that implements your authorisation response. This has been set to the example authorisation response handler for demonstration purposes.

currency.properties

This file provides various information that Select requires for handling the different currencies. Do not edit this file. It will be subject to occasional automatic updates by Web-Merchant/WM via the same mechanism as exchange rate updates. This file must be in a directory in the servlet server classpath.

cryptix-lib and ijce-lib

These directories contain properties files for the Cryptix library. Do not edit these files. These directories should be in a directory in the servlet server classpath.

Files created by Select

Select creates files in your keystore, logdir and merchant and currency config directories.

keystore directories "wcc" and "merc<instId>" containing encryption keys
logdir dated directories containing timestamped log files of every Select protocol communication with Web-Merchant/WM. These are useful when debugging problems in the link with Web-Merchant/WM.
merchant config file named MerchantInfo.<instId>.properties containing various information to be used by Select
currency config files named MerchantCurrencyConverter.<instId>.properties.YYYY-MM-DD, uploaded to your site every day and containing the exchange rates for the given date

Initialising Select Pro

Before Web-Merchant/WM can communicate with your installation using the Select protocol it must be initialised. This involves a call to your Select servlet to generate and exchange encryption keys and then to set up exchange rate and merchant information files. Once you have confirmed that the SimpleWeb-Merchant/WMServlet works and have set up the select.properties configuration you are ready to try initialisation. Before you ask for this to be done check that all the directories mentioned in select.properties exist and that they are writable by your server. Initialisation will confirm that your installation is correctly configured.

Testing Select Pro

The html page "buythese.html" in the htdocs directory has a couple of example forms that submit to the "BuyThis" servlet on your server. The output from this servlet is a page that contains a suitable "purchase token" and URL parameters for submission to Web-Merchant/WM. You need to edit this page for the location of your BuyThis servlet and for your Select installation id. Ensure that the currencies in the examples are ones that you are registered to use. Change them if necessary. The test mode is set to 100, which means that this transaction will always be successful but will not go to the bank.

If your installation is set up for a merchant server call-back then the servlet set up for authResult will be called during processing of the transaction. You can modify this servlet to carry out whatever processing you wish on the call-back, but for initial confirmation of correct functioning use it as it is.

See Sending a Purchase to Web-Merchant/WM for more details on "BuyThis" and the purchase token.

Multiple Merchants sharing one server

Your Select server can be initialised for multiple merchants, who will all share the same Select servlet but have different installation ids.

Using the default configuration as given above they will also share the same authResult servlet. This may be what you require - this servlet is sent the installation id for any authorisation response and so processing can be carried out as appropriate for that merchant. Alternatively the MerchantInfo file for each merchant can contain a line specifying the servlet.authResult.code, in the same format as in select.properties.

$Revision: 1.7 $