Integrator's Information
TopShopper Classic, Version 2.0

Contents

	1. Introduction
	2. Definitions
	3. System Requirements
	4. Installing TopShopper
	5. Integrating TopShopper into the site
	6. The Shop Front Page
	7. The Sales Pages
		Hyperlinks
		Forms
		Check Lists
		Prices
		Dynamic Pages
		Dynamic Prices
		Dynamic Navigation Images
		Dynamic Check Lists
		Summary Information
	8. The Shopping System Pages
		Main Pages
		Navigation Images
	9. Payment Options including Credit/Debit Cards
	10. User Includes
		The Configuration Include (inc_config.php)
		The Invoice Top Include (invoicetop.inc)
		The Invoice Bottom Include (invoicebottom.inc)
		The Terms & Conditions Include (merchant_terms.inc)
	11. User Files
		The Products File (products.txt)
		Invoice Reference File (invref.txt)
		E-mail List File (emaillist.php)
		Address File (address.txt)
		Message File (message.txt)
		Location File (locations.txt)
		Postage and Packing Costs
		Post Vectors File (postvectors.txt)
		Postage Look-up Files
		Value Added Tax
		VAT Vectors File (vatvectors.txt)
		VAT Look-up Files
		VAT on Postage
	12. The Administration Files

1. Introduction

TopShopper has been developed specifically for small and medium sized enterprises that want an affordable, reliable and easily integrated e-commerce system. It has been developed particularly with UK merchants in mind although it is equally effective for other merchants. It is designed to work with your own secure payment page but also can integrate directly with WorldPay, PayPal, NoChex or SECPay.

TopShopper is supplied in a form that is 'Ready to Use' . You just need to configure the system and add some 'add to cart' buttons to your sales pages. However, the shopping cart pages can be customised to present a corporate image. To customise, please read section 8 - The Shopping System Pages.

TopShopper has the following characteristics:

• can be implemented on both new and existing sites
• allows the integrator complete freedom of page and site design
• places no restrictions on page authoring tools used
• fast page download times
• integrated mailing script
• adds customers to a mailing list for future automatic customer mailing
• runs on any ISP service or can be user-hosted
• easily integrates with secure payment systems
• allows customers to print quotes and invoices
• handles shipping and handling world-wide
• handles VAT
• allows price breaks when a multiple number of the same product is ordered
• allows for the use of 'Promotion Codes' giving selected customers discounts.
• configurable font and background attributes

2. Definitions

Developer: The Developer of TopShopper is Topdown Active Web Designs. The term developer in this guide always refers to Topdown Active Web Designs and should not be confused with the website builder who may in other circumstances refer to themselves as a developer.

Integrator: The individual or organisation responsible for designing and building a particular commercial website using TopShopper

Merchant: The individual or organisation that owns and runs the on-line shop.

Shopper: The customer who visits the on-line shop.

3. System Requirements

Development requirements

TopShopper can be integrated using a system of 'includes'. All pages containing 'includes' must be active pages and have the extension '.php'. Once installed it can be configured over the Web. The Shopping Cart will run in any browser as straight forward HTML code is used. There is some use of JavaScript but this is limited to form validation which increases the functionality. However, if no Java is available on the browser, validation is carried out server-side.

Hosting Requirements

The server needs to be running PHP3 or better. It is also important to retain the names of the files and folders supplied with TopShopper , as with any website. The main folder (shopcart) must reside on the site root directory. All configuration files can be edited through a Web Browser although direct manipulation of the products, post and vat files using a traditional text editor may be easier where large numbers of products are concerned.

Certain folders must have Read/Write permissions. Unfotunately on some servers the permissions are normally set to read-only. The following folders must be set to read/write by the administrator of your hosting company or by the use of 'chmod' via FTP.

'shopcart/t_user' and all files and folders below.
'shopcart/t_user/includes' and all files below.
'shopcart/t_user/files' and all files and folders below.
'shopcart/t_user/files/post' and all files below.
'shopcart/t_user/files/vat' and all files below.

Diagnostic Script

You can save a lot of time by running the diagnostic script found at
'/shopcart/admin/diagnostic.php'. Once you have uploaded the system to
your site, then access http://yoursite/shopcart/admin/diagnostic.php
through your browser.

If you do not understand how to deal with any errors that are detected,
please email the results to help@topshopper.net for assistance.

4. Installing TopShopper

1. Add the ‘shopcart’ folder to your site in the root (home) directory.
2. Run the Administration file (http://yoursite/shopcart/admin/index.php) to configure the system. The Username is initially set to 'username' and the Password to 'password'. These should be changed for security reasons which can be done by entering the Configuration Script. There is a help file for the configuration script at '/shopcart/admin/configguide.htm'

5. Integrating TopShopper into the site

You are advised to go first to the Topshopper Test System (http://yoursite/shopcart/shoptest/index.php) that is included for familiarisation and as a working example. Click around. Get a feel for the system. Try changing some of the parameters in the Configuration file. The Configuration file can be edited directly(see format later) or by going to the Administration page at 'http://yoursite/shopcart/admin/index.php'. (It might be a good idea to note the original settings). Some things to try would be: changing background colour; changing font colour and size; putting postage on; putting VAT on etc. Don't try manipulating the products, vat and post files until you know more.

Complete integration will involve the development of:

1. A 'Shop Front' Page
2. The Sales Pages
3. A Shopping Cart Page
4. A Checkout Page
5. An Invoice/Quotation Page
6. A Mailing Page
7. A Terms & Conditions Page
8. A Credit/Debit Card Transaction Page

You will also need to store information about the Merchant's Shop in various 'include' and 'text' files. The most important of these is the 'products file' which holds information about the description, price, VAT codes and postage for each product. It is a good idea to update the 'products file' each time a new sales page is added.

6. The Shop Front Page

The Shop Front page is the page that shopper will return to if they hit the 'Shop Front' button anywhere in the shopping system. It will normally be an index type page from which all parts of the shop can be reached. It does not need to be active and can have extensions like '.htm' or .html'. Don't forget to run the Configuration Script to let the system know the name of the Shop Front page.

7. The Sales Pages

The Merchants Sales Pages are developed in the normal way. However, they will contain links to the Shopping Cart. They may be made dynamic so that they can extract prices information from the Products File and so that different navigation images can be selected through the admin pages.

Once the name of the Shopping Cart file has been decided (We will assume the default name of cart.php has been chosen which resides in the root directory) the 'Add to Shopping Cart' links can be coded. There are two ways to do this - by using a hyperlink or by using a form.

Hyperlinks: Hyperlinks can be used to pass information to the Shopping Cart. The information is passed through the Querystring - i.e.. the stuff after the '?' in the hyperlink.

e.g.. cart.php?step=add&pidref=ZX81&quantity=4&type1=Blu&type2=240V

Notice the use of the '&' sign to link them.

The 'Add to Basket' image can be used as a button as shown below:

<a href="/cart.php?step=add&pidref=CWB"><img src="/shopcart/images/set1/addbasket.gif" border="0"></a>

Other Important Hyperlinks

To View the Basket from any part of the site, use a hyperlink such as: <a href="/cart.php">View Your Basket</a> or use an image
<a href="/cart.php"><img src="/shopcart/images/set1/viewbasket.gif" border="0"></a>

It is so important to make this link available to the shopper at all times (in the menu structure for instance). If you do not do this, the shopper will find it difficult to get back to the shopping cart without having to buy something.

To Empty the Basket from any part of the site, use a hyperlink such as: <a href="/cart.php?step=empty">Empty Your Basket</a> or use an image : <a href="/cart.php?step=empty"><img src="/shopcart/images/set1/emptybasket.gif" border="0"></a>

'step=empty' must be in lower case.

Forms

Forms may be used where there is a variety of types or it is likely that a shopper will want multiple quantities of a product.

The 'METHOD' used by the FORM must be 'GET'.

It is usual that 'step' and pidref' are included as 'Hidden' fields.

One thing to watch out for is that applications such as Dreamweaver will type to 'help' you by changing 'step' to'step2' and 'pidref' to 'pidref2' etc., especially if you try to copy a form to speed things up.

The value in the drop-down menu becomes part of the Product Code in the Shopping Cart. You may prefer to use shortened versions of the Type as shown below. The shortened version can be put in the item list so that the customer understands the meaning of the code.

Note that any drop-down menus must have the name 'type1' or 'type2' or 'type3'. When more than one type is specified, the types are seen in the cart product code separated by a comma.

Typical HTML for a form would be:

<form method="get" action="/cart.php" name="Addit">
<div align="left"><font face="Arial, Helvetica, sans-serif" size="2" color="#000066">Colour
<select name="type1">
<option value="ANY">Any</option>
<option value="RED">Red(RED)</option>
<option value="BLU">Blue(BLU)</option>
<option value="GRN">Green(GRN)</option>
<option value="YEL">Yellow(YEL)</option>
</select>
Quantity
<input type="text" name="quantity" size="2" maxlength="2" value="1">
<input type="hidden" name="step" value="add">
<input type="hidden" name="pidref" value="CP7000">
<br>
<input type="image" border="0" name="Submit" src="/shopcart/images/set1/addbasket.gif" align="middle">
</font></div>
</form>

The PHP scripting engine is 'case sensitive' - step, add, pidref, quantity, type1, type2 and type3 must be in lower case.

Check Lists

Check Lists are a method by which shoppers can choose a variety of products by simply checking a checkbox on a form. (See the Hard Drives sales page on the Test Shop '/shopcart/shoptest/harddrives.php' for an example).

Check Lists are forms that have multiple references to products. Check Lists are usually arranged in tables. Each product in the list must be identified using an enumerated set of parameters. Parameters that can be used are 'pidref', 'quantity', 'type' and checkbox. The first product would be identified by 'pidref1', 'quantity1','type1' and 'checkbox1'. The second product would be identified by 'pidref2', 'quantity2','type2' and 'checkbox2' etc.

'pidref' is normally a hidden field having a value equal to the Product Identification Reference Code.
'quantity' could be a text box or dropdown menu (defaults to 1 if omitted).
'type' is normally a dropdown menu (can be omitted)
'checkbox' value must be set to"ON"

For the purposes of Lists, each product can only have one 'type' field.

The form must have hidden field having the name 'countmax' and having a value equal to the number of products in the list. The form must have a hidden field with the name 'step' and the value 'checklist'. Finally the form must have an 'add' button.

The form must use the GET method.

Prices

Prices on a Sales Page can either be Static (never change) or dynamic (reflect the current price in the Products File).

Its a good idea to show the shopper both the Product Code and the Price on the Sales Page.

TopShopper supports the ability to set 'price breaks'. If a Shopper buys more that a predetermined number (multilevel) of an item, then they will be charged at the reduced rate (multiprice). This works even if the shopper adds one item to the cart at a time. As soon as the 'multilevel' is reached, the price is reduced.

Dynamic Pages

In order to make the Sales Page Dynamic, the page must have the extension '.php'. The 'inc_dynamic.php' include must be added before any prices or images are sought. This piece of code must be close to the top of the sales page. (See 'computers.php' in the 'shoptest' directory)
The HTML required is:

<?php
   include ("rootpath.php");
   include ($DOCUMENT_ROOT."/shopcart/includes/inc_dynamic.php");
?>

Dynamic Prices

Within the page a short piece of PHP code will allow you to find the unit price, the multilevel and the multiprice of a product. The Product Code is used to identify the product.

e.g. :
Price &pound; <?php GetPrice("D36")?> each.<br>
Price for <?php GetMultiLevel("D36")?> or more<br>
&pound; <?php GetMultiPrice("D36")?> each.

This can be seen in operation on the 'tools.php' page in the shoptest directory.

The prices on a dynamic page are read from the Products File. When this file is edited, the prices change on the website. This makes price changes simple and can be done through the Administration area.

Dynamic Navigation Image Set

Tthe current navigation image set can be accessed by including a piece of PHP in the image link. For example, the current Navigation Image for 'Add to Basket' would be found by using the code :
<img src="/shopcart/images/<?php print $navigationset?>/addbasket.gif" border="0">.
If this type of link is used, the Navigation Image used is that specified in the Administration Configuration. This could be useful if you would like to start with navigation sets supplied with TopShopper but later decide to design some custom images.

These new custom images must have the same names as the existing images and must be stored in the '/shopcart/images/custom' directory. To activate these new images, simply run the Configuration Script in the Admin area and choose 'custom' for the Navigation Images. All dynamic images will now change to the new set.

Dynamic Check Lists

Dynamic Check Lists can be produced on a page by calling the 'GetList()' function found in 'inc_dynamic.php'.

In the 'Products file' , the fourth parameter can contain a letter code to indicate that the product belongs to a list.

e.g.

ZQ70M|30Gb 7200 IDE HDD|89.98|A|x|1|30
ZQ71N|40Gb 7200 IDE HDD|99.99|A|x|1|30
ZQ72P|60Gb 7200 IDE HDD|124.99|A|x|1|30
A27AJ|80GB 7200 IDE HDD|134.99|A|x|1|30
A28AJ|120GB 7200 IDE HDD|209.99|A|x|1|30

On the sales page, a short piece of PHP is used to recover the list is encorporated into a form, using the GET method, that points to your cart.

e.g.
<form name="form" method="get" action="/shopcart/shoptest/cart.php">
<?php GetList("A");?>
</form>

A table of products appears at this point, configured as a Check List.

Images of the products can be accessed by the shopper by clicking on an icon in the form. The icons will only appear if the path to your images has been set up in the configuration file through the administration. All your images, which must be JPegs (.jpg), must be in this directory. If a picture file exists a picture icon appears in the image (Img) column that can be 'clicked' to recover the image in a new browser window. If a picture file does not exist the word 'No' appears in the image (Img) column. The name of the picture file must be the same as the product code, plus the .jpg extension. For example D36.jpg, where D36 is the product code..

Letter codes can be more than one character. The system is case sensitive. Other lists can be defined by using different letter codes.

(See the Hard Drives sales page on the Test Shop '/shopcart/shoptest/harddrives.php' for an example)

Note that Dynamic Lists and Multiprice systems are mutually exclusive. That is, you can't use them both on the same product.

Summary Information

You can show the current summary status of items in the cart by adding some PHP to the sales and other pages. The table below shows the information available and the code required to print it on the page.

These are session variables and will only be available if a session has been started. The page must have the extension '.php' and you must add the following code on the first line of the code for that page:

<?php
session_start();
include ("rootpath.php");
include ($DOCUMENT_ROOT."/shopcart/includes/inc_dynamic.php");
?>

Please see sales pages in 'shopcart/shoptest' directory for examples

8. The Shopping System Pages

Main Pages

The Shopping Cart Page, the Checkout Page, the Invoice/Quotation Page, the Mailing Page, the Terms & Conditions Page are all dealt with in the same way. Each of these pages are formed by generating a dynamic page (.php) of your choice and by adding one of the appropriate includes. The pages can have any name and be in any directory but the following default values may make debugging easier:

'/cart.php' should contain the include - '/shopcart/includes/inc_cart.php'
'/checkout.php should contain the include - '/shopcart/includes/inc_checkout.php'
'/invoice.php' should contain the include - '/shopcart/includes/inc_invoice.php'
'/mailer.php should contain the include - '/shopcart/includes/inc_mailer.php'
'/terms.php should contain the include - '/shopcart/includes/inc_terms.php'

These 'includes' use PHP Sessions and it is imperative that a 'Session' is started before any HTML is sent to the browser.
Therefore the following HTML code must be included at the very top (on the first line) of each of the above pages - before the <HTML> tag.

<?php
   session_start();
?>

To include the files use HTML like:
<?php
   include ($DOCUMENT_ROOT."/shopcart/includes/inc_cart.php");
?>

The Configuration File in the Administration section should be updated to indicate the location of these files.

Important Note
It is possible to continue to update and use the files in the shoptest directory. However, this is not recommended. The purpose of using the 'includes' is so that the shopping system can be tailored to present a corporate type image and produce a site to the merchant's specifications. For the system to work properly, the includes need to be allocated about 600 pixels width and unlimited length. However, a smaller width may be possible using small font size (size 1). The minimum width may also be limited by the size on the navigation images within the shopping cart pages. However, you can design your own images that could be made small.

See the files in the 'shoptest' directory for examples.

Navigation Images

There are 7 navigation images. These are: addbasket.gif, continueshop.gif, emptybasket.gif, proceedtochkout.gif, shopfront.gif, terms.gif, viewbasket.gif. You are provided with sets of standard images. The Navigation Set can be changed in the Configuration File or through the Administration Area. However, you can add your own images to a custom directory to suit your web page. You must not change their names. Typical size for the image is 100 x 22 pixels although some are larger. Larger sizes may effect the width of the shopping cart.

The images will be found in various directories like '/shopcart/images/set1'. You should add your own images to the '/shopcart/images/custom' directory. The images will then be accessed using <img src="/shopcart/images/custom/addbasket.gif" border="0"> for example. You must also change the Navigation Set in the Configuration area of the Administration.m

9. Payment Options including Credit/Debit Cards

The system can be configured to display up to 5 payment methods including credit/debit card payments. There are 5 options that can be switched on and off independently: payment by cheque, payment by credit/debit card over the phone, payment on-line through your own secure server, or payment on-line via WorldPay, PayPal Nochex or SECPay

Payment by Cheque

When this is switched on, the merchant's address appears on the payments page and the customer is invited to send a cheque to that address. Ensure a valid address is set up in Administration.

Payment by Telephone

When this is switch on, the merchant's telephone number appears on the payments page and the customer is invited to supply their credit/debit card details by phone. Ensure a valid telephone number is set up in Administration.

Payment through your Secure Server

When this is switched on, the customer is invited to pay through your Secure Server.

You can set-up your own secure payment system either on your local or a remote site. This site must support PHP3 of better if you intend to use the credit card collection script supplied (inc_credit.php). An ASP version is available if required from TopShopper

The necessary files are contained in the 'secure' directory. Upload this directory, if necessary, to the site you want to use. You can modify the credit card collection page as you wish. The recommendation is to use 'credit.php' as a name which will contain the include 'inc_credit.php' at the appropriate place.

To include this file use HTML like:
<?php
   include ("inc_credit.php");
?>

The 'inc_credit.php' include must be able to access the 'inc_config.php' file that must be in the the same directory as the credit.php file. Once the 'inc_config.php file has been permanently established on the main site, it must be copied from the '/shopcart/t_user/includes' directory to the secure directory on the secure site. Note that any subsequent changes to the Configuration File on the main site will not be reflected on the secure server until the new 'inc_config.php' file has been copied there. Adjustments to the configuration can then take place on the secure server by running the configuration script from the administration on the secure server ('/secure/index.php")

If you want to use your own credit card collection script, the following data will be sent by the mailing script using the POST method:

invoiceref - contains the transaction reference number
invoicetotal - contains the value of the transaction
email - contains the shopper's email address
step - contains the text "getdetails"

Credit Card Number Checking
The credit card number is checked using the LUHN formula. The Luhn formula is used by all credit/debit cards to produce a check digit. This does not check that a credit card is valid. If you put in a random number, there is a one-in-ten chance that it will pass the LUHN test. However, it is very good at detecting 'finger trouble' or swopping the order of two digits or missing out a digit completely. These are the main cause of failure. You will still need to check the validity of the card number and whether funds are available.
For testing, use the number 4000-0000-0000-0002 which is a well-known valid number. If you change any one of the digits it will fail. The system ignores dashes and spaces.

Most credit cards have a security code. You can configure the system to collect this if you want(default), or you can switch it off in the configuration area of the main site. Don't forget to upload the new 'inc_config.php' file to the secure area.

Payment through WorldPay©

If this is switched on, the customer is invited to pay through WorldPay.

If you choose to collect credit/debit card payments through WorldPay©, you must register with WorldPay©. Then you should enter your WorldPay Installation ID and Currency Code (normally 'GBP') in the Configuration Script. The Test Mode paramenters are: 100 - details always acceptable; 101 details always rejected. If test mode set to 0 then system becomes live. Customers will be able to transfer to WorldPay© to make a payment.

Payment through PayPal©

If this is switched on, the customer is invited to pay through PayPal.

If you choose to collect credit/debit card payments through PayPal©, you must register with PayPal©. Then you should enter your PayPal Merchant ID and Currency Code (normally 'GBP'), normally your e-mail address, in the Configuration Script. Customers will be able to transfer to PayPal© to make a payment.

Payment through NOCHEX©

If this is switched on, the shopper is invited to pay through NOCHEX.

If you choose to collect credit/debit card payments through NOCHEX©, you must register with NOCHEX©. Then you should enter your NOCHEX Merchant ID (email) and Return URL(if required), in the Configuration Script. Shoppers will be able to transfer to NOCHEX© to make a payment by Debit Card only.

Payment through SECPay©

If this is switched on, the shopper is invited to pay through SECPay.

If you choose to collect credit/debit card payments through SECPay©, you must register with SECPAY©. Then you should enter your SECPay Merchant ID, Callback URL and Test Mode in the Configuration Script. Shoppers will be able to transfer to SECPay© to make a payment.

Payment through Protx©

f this is switched on, the shopper is invited to pay through Protx.

If you choose to collect credit/debit card payments through Protx©, you must register with Protx. Then you should enter your Vendor Name, Encryption Password etc. in the Configuration Script. Shoppers will be able to transfer to Protx to make a payment.

10. User Includes

These are the only Include Files that you are recommended to edit. There are four User Include files: inc_config.php; invoicetop.inc; invoicebottom.inc; terms.inc. They are found in the '/shopcart/t_user/includes' directory.

The Configuration Include (inc_config.php)

This is a piece of PHP code that is used by all the main shopping cart scripts and includes information about how the system is configured. It is a text file and can be edited with any text editor. However, this file is best edited using the editor provided in the administration area of the system. An example of the file is shown below:

<?php
$scd="#BPZVJLT";
$username="username";
$password="password";
$merchantname="Topdown Active Web Designs";
$shopfronturl="/shopcart/shoptest/index.php";
$carturl="/shopcart/shoptest/cart.php";
$checkouturl="/shopcart/shoptest/checkout.php";
$invoiceurl="/shopcart/shoptest/invoice.php";
$mailerurl="/shopcart/shoptest/mailer.php";
$crediturl="/shopcart/shoptest/credit.php";
$termsurl="/shopcart/shoptest/terms.php";
$telesales="";
$invoicerefcode="TS";
$adminaddress="mike@topdown.co.uk";
$fromaddress="sales@topdown.co.uk";
$csym="£";
$fontface="Arial";
$fontsize="2";
$fontcolor="#000066";
$background="#ffffff";
$cellcolor="#cccc66";
$navigationset="set2";
$postpackingstate="on";
$postcostsource="InvoiceTotal";
$vatstate="off";
$worldpayid="";
$testmode="100";
$wpcurrency="GBP";
$productsfile="/shopcart/t_user/files/products.txt";
$invoicereffile="/shopcart/t_user/files/invref.txt";
$snailmailaddressfile="/shopcart/t_user/files/address.txt";
$messagefile="/shopcart/t_user/files/message.txt";
?>

Please note that the Security Code ($scd) will be different for every site. It has two uses. i) It prevents hackers from remotely corrupting the Shopping System. ii) It prevents copying the Shopping Cart System to other sites without permission. Please make a note of the code in case it gets corrupted. If it is incorrect then the system fails and strange messages appear.

The Invoice Top Include (invoicetop.inc)

This is a piece of HTML code that will be included at the top of the invoice. It can be used to provide a 'Header' for the Invoice and may contain a Company Logo, the Merchant's Address, the Merchants VAT Registration Number etc. It must not be a complete HTML page and must not contain any 'header' or 'body' tags. A simple example would be:

<table width="100%" cellpadding="3">
<tr>
<td height="78">
<div align="right"> <b><font face="Arial" size="2" color="#660000">
Topdown Active Web Designs<br>
Deanwood House<br>
70 Bishops Road<br>
Whitchurch<br>
Cardiff<br>
Wales UK<br>
CF14 1LW</font></b></div>
</td>
</tr>
</table>

It is important that this code does not force the Invoice to be more than 800 pixels wide as this will affect the shopper's ability to print the invoice properly.

The Invoice Bottom Include (invoicebottom.inc)

This is a piece of HTML code that will be included at the bottom of the invoice. It can be used to provide a 'Footer' for the Invoice and may contain a Telephone Number, a FAX number, the Merchant's Address, the Merchants VAT Registration Number etc. It must not be a complete HTML page and must not contain any 'header' or 'body' tags. A simple example would be:

<div align="center"><font face="Arial" size="2" color="#660000">TEL: +44 0870 7424736 - FAX: +44 0870 1262579</font></div>

It is important that this code does not force the Invoice to be more than 800 pixels wide as this will affect the shopper's ability to print the invoice properly

The Terms & Conditions Include (merchant_terms.inc)

This 'include' is used when a shopper asks to see the Merchant's Terms and Conditions. A shopper cannot complete the transactions until they have agreed to the Terms and Conditions as specified in this include. It is therefore important that this piece of code is prepared carefully. You may like to take legal advice before producing this file. It must not be a complete HTML page and must not contain any 'header' or 'body' tags. An example would be:

<ol>
<li> Payment may be by secure credit card transaction or by cheque.</li>
<li>Delivery is by Royal Mail or Carrier.</li>
<li>VAT is charged at the prevailing rate (17.5%) unless otherwise specified.</li>
<li>Your details will be stored on a computer according to the terms of the Data Protection Act 1984.</li>
<li> All goods remain the property of this company until payment is made in full.</li>
<li>We reserve the right to refuse to supply goods.</li>
<li>Delivery, please allow 28 days for delivery, delivery charge will depend on goods ordered.</li>
<li>We can take payment by Visa, Mastercard, and Switch or by cheque &amp; postal orders. For exchange you will need to supply a copy of your receipt. If the goods are found to be defective we will send a replacement within 28 days.</li>
<li>We reserve the right to change any advertised price before you place an order.</li>
<li>All products and services are subject to availability and may be withdrawn at any time. If your order cannot be fulfilled you will be offered an alternative or given a full refund.</li>
<li>Payment can be made by Visa, Mastercard, and Switch. Payment will be debited from your account before the dispatch of your purchase. We will take all reasonable care, in so far as it is within our power to do so, to keep the details of your order and payment secure, but in the absence of negligence on our part we cannot be held liable for any loss you may suffer if a third party procures unauthorised access to any data you provide when accessing or ordering from our site.</li>
<li>We request your name and address to enable us to provide you with an efficient after-sales service but we WILL NOT pass you name and address to ANY third parties.</li>
<li> If you are not entirely satisfied with your purchase, you can return it within fourteen days of the despatch date with your receipt, providing it is unopened.</li>
<li>Goods are not sold on a trial basis.</li>
<li>Claims for damage, non-functionality and mis-shipping must be made within seven days of receipt.</li>
<li>You are responsible for ensuring safe delivery of the returned item. </li>
<li>Reserve the right to amend these Terms and Conditions at any time.</li>
<li>These Terms and Conditions do not affect consumer statutory rights.</li>
</ol>

11. User Files

These are the only files you are recommended to edit. These files store information about the Products, Postage Rates, VAT Rates and Shopper's E-mail Addresses. There are also other files that support these files. They are all text files that can be produced and edited by any text editor. Once established they can be modified through the Administration area. They are found in the '/shopcart/t_user/files' directory.

The Products File (products.txt)

The Products File holds details of the Shop's products. There is one product per line. The format is:

Product Code|Short Description|Unit Price|Multi-Level|Multi-Price|VATCODE|POSTUNIT

An example of a Products File is shown below:

Prod|Desc|Unitprice|MultiLevel|MultiPrice|VATCODE|POSTUNIT

**** Tools ****
CP7000|7" inch Normal Side Grip Complete|450.75|x|x|1|20
CWB|Combination Wheeled Base/Overhead Control|455.00|x|x|1|30
D36|3" inch Disc(74mm) - 6 Teeth|70.00|3|65.00|1|5
D60|5" inch Disc(126mm) - 10 Teeth|250.00|5|240.00|1|5

**** Computer ****
M7VKB|Socket A Motherboard|102.12|x|x|1|5
TF78K| 17" Monitor|221.99|x|x|1|5

The formatting of this file is strict and crucial. The rules are:

• There must be 7 text areas on each line separated by the '|' character. (This character is to be found next to 'Z' ie. 'shift \'. Often depicted as two short vertical lines above each other.) This character can only be used as a separator.
• Blank lines or lines with less than 7 text areas separated by the '|' character will be ignored.
• The only area where all printable characters are allowed including 'space' is in the Description area.
• The Product Code must not contain a dash(-) or an underline character(_) and must have no spaces. Use alphanumeric only. The system is case-sensitive.
• The Description should be fairly short. This is the only area where all printable characters are allowed, including 'space'.
• The Unit Price must not contain the currency symbol(£, $ or other).
• The Unit Price must be the normal retail price if VAT is switched off. If VAT is switched on, then the prices must be the price excluding the VAT element.
• The Multi-Level is the number of items of that product that must be purchased to take advantage of the discounted price. If this is not applicable for this item then a non numeric character must be inserted. 'x' is recommended.
• The Multi-Price is the Discount Price per unit item. It must not contain the currency symbol(£ or $).
• The Multi-Price must be the normal retail price if VAT is switched off. If VAT is switched on, then the prices must be the price excluding the VAT element.
• The VAT CODE is a numeric code that will be used to determine the correct VAT value. If VAT is 'off' it is recommended that this value is set to zero '0'. See later.
• The POST CODE is a numeric value that may be used to calculate postage and packing costs. If Postage is 'off' it is recommended that this value is set to zero '0'.
• There should be no extra spaces
• Lines that do not fulfil the above may cause PHP errors.

In order to make the file easier to edit and maintain, separator lines can be included. They will not normally contain the '|' character. See above.

Invoice Reference File (invref.txt)

The Invoice Reference File holds the next invoice reference number. This is incremented after each sale. A Merchant Identifier Code is added at the front of this number which can be changed during configuration.This number is used on all e-mail and credit/debit card transactions for a particular sale.The maximum value of this number is 99999999; Numeric only allowed. If the merchant reaches this number of sales it will have to be reset. It's a good idea to start at say 1000000 - It gives a better impression to the first few customers.

E-mail List File (emaillist.php)

When a customer asks to be added to the mailing list, the customer's name and e-mail address are added to this file. The format is:

Name|Email Address

It is important to keep the '<?php die("Security Breach - Closing Now" )?>' at the top of the file for security reasons. This stops snoopers downloading your email list.

Address File (address.txt)

This file should contain the Merchants Address. It is used on E-mails sent to customers

Message File (message.txt)

This file should contain an additional message that will be sent to customers in the sale confirmation e-mail. It could, for instance, contain information about latest deals or new products.

The following files need only be included if either VAT or Postage are switched on

Location File (locations.txt)

When VAT or Postage is switched on, the system needs to know the location of the address to which the goods are to be sent. Under these circumstances, a 'location' field appears in the Checkout form. The locations presented in the form are drawn from the 'locations.txt' file. The format of the file is:

Location|Location Code

eg.
United Kingdom|UK
Elsewhere in Europe|EU
Outside Europe|WW

You can have as many as you like. The number you have will depend on the number of distinct areas there are in terms of postage and/or VAT. If the Merchant is located in the UK then the above example will usually suffice. Keep the Location Code short as it will be used elsewhere.

Postage and Packing Costs

Post and Packing rates are determined by using Look-up files. Postage costs can be based on the Invoice Total or on some unit such as weight. The system can be configured to use one of these methods. If 'Invoice Total' is selected for the 'Postage Calculator Source' then the POSTUNIT in the products file can be set to zero(0). However, if 'Post Unit' is selected for the 'Postage Calculator Source' then a decision must be made about the Unit that will be used. Normally it will be weight but it could also be length. If weight in grammes is chosen, then the weight of each product needs to be entered in the POSTUNIT section on the Products File.

It must be said that it is easier to either make post and packing included or use Invoice Total and to put a limit on postage costs or make postage free for invoices above a certain value. All of these are possible. See Later.

Post Vectors File (postvectors.txt)

When Postage is switched on, the system uses the Post Vectors File to determine which postage Look-up File is used for each Location as defined in the Location File. The format is:

Location Code|Look-up File Name

eg.
UK|UK
EU|EU
WW|WW

The .txt extension is assumed for all Look-up File names and should not be included. Each Look-up File must be included in the '/shopcart/t_user/files/post' directory.

The system of vectors may seem complicated but it allows for greater flexibility where large numbers of Locations are used.

Postage Look-up Files

Postage Look-up files contain information about postage costs for a particular location. The format is either:

Invoice Total = Postage cost
or
Post Unit Total = Postage cost

This will depend on which is active.

The Calculator moves from top to bottom of the file testing each level.

For example: a file that calculates postage based on weight using second class post may look like this :

0=0.19
101=0.33
201=0.54
301=0.76
501=1.30
1001=3.32
2001=6.78
4001=12.35

Packages up to and including 100g are charges 19p
Packages up to and including 200g are charged 33p etc.
The maximum charge would be £12.35 for over 4Kg.

You can make the divisions as large or as small as you like. Each product would have to be weighed and the value put as the POSTUNIT in the Products File.

Another example: A file that calculates postage based on Invoice Total

0=5.00
20.01=0

This simple file will charge postage of £5.00 for Invoice values of up to and including £20.00 and nothing for Invoice values above £20.00

Value Added Tax

Within the EU the application of VAT is Universal. VAT is a tax on added value and not on individuals, processes or products. The tax is payable by all purchasers of goods located in the same jurisdiction as the merchant. In these circumstances, purchasers who are registered may claim VAT paid back from the Government. Because of this, Shoppers will normally be interested to see the VAT element in the cost of anything they may purchase. The purchaser needs to be able to quote their VAT registration number and this information is collected by TopShopper.

When dealing across national borders, the situation is a little more complex. A shopper based in the EU, but outside the UK, and who is not registered for VAT is treated as if they were located within the UK and are liable to pay VAT. If the shopper is registered for VAT in another EU country, then they are charged for the goods at a VAT-exclusive price, the shopper being responsible for accounting for VAT at their member state's prevailing VAT rate. The merchant is required to obtain the VAT registration number to support the VAT free supply of goods. TopShopper therefore requests the VAT registration number before goods can be supplied at zero rate.

Once trade is outside the EU, the supply of goods is VAT free.

In relation to VAT on postage, the current situation is that no VAT should be applied to goods sent by Royal Mail but for Courier etc, VAT should be applied.

The above is just a guide. It is strongly recommended that any tax queries are discussed with the merchant's accountant or financial advisor and possibly the VAT authorities of the Customs and Excise Service.

The good news is that whatever system of VAT you may want, TopShopper will deal with it.

VAT Vectors File (vatvectors.txt)

When VAT is switched on, the system uses the VAT Vectors File to determine which VAT Look-up File is used for each Location as defined in the Location File. The system of vectors may seem complicated but it allows for greater flexibility where large numbers of Locations are used. The format is:

Location Code|Look-up File Name for unregistered customers|Look-up File Name for registered customers

eg.
UK|UK|UK
EU|UK|NULL
WW|NULL|NULL

The .txt extension is assumed for all Look-up File names and should not be included. Each Look-up File must be included in the '/shopcart/t_user/files/vat' directory.

The above 'vatvector' will be typical for UK based merchants who are registered for VAT. It will apply VAT at UK rates for all UK shoppers, whether registered or not. It will apply normal UK rates for non-registered EU shoppers but will apply the null rate for registered EU shoppers. It will apply the null rate for all other non EU shoppers. This assumes the Location File has been set up are shown above.

VAT Look-up Files

Instead of allocating actual fixed rates of VAT to a particular item, TopShopper uses a system of VATcodes and it is these codes that are used to deternime the tax levied on each item. This allows changes of tax rates to be accommodated and for non-UK rates to be applied. Every item sold on the site of a VAT registered merchant has to be allocated an appropriate VAT code.

In the UK there are currently only three different rates i.e. 0%(e.g. books medicines), 5%( Domestic Fuel) and 17.5% (standard rate) and therefore the codes 0,1 and 2 could be used for items within these three categories. However, most sites will not be selling domestic fuel and so only two codes need to be used - 0 and 1.

Difficulties arise where a merchant is registered for VAT in other EU states. This means that the same goods may have different rates applied in different states. This is where the power of the 'vectors' comes in. The shopper will be directed to a different Look-up file depending on their location. It is therefore important that each group of products that may be charged differing amounts of VAT in different locations be allocated different VAT codes.

The format of the VAT Look-up Files are:

Rate for VAT Code 0|Rate for VAT Code 1|Rate for VAT Code 2|Rate for VAT Code 3|etc.

The rate for each VAT Code set must be available in each Look-up File.

Where a merchant is only registered in the UK, then normally only three Look-up files are required - the default file, the standard UK file and the null file. Assuming that the merchant will only be applying two different VAT codes the UK file will be: 0|17.5 and the null file will be 0|0. The default file contains the standard VAT rates for the country you are operating in. These values are used by the cart until the shopper reveals their location at the checkout stage. The appropriate rate of tax is then applied.

VAT on Postage

You can configure the system to apply VAT to Postage. This is done in the configuration area. VAT will be applied at the rate you specify. Please do not include the '%' sign in the text box.

12. The Administration Files

An administration area is provided that allows for the editing of the User Files. This is meant to be used by the Merchant or Integrator to make minor changes to the system parameters, once the system has been set up. Simply go to 'http://yoursite/shopcart/admin/index.php' . The Username is initially set to 'username' and the Password to 'password'. These should be changed for security reasons which can be done by entering the Configuration Script.

You must Log In to edit the files or configure the system. For security reasons, you will be Logged Out automatically after about 10 - 20 minutes of inactivity.

Thank you for using TopShopper