Notes for Form PHP Integration kit
- BETA RELEASE
This kit is a BETA release. If you come across any integration problems or bugs using this kit please report it to support@sagepay.com
- Please note that this kit was developed and tested on a Windows platform. The kit can however be installed on a Linux platform. For Windows users, it is assumed that you have installed, and are familiar with, Microsoft Internet Information Services version 6.0. For Linux users, it is assumed you have installed, and are familiar with, Apache HTTP Server 2.0 and higher.
- PHP
Your web Form must have the ability to run PHP 5.0 or higher.
Please note that this kit was developed and tested on a Windows platform. The kit can however be installed on a Linux platform.
For Windows users, it is assumed that you have installed, and are familiar with, Microsoft Internet Information Services version 6.0.
For Linux users, it is assumed you have installed, and are familiar with, Apache HTTP Server 2.0 and higher.
- The kit will unzip to a folder called SagePayFormKit. You can run this from anywhere, but we recommend keeping the paths simple by installing it on the root of your data drive for Windows (e.g. C:\SagePayFormKit or D:\SagePayFormKit), or in the root folder specified in the httpd.conf file if running Apache.
Windows XP and 2003 users
- Ensure that the user under which the web Form is running has READ and EXECUTE permissions to the folder in which the kit is installed. Grant those permissions using Windows Explorer.
- Now create a virtual directory in your local IIS to point to the kit.
- 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 SagePayFormKit and click Next.
- Browse to c:\SagePayFormKit (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.php.
- 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 SagePayFormKit and the in the Path, browse to c:\SagePayFormKit (or wherever you installed the kit). Click OK
- Select the SagePayFormKit directory and in Features View, double click Default Document.
- Delete all entries and enter welcome.php . Click Apply in the right hand column.
Linux Users
- Set up a virtual host in Apache where you will run the kit from. To do this, open the httpd.conf file in an editor. At the very bottom of this file is a Virtual Hosts section.
- Add a new virtual host in accordance with your local set-up. For example if you were creating a directory called SagePayFormKit on php:
<VirtualHost 127.0.0.1>
ServerName SagePayFormKit
DocumentRoot /www/htdocs/SagePayFormKit
</VirtualHost>
- Also in the httpd.conf file, add welcome.php as a default document in the <IfModule mod_dir.c> section. For example:
<IfModule mod_dir.c>
DirectoryIndex index.htm index.html index.php default.html welcome.php
</IfModule>
- Ensure that your root folder is accessible to the Apache program. This requires that the folder belongs to a non-privileged user.
- Open the includes.php 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”
- If you chose not to call your Virtual Directory or Alias SagePayFormKit, 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 Form 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.
- 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.
- Set the $strEncryptionPassword to the XOR Encryption password created for you when you set up your simulator account (which was subsequently sent to you in an e-mail), or the password assigned to you by the Sage Pay Support team when your test and/or live account was created. If you do not know your encryption password, e-mail Sage Pay Support to request it.
- 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.
- Set the $strVendorEMail to the address to which you would like order confirmation and failure e-mails to be sent. Sage Pay Form will send a mail for each successful or unsuccessful order to that address, allowing you to be notified of transactions passing through your site. If you do not wish to receive these mails and prefer to check your transaction in My Sage Pay, leave this value as it is.
- 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.php file.
- Open a browser and go to http://localhost/SagePayFormKit
(append the port number you are using to 'localhost' if applicable)
- You should see the welcome screen. This will confirm that the virtual directory is set up correctly. If it is not, you will see and error and will need to modify the settings in the includes.php file to correct the issue.
- 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 process.
- When you have your site working with Simulator, and the Sage Pay Support team have set up a test account for you, you can change the $strConnectTo value in the includes files to TEST. This will point at the Test server and you'll see the true user experience (since this is identical to the Live systems, but without the banks attached).
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 Form, and hopefully the example code in this kit will simplify the process for you.
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.
