Notes for Server ASP Integration kit
- ASP
Your web server must have the ability to run classic ASP under IIS4 or higher.
- Windows HTTP Component WinHTTP 5.1
This implementation of Sage Pay Server relies on the Windows HTTP Component WinHTTP 5.1. WinHTTP 5.1 is included in the following operating systems:
- Microsoft Windows Server 2003 family,
- Microsoft Windows XP, Service Pack 1, and
- Microsoft Windows 2000, Service Pack 3 (except Datacenter Server)
WinHTTP 5.1 runs on
- Windows XP,
- Windows 2000, and
- Windows NT 4.0 with Microsoft Internet Explorer 5.01 or later.
If you run any of these Microsoft families, it is recommended that you upgrade to the latest appropriate service pack and secure any externally visible servers with firewalls, intrusion prevention and anti-virus packages.
- MySQL and the MySQL ODBC Connector
This kit builds an example database for you, and stores all relevant details about your orders and transactions. It is designed to run almost out-of-the-box using MySQL (a freeware and increasingly powerful database available at http://www.mysql.com).
This kit was developed used MySQL version 5.0.41, available here: http://dev.mysql.com/downloads/mysql/5.0.html
and the
MySQL ODBC Connector version 3.51.15, available here: http://dev.mysql.com/downloads/connector/odbc/3.51.html
If you download these files, the instructions below will walk you through setting up the database server first. It is extremely lightweight, so will not put too much load on your development box.
If you wish to use any other SQL comatible database, you should be able to do so with minimal changes. You will just need to replicate the table structures shown at the end of this readme.
- Sage Pay MD5 Hash Component
The kit comes with a Sage Pay Windows COM object
called MD5Hash.DLL. This needs to be installed on your test and live envrionments to handle the validation of POSTs being sent to your system from the Sage Pay Servers. Instructions for the installation are given below, but if your live servers are hosted by a third party, you may need to check that you are allowed to install COM objects on your server. We recommend you talk to them before you spend time developing the Sage Pay Server integration. They can contact Sage Pay if they have concerns about the COM object or require more information.
- The kit will unzip to a folder called SagePayServerKit. You can place this anywhere on your server, but we recommend keeping the paths simple by installing it on the root of your data drive (e.g. C:\SagePayServerKit or D:\SagePayServerKit).
- Once that is unzipped, install MySQL as follows:
- Run the MySQL installation file
- Choose custom and change the installation folder to c:\MySQL5.
- Then click through to remaining install screens with no changes
- In the Enterprise pop ups, just click next, then leave the Configure the "MySQLServer now" box checked and click Finish.
- In the config wizard click Next
- Select Standard Configuration and click Next again
- Check both "Install as Windows Service" and "Include Bin Directory in Windows PATH" and click Next
- Set a Root password (we recommend a strong password including upper and lower case letters and number, at least 8 characters long) and select no root access remotely and No Anonymous account. Then click next
- Click Execute. (You may need to enable port 3306 on your Windows firewall to complete this step. See your system administrator if you need help with this.)
- Now open a command prompt (Start->Run and enter "cmd" and click OK)
- Type mysqladmin -u root -p create sagepay and hit return
- Enter your root password when prompted (as set during installation).
- This creates a database called “sagepay"
- Type mysql -u root -p sagepay and enter your root password when prompted.
- This connects to the new sagepay database and logs you in.
- Think of a password for user level access (the password to be used by you web application), and create a sagepay database user called sagepayUser by typing the following:
grant usage on *.* to sagepayUser@localhost identified by '[password]';
replacing [password] with your user password. e.g. grant usage on *.* to sagepayUser@localhost identified by 'ILoveCheese';
NB: Passwords are case sensitive! (and don’t use this ILoveCheese example!)
- Now grant that user the rights to select, insert, update and delete tables by typing the following:
grant select,insert,update,delete on sagepay.* to sagepayUser@localhost;
- Now you can create the tables to hold all the information we’ll be storing and retrieving when using the kits. We’ve provided a script for you called MySQLTables.sql . At the mysql command prompt type:
\. [kitpath]\MySQLTables.sql
So by if you’ve installed the kit in the default folder, it would be: \. C:\SagePayServerKit\MySQLTables.sql
- You can ensure the product data is present by entering the command:
SELECT * FROM tblProducts;
- You should see three DVD titles listed, with their prices.
- Now exit out of MySQL by typing \q at the mysql prompt.
- Run the MySQLODBC installer.
- Select Typical setup, click Next
- Now click Install.
- MySQL and the ODBC connector setup is now complete.
- The Sage Pay MD5 Hashing component should now be installed.
- In the Command prompt window enter the following command:
regsvr32 [Full Path To Kit]\MD5Hash.dll
so if you've installed in the default folder, the command would be:
regsvr32 C:\SagePayServerKit\MD5Hash.dll
- A dialog box should pop up stating that registration has succeeded.
- Ensure that the user under which the web server is running has READ and EXECUTE permissions to the folder in which the kit is installed. Grant those permissions using Windows Explorer.
- If you cannot resolve this issue, please e-mail [email protected] (including your Sage Pay Vendor Name and details of your installation environment).
- Now create a virtual directory in your local IIS to point to the kit.
Windows XP and 2003 users
- Open Administrative Tools->Internet Information Services.
- Drill down into the Web Sites folder to find your Default Web Site.
- Right click it and select New->Virtual Directory
- Click Next in the dialog.
- Enter the Alias SagePayServerKit and click Next.
- Browse to c:\SagePayServerKit (or wherever you installed the kit). Click OK.
- Click Next
- Ensure Read, Run and Execute are selected, then click Next.
- Click Finish. The list of pages should appear in the right hand column.
- Right click and go to Properties, select the Documents tab and remove all pages.
- Then click Add and enter welcome.asp.
- Click OK
- Then close the properties dialog with OK.
Windows Vista Users
- Open Administrative Tools->Internet Information Services (IIS) Manager
- Drill down into the Web Sites folder to find Default Web Site.
- Right click it and select Add Virtual Directory
- Enter the Alias SagePayServerKit and the in the Path, browse to c:\SagePayServerKit (or wherever you installed the kit). Click OK
- Select the SagePayServerKit directory and in Features View, double click Default Document.
- Delete all entries and enter welcome.asp . Click Apply in the right hand column.
- Open the includes.asp file in your preferred web development system, or a plain text editor if you do not have one.
- At the top of the file is a section labelled “Values for you to update”
- Edit the strDatabasePassword value and enter the sagepayUser password you chose when setting up the database above.
- If you chose not to call your Virtual Directory SagePayServerKit, change the strVirtualDir value to the name of the directory you chose.
- Edit the strYourSiteFQDN to point to the Fully Qualified DNS Name (FQDN) of your site.
Your FQDN must start with http:// (or https:// if it is secured with an SSL certificate) plus the DNS name (e.g. www.sagepay.com).
If you do not have a DNS name, you can use your IP address, but it MUST be the externally facing IP address of your system i.e. an address on which the Sage Pay servers on the other side of you firewalls can call back to.
If in doubt, contact your network Administrator.
NOTE: Do not add the Virtual Directory name to this address. It is done automatically by the kit.
- Edit the strYourSiteInternalFQDN to point to the Fully Qualified DNS Name (FQDN) of your site AS SEEN FROM YOUR DEVELOPMENT MACHINE.
At the end of a Sage Pay Server transaction, the customer is redirected back to the completion page on your site using a client-side browser redirect. On live systems, this page will always be referenced using the strYourSiteFQDN value above. During development and testing, however, it is often the case that the development machine sits behind the same firewall as the server hosting the kit, so your browser might not be able resolve external IPs or dns names.
e.g. Externally your server might have the IP 212.111.32.22, but behind the firewall it may have the IP 192.168.0.99. If your test machine is also on the 192.168.0.n network it may not be able to resolve 212.111.32.22.
Set the strYourSiteInternalFQDN to the internal Fully Qualified Domain Name by which your test machine can reach the server (in the example above you'd use http://192.168.0.99/).
If you are not on the same network as the test server, set this value to the same value as strYourSiteFQDN variable.
- Set strVendorName to your Sage Pay Vendor name, chosen when you set up your account through our online application form, or as issued to you by Sage Pay Technical Support if you did not complete the online form.
- If the default currency through which you accept payments is not UK Sterling (GBP), then change the strCurrency field to the correct 3-digit ISO currency code for your transactions e.g (EUR for Euro, USD for US Dollars). ONLY change this value if the merchant account from your acquiring bank supports that currency.
- If you are a Sage Pay Partner and wish to flag the transactions with your unique partner id then set strPartnerID to your unique partner id.
- Save the changes to the includes.asp file.
- Open a browser and go to http://localhost/SagePayServerKit
- You should see welcome screen. This will confirm the mySQL has been set up correctly and that the virtual directory is also set up correctly. If they have not, you will see and error and will need to modify the settings in the includes.asp file to correct the issue.
(image here)
- The pages themselves contain descriptions of how they work, where the code is located, and how to proceed at each step. They will walk you through a complete payment then allow you to perform back office actions like refunds and repeats if you wish.
- At any stage, you can check the contents of your database by opening a command prompt window, typring: mysql -u sagepayUser -p sagepay and entering your prostUser password when prompted.
- From here can view the orders table with standard SQL commands like SELECT * from tblOrders; etc.
- You can also download Windows based MySQL database tools if the command line is not flexible enough for you (see the http://www.mysql.com web site for more details)
You are free to use and modify the kits as little or as much as you like. Sage Pay support will be able to advise you how to link your web site with Sage Pay Server, and hopefully the example code in this kit will simplify the process for you. You can use the database design we've provided and extend it as you see fit, or replace it with your own if you wish.
As you can appreciate, each web-site implementation is different, so whilst our support teams can help you with the standard, unmodified kit, we cannot support the pages after you've made changes to them. We will, of course, advise as best we can and will do our best to help make the integration as uncomplicated as possible.
If you are not comfortable with coding your own website, or find the kits beyind your level of comfort, we can help by providing a list of integration partners with whom we work, who have a good knowledge of our system and can help with your integration. Please visit http://www.sagepay.com/partners.html to search for a relevant partner.