CandyPress Store
Copyright 2010 Cavallo Communications, LLC DBA CandyPress.Com


  1. Introduction
  2. Installation and Setup
  3. Customizing your Store
  4. General Notes
  5. Upgrading from previous versions
  6. Applying Updates
  7. Acknowledgements
  8. Change History

1. Introduction (TOP)

CandyPress Store is an eCommerce solution based on popular Microsoft technologies. It is designed to run on an IIS web server that is ASP and VBScript enabled. In addition, the software is designed to work with SQL Server or MS Access databases.

2. Installation and Setup (TOP)

2.1. License

Before installing this product, be sure to read the License Agreement (included with this software) carefully. By using the software, you also accept and agree to the License Agreement. If you don't have a copy of the License Agreement, you can contact us for a copy.

2.2. Install the software

To install the software extract the files from the installation .zip utilizing a zip file utility such as WinZip to a folder on your system. The installed software folders and files will have a structure similar to this :

2.3. Upload files to your web server

Upload, copy or FTP the entire folder to your web server, including ALL the folders and files inside it. Do not change the file and folder structure. You would typically place the folder in your web server's root directory, but it can also be copied to any sub-directory under the web server's root directory. The file store1.mdb in folder cpdata should have read/write permissions.

Store Install
Once uploaded, start the on web site configuration by opening your browser and in the address bar enter the URL to the upload location followed by /installer/000_welcome.asp and press enter. Follow the on screen instructions using the following for login Userid admin Password admin. 

2.4. MS Access Only

The folder CPData contains the database file store1.mdb. The folder and file must have read and write permissions on the server. If you don't know how to change file permissions on your web server ask your web hosting company for assistance. Once you have done that, you should take some extra steps to ensure that the database is protected :

2.5. SQL Server Only (Administration Only)

You will need to create a blank (empty) database for your store using whatever means you have at your disposal (you may have to contact your web host or use your web hosts control panel). Next, run Admin | | Utilities  | Convert to SQL database to create the tables and load the existing Access database data to the SQL Server. Change the config/config.asp connection string to use the SQL database and change the type of database in use, see below.

2.6. Modify Configuration File

The configuration file is called config.asp and is located in the Config folder. This file holds some of the most important settings required to run the store. Before proceeding to the next step, it's important that you make the necessary changes to this file. Open the file with a good text based editor (e.g. Notepad). Don't use MS Word or something similar because it may insert a lot of 'junk' characters into the file. The settings below are the most important and must be set properly in order to continue :

2.7. Test Your Database

At this point, you should have all the scripts copied to your web server, and the sample Access database should be in a read/write folder (or if you're using SQL Server, you created a blank database). Now we need to ensure that your connection string and database permissions are correct so that you're able to connect to your database, and read and write to it. This is done using some utilities available from the Admin area of your store. IMPORTANT : You'll need to pass all the tests below before you can proceed with the installation as the rest of the installation procedure requires that you are able to read and write from your database.

2.10. Store Configuration

You should now be able to connect to the database and write to it. Most of the store's configuration settings are held in the database and are updated with an online utility. It is therefore important that you can successfully read and write to your database before you continue (see previous paragraph). Click on the Store Configuration link and review each setting carefully. Detailed help is available online for each of the settings. At a minimum, you must change the two settings indicated below before you can start testing your store.

2.11. Text Configuration

Some of the messages and text in your store can be modified to more closely match your specific requirements. For more details, click on the Text Configuration link, where you will find detailed instructions on how to make these modifications. You can leave the default values if you simply want to test the store (just remember to update them before you go live), or if you are happy with the default settings.

2.12. Test your store

At this point (provided that you have successfully completed the steps above) you can start to test your store. You should be able to browse the products in the store, add items to the shopping cart, create an account and complete an order. Depending on the specific gateway that you will be using for payment, you will have to take additional steps to configure your store to work with the gateway of your choice (see further down). You may also want to re-visit the Store Configuration utility to review all the settings to ensure that they are set to whatever values is appropriate for your store.

2.13. Other Permissions

If you want to use the file upload utility provided with this product, you will have to ensure that the anonymous web user account has read and write permissions on the Product Images directory, and the Download Files directory. In the meantime you will be able to upload images and other files using any good FTP software, or your regular web authoring software (e.g. "FrontPage").

2.14. Affiliates

If you want to allow Affiliates to signup themselves, there is a special link that must be placed in _INCtemplate_.asp. See the Links section in this document for more information. There is also an example inside _INCtemplate_.asp but it is enclosed in HTML comments. You can simply remove the comments which will result in the link being displayed.

2.15. Adjusting Session Timout

If during testing, you feel that the session times out too quickly, you can modify the "session.timeout" value in your store's global.asa file. Locate the global.asa file on your web server and insert the line session.Timeout=nn (where nn is the timeout value in minutes, increase or decrease to suit your needs). This line should be placed in the Session_OnStart code block. For example :

sub Session_OnStart
end sub

2.16. Payment Gateways

This software comes with built-in support for various payment methods and gateways.

Offline Payments - These payment methods refer to payments that will be manually finalized after the order has been placed. For example, Mail-In, Fax-In, Call-In, COD, etc. If necessary, You should make sure that the customer is aware of where and how they need to send payment. This information could go into a separate web page on your site and/or the Terms and Conditions and/or the confirmation email. After payment has been finalized, you will then manually update the order status.

Offline Credit Cards - Normally you would only offer this as a payment method if you have a merchant account. If you select this as a payment method for your store, the customer will be asked to enter their Credit Card details during the checkout process, and this information will then be stored along with the rest of the order in your database. Your next step (after receiving the order) would then be to process the credit card payment using the tools provided by the company with whom you have your merchant account, or you can use the built-in Authorize.Net interface if you have an account with them. After successfully processing the credit card payment, you can then go ahead and update the Order's Status and complete the transaction. If you will be using this payment method, be sure to also enter the type of Credit Cards (e.g. Visa, MasterCard, etc.) you can accept into your store's configuration settings. NB : If you are using offline credit cards, you should delete the card number from the order after it has been processed to ensure maximum security.

Authorize.Net AIM - With the AIM payment method, the customer will be instructed to enter their credit card details on a form on your web site. The form values are then posted to Authorize.Net "silently", meaning the customer doesn't see any interaction with Authorize.Net. To setup, you will need to enter your Authorize.Net login ID, Currency Code and Transaction Key into your store's configuration settings (these are obtained from Authorize.Net). See Authorize.Net for more details.

Authorize.Net SIM (Front-End) - If used on the front-end, the customer will be redirected to Authorize.Net during the checkout process where they will fill in a form to complete the payment. Their payment info is stored directly on Authorize.Net's servers. To setup, you will need to enter your Authorize.Net login ID, Currency Code and Transaction Key into your store's configuration settings (these are obtained from Authorize.Net). You will also have to enter the full URL to your store's 60_PayReturn.asp file (e.g. "") in your Authorize.Net account as a valid receipt URL. See Authorize.Net for more details.

Authorize.Net SIM (Back-End) - If you accept 'Offline Credit Card' payments, and you have an Authorize.Net account, you can use the integrated back-end credit card authorization tool. With 'Offline Credit Card' payments, the customer enters their credit card info on your site, and it is stored in your database. You must then authorize these transactions manually. The Authorize.Net back-end interface makes this process much simpler by allowing you to simply click on a link in the Administration area which will pre-fill the authorization form, saving you from typing everything in manually. Setup is the same as the front-end (above). See Authorize.Net for more details.

PayPal - Setting up your store to accept PayPal payments is a simple matter of entering your Primary PayPal Email Address (sometimes refered to as the Member ID) into your store's configuration settings. You will also need to select the Currency for your store. No further setup is required from within your PayPal account. Your customer will supply PayPal with all the necessary payment details (such as their credit card info, etc.) during the checkout process, and PayPal will then notify you via email if the payment has been successful (or you can check your PayPal account online). This means that you don't have to store the customer's payment details in your store's database. Note that the customer will be required to create an account with PayPal (if they don't have one already) when they pay for their order. Fortunately, PayPal is by far the most popular 3rd Party payment processor so the chances are very good that your customers will already have a PayPal account. See PayPal.Com for more details.

PayPal IPN - (Requires Microsoft XML Parser to be installed on the server) If you use PayPal IPN (Instant Payment Notification), the order status and product inventory is automatically updated whenever PayPal processes a valid payment for your store. In addition, an email is automatically sent from your store to your customer to notify them of the status change. To use PayPal IPN, you must setup your store as described above for regular PayPal payments. Then, you must take the additional step of "activating" PayPal IPN.

  1. Log on to your PayPal account.
  2. Navigate to "Profile" -> "Instant Payment Notification Preferences".
  3. Switch IPN on.
  4. Enter the URL of the script that will be processing IPN payments for your store. The PayPal IPN script is located at "scripts/60_PayXPayPal.asp". You will have to enter the FULL path to this script into your PayPal IPN URL (e.g."").

See PayPal.Com for more details.

2CheckOut.Com - 2CheckOut.Com is in many ways similar to PayPal, except that the customer is not required to create an account with them when they pay for their orders. The customer would (like PayPal) supply 2CheckOut.Com with all their payment details, so there is no need to store that information in your store's database. To use 2CheckOut.Com, you would need to enter your 2CheckOut.Com account number into your store's configuration settings. In addition to this, you should also enter a 'return URL' into your 2CheckOut.Com account setup. This is to allow 2CheckOut.Com to redirect your customer back to your web site after the payment has been concluded by 2CheckOut.Com.

  1. Log on to your 2CheckOut.Com account.
  2. Navigate to "Look & Feel" from the home page.
  3. Set "Return to a routine on your site after credit card processed:" to "Yes".
  4. Enter the full path to the "/scripts/60_PayReturn.asp" page in the "Return URL" text box (e.g. http://www.myStore/cp5.1/scripts/60_PayX2Checkout.asp).
  5. Put your 2CheckOut.Com account in "demo" mode and enter a few test orders to see that everything works as it should.

See 2CheckOut.Com for more details.

2CheckOut.Com Auto Update - You can automatically update an order's status and inventory on return from 2CheckOut.Com. When the customer pays via 2CheckOut.Com, they will be presented with a confirmation screen, with a button that they must click to return to your web site. When they click this button, several bits of information is passed back to your web site that allows the software to determine if the order was successful, and do the necessary updates automatically. To use this feature, you will have to follow these steps :

  1. 1. Log on to your 2CheckOut.Com account.
  2. Navigate to "Look & Feel".
  3. Set "Return to a routine on your site after credit card processed:" to "Yes".
  4. Enter the full path to the "/scripts/60_PayX2CheckOut.asp" page in the "Return URL" text box (e.g. http://www.myStore/scripts/60_PayX2CheckOut.asp).
  5. Navigate to "Account Details" -> "Return".
  6. At the bottom of the page, enter your "Secret Word".
  7. Go to your store's Admin section and enter the exact same "Secret Word" there (this word is case sensitive).
  8. Put your 2CheckOut.Com account in "demo" mode and enter a few test orders to see that everything works as it should.

See 2CheckOut.Com for more details.

Google Checkout - FFirst, we need to define what is Google Checkout (GC) and how it differs from any other payment method currently available in CandyPress (CP). GC is billed as a way for customers to pay online without having to reveal their finical and personal information to another party but only to GC. GC will keep their finical and personal information safe!

To accomplish keeping that information safe all personal and finical information is maintained on GC. The shopping cart should not know more than the GC order number and the status of the payment. This implies that you would not even know the name of the person making the order. But because the products have to be sent to someone, that information is returned to CP by GC. CP uses that information to create a customer record if one does not exist. It creates both the billing and shipping detail from that information. The shipping detail should be correct but the billing may not be as it will reflect the same information as the shipping, which may not be the same.

You as the shop owner have the option to maintain the order either through the CP Admin or your GC admin. Note, that invoicing technically should be accomplish using GC because the information that CP has is mixed.

Knowing how GC interacts with CP will allow you to make a more informed decision about whether you wish to use GC as your payment and order maintenance tool. If you don't wish to maintain customers through both CP and GC then GC may not be for you.

If you chose to use GC then you must have a GC sellers account with an issued merchant account id and a merchant key.  I suggest that you initially setup a sandbox account at, complete all information on the "Settings" tab and make  a special note of the merchant id and key - you'll need to enter these into CP and to establish a HTTP basic authentication account on your web server.

An HTTP basic authentication account is a user account that uses the merchant id as the user name and the merchant key as the password. It will need the same permissions to the same directories as required by usr_machinename. (see the readme.htm file).

Once you have the GC account established you'll need to define how it communicates with CP. With your account open click on the "Settings" tab, click on "Integration" at the left navigation. 

Setup the following as shown and save.

API callback URL (Level 2 integrations only) [?]
Specify a URL for Google to notify you of new orders and changes in order state. You must provide the URL of a server running 128-bit SSLv3 or TLS. [?]
API callback URL: 
< name="smb.notificationUrl" value="" id="apiURL" maxlength="SmbIntegrationSettingsHandler.MAX_NOTIFICATION_URL_LENGTH" style="width: 100%;" ="API(this.value)" ="API(this.value)" ="text">
Callback method: 
e.g. <google-order-number>123</google-order-number>
HTML (name/value pairs)
e.g. google-order-number=123


Shopping cart post security

Please note that any changes to these settings will modify the API messages that Google delivers. It is strongly recommended that you first test any changes to these settings on the Sandbox test server.[?]

Note that the API URL call back is not using an SSL, this should be changed when you set up for production.

Custom Payments - If you want to use a payment gateway not provided as standard with the software, you can write your own gateway routine using the "_INCpayOut_.asp" and "INCpayIn_.asp" files located in the "UserMods" directory. Some ASP and HTML knowledge is required. The FAQ section in our support forum has several working examples for some popular gateways.

2.17. Troubleshooting

If you are experiencing difficulty installing and running the software, please visit the FAQ and support section on our web site where a lot of questions are already answered. Some of the most common causes for errors are :

3. Customizing your Store (TOP)

3.1. Overview

If you want to change the look and design of the store, you will need to make some changes to the files in the UserMods folder. Depending on the amount of customization you want to do, it's not that difficult. CSS is used extensively for the purpose of changing colors, fonts, and so forth. The most important files are :

NOTE : To ensure that you will be able to upgrade the software later on, you shouldn't make any changes to the files in the Scripts or Admin folders. If you do, be sure to document these changes so that you can re-apply them after doing an upgrade.

3.2. /UserMods/img/*.gif

There are several image files that can be modified with a graphic (or image) editor to more closely resemble the color scheme and theme of your web site. Do not change the name of the file, just it's contents. Also, we strongly advise you to stick to the original image dimensions (i.e. width and height).

3.3. /UserMods/*.asp

As mentioned earlier, there are several ASP files within the UserMods folder that can be modified to change the look of your store. You should use a good text editor, or ASP aware software like Visual Interdev to make these changes. The golden rule is to make a small amount of changes, then thoroughly TEST those changes before making more changes. This way it will be a lot easier to pin-point where you went wrong. Even if you are not skilled in ASP or HTML, you can always experiment. Just keep a copy of the original file(s) so you can restore if you need to.

3.4. Links

The most important thing to remember about links is that you must ALWAYS specify the full URL to the target page, not a relative path. The easiest way to do that is to use the urlNonSSL variable as shown below. This will ensure that links operate properly when switching to and from SSL sessions.

Standard links included in _INCtemplate_.asp . These links should always be present in _INCtemplate_.asp to ensure that the customer can browse and use your store properly :

<a href="<%=urlNonSSL%>default.asp">Home</a><br><a href="<%=urlNonSSL%>prodList.asp">All Categories</a>
<a href="<%=urlNonSSL%>contactUs.asp">Contact Us</a><br><a href="<%=urlNonSSL%>05_Gateway.asp?action=logon">Account</a><br><a href="<%=urlNonSSL%>cart.asp">Cart</a>
<a href="<%=urlNonSSL%>05_Gateway.asp?action=checkout">Checkout</a>
<a href="<%=urlNonSSL%>prodList.asp?special=Y">Specials</a>
<a href="<%=urlNonSSL%>prodSearch.asp">Advanced Search</a>

Products and Categories example links. These examples show how you can put a hard-coded link to a specific product or category in _INCtemplate_.asp if you wish :

<a href="<%=urlNonSSL%>prodList.asp?idCategory=5">Sauce Category</a>
<a href="<%=urlNonSSL%>prodView.asp?idProduct=5">Mayonnaise - 500g</a>

Affiliate signup link. If you want to allow affiliates to sign themselves up, use the following link in _INCtemplate_.asp :

<a href="<%=urlNonSSL%>05_Gateway.asp?action=logonaff">Affiliates</a>

3.5. Search

To add a search box, use the example code below. The default version of _INCtemplate_.asp already has a search box.

<formaction="<%=urlNonSSL%>prodList.asp" method="post" id="search" name="search">
<input name="strSearch" size="20">
<input type="submit" name="submitSearch" value="GO">

3.6. Cart Quantity and Total

You can display the current cart quantity and total by using the code shown below. The default version of _INCtemplate_.asp already has this built-in.

Quantity : <%=cartQty(idOrder)%>
Total : <%=moneyS(cartTotal(idOrder,0))%>

3.7. Featured Categories

You can easily display the Featured Categories of the store by using the showFeaturedCat() function. The code below serves as reference :


3.8. New Products

To display a list of all the latest products added to the store, use the showNewProd() function :


The parameter signifies the number of products you want to display. In the above example the function will display the most recent 5 products added to the database.

3.9. Top Sellers

To display a list of the best selling products in the store, use the showTopSell() function :

<%= showTopSell(5)%>

The parameter signifies the number of products you want to display. In the above example the function will display the top 5 best selling products.

3.10 Custom Pages

To display a list of defined extra pages in the store, use the showExtraPages() function:

<%= showExtraPages()%>

A custom page may also be displayed using the link <%=NonSSLUrl%>openExtra.asp?Extra=x where 'n' is the id of the custom page.

3.11. ASP Variables and Functions

Users who want to enhance the functionality of their pages with ASP and VBScript can also make use of several predefined variables and functions (see the default version of _INCtemplate_.asp for examples on proper usage). Some of the variables and functions at your disposal are :

4. General Notes (TOP)

4.1. Product Images

Product Images can be uploaded with the Upload Utility provided with this software, FTP or any other web authoring package you have. Note that you may create a product on the database without any images. Each product can have two images. A small "thumbnail" version of the product image, and a regular sized version of the product image. The product maintenance functions provide for the entry of both these files. The thumbnail version is displayed in the product list pages, while the regular sized version is displayed when the customer looks at the product detail. You should stick to ".gif" or ".jpg" files for these images because those are the most widely supported image file formats.

4.2. Software Downloads

The downloadable software products that you intend to sell through your store can be uploaded with the Upload Utility or any good FTP software. The product maintenance functions provide for the entry of the filename of the downloadable product as part of the product record. When a customer orders a downloadable product, they will be able to download the product by logging on to their Account and clicking on the order. This system gets rid of the problematic email system employed by so many other Shopping Cart packages. The system automatically checks to see if the order has been paid, before allowing the download.

4.3. Security 

Security of your data is important. Since most stores run on shared web hosting accounts, your web host is responsible for the most important task - namely securing the web server itself. The vast majority of hackers will gain access to your web site via FTP, or via an unpatched operating system exploit. That is why it is important to make sure that your web host has a good reputation for security, since they are responsible for securing the FTP servers and applying patches. However, there are some things YOU should do to minimize the risk to your web site :

5. Upgrading from previous versions (TOP)

5.1. Install CP 6.0  from 5.1 - There have been numerous changes to the scripts files in support of XHTML and CSS so we strongly recommend that you follow our recommendation of installing CP6.0 to a new folder under your root then doing a folder name swap to bring it to production.

The major change for upgrading will be that your template may will need to be redesigned to utilize the XHTML / CSS design template and layout. If that is difficult for you at this time you may use your existing template but will need to utilize the layout css files contained in usermods/templates/legacy.

5.2. That's it! You're done. If necessary, re-apply any changes you may have made to the scripts and storefront template.

5.3. Test your store - Make sure that you are still able to write to the database and send emails, etc. Enter a few orders to ensure that everything is working as expected.

5.4. Backup - your prior installation and archive.

5.5. Change Folder Names - If you installed to a different folder as recommend and you're existing store is in a folder, rename the existing folder then rename the 5.1 installation folder then name of the prior versions folder, thus maintaining search engine links etc.

6. Applying Updates (TOP)

6.1 Install the updated distribution to a new folder

6.2 Move your existing usermods/_INCtemplate_.asp to the new installation

6.3 Update your existing database with the store cofiguration variables shown in the change history by using Admin | Developer tools | Configuration Variables

6.4 If using an Access database move your database to the new installation

6.5 Move the config/config.asp file to the new installation and modify the connection string to point to the database if necessary.

6.6 In your browser go to Admin | Store Configuration | URL & Folders and change the URL locations.

6.7 Test the store and when satisfied rename the prior installation folder and name the current installation folder to the priors.

1. The "Change History" in the readme.htm (this file) lists all updated files and any additional variables in the store configuration.

If you use a common location for the database (Access) or use SQL then you only need to move the config/config.asp to the new folder.


7. Acknowledgements (TOP)

1. MD5 Digest Routine was written by

2. RC4 Routine was written by Mike Shaffer and can be found at

3. Parts of database structure, SQL logic and SQL command tool based on Comersus Cart .

4. Image resize routines Copyright  Mike Shaffer

5. LightBox Image Routines

6. Theme and layout by copyright held by Cavallo Communications, LLC.


 8. Change History

May. 24, 2010 CP6.2.0.0

Name = pGoEMFrontEnd
Type = LongInteger
Value = -1

Name = goEMLogin
Type = String
Value = 999999

Name = goEMPassword
Type = String
Value = password

Name = pGoEMerchant
Type = String
Value = 0

Name = payModeGoEMerchant
Type = String
Value = -1

Name = PayMsgGoEMerchant
Type = String
Value = GoEMerchant

Name = goEMCurrCode
Type = String
Value = USD

Name = feeGoEMerchant
Type = Double
Value = 0

Name = pGoEMTest
Type = String
Value = N

Field = GatewayName
Value = payMsgGoEMerchant

Field = GatewayPayin
Value = 50_GoEMerchant

Field = GatewayPayout
Value = 60_GoEMerchant

Field = GatewayActive
Value = pGoEMerchant

Field = feePayment
Value = FeeGOEMerchant


Apr. 5, 2010 CP6.1.0.2

Feb. 27, 2010 CP6.0.0.4

Aug 8, 2009 CP5.1.1.8

May 22, 2009 CP5.1.1.7

March 5, 2009 CP5.1.1.6

February 22,  2009  Initial release of CP5.1.1.5

Name = pPhoneOptional
Type = String
Value = N

Name = pShipPhoneOptional
Type = String
Value = N

Name = pListResizeImages
Type = String
Value = 0

Name = pViewResizeImages
Type = String
Value = 0

Name = pThumbResizeImages
Type = String
Value = 0

Name = pWList
Type = Long Integer
Value = 175

Name = pHList
Type = Long Integer
Value = 175

Name = pWView
Type = Long Integer
Value = 250

Name = pHView
Type = Long Integer
Value = 250

Name = pWThumb
Type = Long Integer
Value = 50

Name = pUseAdminSig
Type = String
Value = -1

Name = pGoogleAnalytics
Type = String
Value = blank

Name = pUseProdCart
Type = String
Value = -1

Name = pUserProdView
Type = String
Value = -1

Name = prodViewRecommendationsCount
Type = String
Value = 3

Name = prodCartRecommendationsCount
Type = String
Value = 6

Name = pCert
Type = String
Value = -1

Name = pIncrCert
Type = String
Value = 5

Name = pMinCert
Type = String
Value = 5

Name = pMaxCert
Type = String
Value = 100

Name = pMailPort
Type = String
Value = 2

A new table UOM was added to the database to support unit of measure handling.

A new table prodimages was added to the database to support multiple images per product

The database table products was modified to support a unit of measure reference to the UOM table in the database

The database table products was modified to support minimum product order quantity. Other columns were added in support of GST, VAT, and PST tax exemption at a future date.

The database tables cartrows and  products were modified to support product discount exemption.

 October 20, 2008 CP4.1.2.31


The database table extrapages must have the value of column extraDisplay changed to Y (checked) The SQL is UPDATE extrapages SET extradisplay = 'Y' Where extradisplay = 'checked' and  UPDATE extrapages SET extradisplay = 'N' Where NOT extradisplay = 'checked'

The database table cartrows must have the an additional column dlpassword char(15) added. The SQL is ALTER TABLE cartrows ADD COLUMN dlpassword TEXT(15)

Sept 2, 2008 CP

July 2,2008 CP

May 10, 2008

January 17, 2008

November 18, 2007

October 07, 2007

Sept 17, 2007


Sept 10, 2007

Type = String 
Value =

 August 17, 2007 CP

August 06, 2007