Commerce.cgi 2.01 Commerce.cgi 2.01 is distributed according to the GNU General Public License. No free support is offered for this product. We wish we could help everyone, but it's just not possible. There is a mailing list available for users to assist other users. You can subscribe to the mailing list by visiting: http://www.onelist.com/subscribe/commerce.cgi ################################################################ Installation Installation requires three files 1) readme.txt (this file) 2) commercecgi.tar - the unix tar file containing all of the Commerce.cgi files 3) install.txt - a simple cgi program that will untar commercecgi.tar ================================================================ **Step 1 - Upload (ftp) commercecgi.tar to your cgi-bin directory. Make absolutely sure that you ftp this file as a BINARY file!! **Step 2 - Rename install.txt to install.cgi and upload (ftp) this file to your cgi-bin directory. Make absolutely sure that you upload this as an ASCII file!! WARNING - Failure to transfer these files in the correct mode (ASCII or BINARY) is one of the most common causes of problems - TAKE YOUR TIME AND DO IT RIGHT :-) **Step 3 - Change the permissions on the file 'install.cgi' to 755. If you're unsure how to do this, take a few minutes to go through this excellent tutorial: http://www.mattkruse.com/info/cgi/ Now you're ready to untar (decompress) the commercecgi.tar file. (Be aware that doing this will create a directory called /store within the cgi-bin. If you already have a directory called /store in the cgi-bin, you may want to create a new directory in the /cgi-bin and repeat Steps 1, 2 and 3 using this new directory instead.) **Step 4 - Access the file install.cgi using your web browser. The URL is probably something like: http://www.your_domain.com/cgi-bin/install.cgi Hopefully you should see this message: "Excellent! It appears that you have successfully installed Commerce.cgi!" If you receive an error when you access install.cgi, check the permissions on the file, and make sure that you uploaded this file in ASCII mode. !!IMPORTANT!! Once the commercecgi.tar file has been successfully decompressed, it is VERY important that you IMMEDIATELY disable install.cgi. Rename it back to install.txt, or delete it entirely (you can always download it again from our site). While your at it, you should also rename or delete commercecgi.tar too! Why is this important? Only because if you accidentally run it again in the future, you could overwrite all of the great changes you've made to your store. RENAME THESE FILES NOW! ################################################################ **Before Doing Anything Else** The file 'commerce.cgi' is located in the /store directory The file 'manager.cgi' is located in the /store/protected directory Make sure that the first lines of manager.cgi and commerce.cgi contain the correct path to perl on your system. This line should look something like: #!/usr/bin/perl -T It is *very* important that you use perl version 5. Some systems have both version 4 and version 5 installed in different locations for backwards compatibilty. The scripts may appear to run with perl 4, but you will encounter weird errors along the way. If you're unsure, ask your Systems Administrator for the correct path. -----Enabling Store Manager----- Next, to get the store up and running, you will need to enable the Store Manager. While the Store Manager itself uses simple password protection, for greater security you *must* also password protect the /store/protected directory. **REPEAT - YOU MUST PASSWORD PROTECT THE /store/protected directory! If you are unsure how to do this, ask your System Administrator to help you...they should be able to offer you a way to password protect this directory, possibly through your website 'Control Panel', assuming you have host that provides such tools... While you're waiting to hear from your SysAdmin, you need to enable the secondary password protection within Store Manager. 1) Open up the manager.cgi file in a text editor and change the username and password variables at the top. The file contains directions to walk you through this. 2) The program stores your I.P. address in a temporary file to keep track of you during your visit. You must rename this file to something unique that you choose by setting the $a_unique_name variable to whatever name you like. DO NOT skip over this step! If you find the login page just reloads itself over and over, this is one possible reason why that is happening. **Last warning: Don't forget to password protect the /protected directory as soon as possible! Now you must set a few important pieces of information unique to your store. Access the 'Program Settings' section of Store Manager through your Web Browser by accessing this URL" http://www.your_domain.com/cgi-bin/store/protected/manager.cgi?welcome_screen=yes Obviously, you need to change this to reflect your specific URL and path. If you leave off the '?welcome_screen=yes' part of the URL, a blank page will be returned, so make sure to use the correct URL to access Store Manager. -----Using Store Manager to set the Program Settings----- Login to Store Manager and select the 'Program Settings'. After successfully logging in you will be taken directly to the 'Add A Product' screen of Store Manager. Click the 'Program Settings' link at the top of the page. The 'Program Settings' screen allows you to easily set certain configuration variables for your store. We'll go through each of these choices one by one... 1) 'Please choose how you will process orders' Here you choose how you'd like to process your orders. This selection is new in Commerce.cgi 2.0 and allows you to choose either 'Offline', "AuthorizeNet', 'iTransact' or 'LinkPoint HTML'. 'Offline' simply means that you'd like to have your orders logged and you will process them offline through your own credit card software. When using 'Offline' processing, the order is logged to a text file on the server and also e-mailed to the merchant. For security, the text file on the server will contain the type of credit card that is being used and the first eight digits of the credit card number. The e-mailed copy of the order that is sent to the merchant will contain the last eight digits of the credit card number, and the expiration date. While it is a housekeeping chore to collate these two files to obtain the full credit card information, it is also more secure. Many people have problems setting up PGP encryption on their server, so this seemed to be a resonable alternative. If this process doesn't work for you, you may want to consider using real time credit card processing. Commerce.cgi 2.0 currently allows you to use choose from AuthorizeNet, iTransact, or LinkPoint HTML. Whether you choose 'Offline', 'AuthorizeNet', 'iTransact', or 'LinkPoint HTML', you will need to enter some additional information in the new "Gateway Settings' screen. We'll learn more about this after we get through the rest of the 'Program Settings'.... 2) 'Please enter the full URL of your /images directory. For example: http://www.careyinternet.com/cgi-bin/store/html/images DO NOT include the trailing slash!!' Commerce.cgi 2.0 does away with the annoying 'Path To Html' variable that we used in the 1.02 version. Now, if you find that you cannot serve images from your /cgi-bin directory, you can simply create an images directory somewhere else on your server and enter the URL to that directory here. Just as it says, DO NOT include the trailing slash in the URL! 3) 'Please enter the full URL of your store here: (ex: http://www.careyinternet.com/cgi-bin/store/commerce.cgi)' To help fix another annoying problem from version 1.x, we've added some regular expressions into Store Manager to calculate your cookie settings. Now you can just enter the full URL to your store here and the cookie settings should be all set. One important note: Cookies are very particular and need to be set carefully. Specifically, take a look at these two URLs http://www.careyinternet.com/cgi-bin/store/commerce.cgi http://careyinternet.com/cgi-bin/store/commerce.cgi If you drop the 'www' from your URL in this setting, and then try and access your Store using the 'www' in the URL, you'll find that the cookie won't be set. Similarly, if you include the 'www' in this setting, but access the Store without using the 'www' in the URL, the cookie won't be set. Just be consistent with how you use your URL and you shouldn't have any problems. If you're worried that visitors to your Store may drop the 'www' on their own, just make sure that all the links on your frontpage include the 'www' and then the cookie will be set when they click through.... 4) 'Customers from the state selected here will be charged sales tax' This is self explanatory. Orders that are SHIPPED to this state will be charged sales tax. 5) 'Enter sales tax percentage here. Enter as a decimal number. Ex: ".05" for "5%", ".06" for "6%", etc.' Orders that are shipped to the state selcted above will have this percentage added to the order for sales tax. 6) 'Do you wish to have orders e-mailed to you?' Answer 'yes' to this... 7) 'Enter the e-mail address where you'd like the orders sent' Self explanatory - just make sure that it's an address that is reliable. 8) 'Do you wish to have the orders written to a log file?' Answer yes to this too... 9) 'Choose a unique name for your log file. (ex: "mylog3218.txt")' This is *very* important. Make up an odd name that only you will remember...use letters and numbers. This file will contain your order data and will be located in the /cgi-bin/store/log_files directory. It is a wise idea to password protect this directory! 10)'Enter the e-mail address of your webmaster or administrator here' This is the e-mail address that appears as the return address when the customer is sent an order confirmation e-mail. A customer service e-mail address is a good choice for this.... ----------------------------------------------------------------- Once you have entered all of the data above, you can click the 'Submit' button. You should see a message stating: 'System settings have been successfully updated. Check your Gateway Settings here' Click the 'Gateway Settings' link. Depending upon how you've decided to process orders, you will be asked for certain information.... ----------------------------------------------------------------- **Offline Processing If you've chosen to process your orders offline, you will only be asked to enter one more piece of data 1) 'Please enter the Secure URL to your commerce.cgi store.' Because you are collecting credit card data, you really should have a secure connection when that data is sent from the orderform to the server. Commerce.cgi requires that the secure URL is accessing the exact same commerce.cgi file as the standard URL. For example: http://www.careyinternet.com/cgi-bin/store/commerce.cgi http://server6000.net/careyinternet/cgi-bin/store/commerce.cgi Both access the same exact file, one is through a standard http connection, the other is through a secure https connection. If you're hosting company expects you to put secure files on a different machine, commerce.cgi will not work. If they want you to put secure files in a special directory, you *may* be able to creat a softlink from the secure directory to the directory containing commerce.cgi. Ask your Server Administrator for assitance. Hopefully, you will simply be able to enter the secure URL and you'll be all set.... ----------------------------------------------------------------- **AuthorizeNet Processing If you've chosen to use AuthorizeNet, you'll be asked to enter some additional information. Most of it is self explanatory, and will be used to customize the AuthorizeNet orderform. It is no longer necessary for you to have a secure server on your end to use Commerce.cgi with AuthorizeNet. All order data is now collected on the AuthorizeNet secure server... 1) 'Gateway Username' Enter a valid username provided to you by AuthorizeNet 2) 'Secure URL to your Gateway's server' This is most likely: https://secure.authorize.net/gateway/transact.dll 3) 'Complete URL to the logo you'd like to display on your orderform. This MUST be a secure https URL. You can also leave this blank if you prefer.' This is self explanatory. If you choose to include this, just make sure it is a SECURE url or you'll have problems. 4) 'Background color of your orderform.' 5) 'Text Color' 6) 'Link Color' These three are all self explanatory customization variables.... 7) 'Enter the text that you'd like displayed at the top of your orderform.' 8) 'Enter the text that you'd like displayed at the bottom of your orderform.' Self explanatory.... 9) 'Enter the text that you'd like displayed at the top of your receipt page.' 10) 'Enter the text that you'd like displayed at the bottom of your receipt page.' Self explanatory... 11) 'Enter the text that you'd like displayed at the top of your customer's e-mail receipt.' 12) 'Enter the text that you'd like displayed at the bottom of your customer's e-mail receipt.' The e-mail receipt is sent to the customer by AuthorizeNet after the order is processed. ----------------------------------------------------------------- **iTransact Processing If you've chosen to use iTransact, you'll be asked to enter some additional information. Most of it is self explanatory, and will be used to customize the iTransact orderform. It is no longer necessary for you to have a secure server on your end to use Commerce.cgi with iTransact. All order data is now collected on the iTransact secure server... 1) 'Gateway Username' Enter your valid username provided to you by iTransact 2) 'Secure URL to your Gateway's server' This is most likely: https://secure.itransact.com/cgi-bin/mas/split.cgi 3) 'Enter the name of your business here.' Self explanatory 4) 'Are setup to accept credit cards through iTransact? Select '0' for no, '1' for yes.' 5) 'Are you setup to accept checks through iTransact? Select '0' for no, '1' for yes.' 6) 'Are you setup to accept EFT through iTransact? Select '0' for no, '1' for yes.' These three variables need to be answered correctly for your specific account. If you are unsure of any of these, contact iTransact support for assistance. 7) 'Do you want to allow customers to enter an alternate shipping address? Select '0' for no, '1' for yes.' If you answer yes to this, the iTransact orderform will allow customers to enter a shipping address that is different from the billing address. Depending on your business, you may or may not want to allow this... 8) 'Enter the text that you'd like to appear in the body of the confirmation e-mail sent to the customer.' This is the e-mail that is sent to the customer by iTransact after the order is processed. ----------------------------------------------------------------- **LinkPoint HTML Processing If you've chosen to use LinkPoint HTML, you'll be asked to enter some additional information. 1) Gateway Username Enter your valid username provided to you by Cardservice International 2) Secure URL to your Gateway's server This is most likely 'https://secure.linkpt.net/cgi-bin/hlppay' --->LinkPoint HTML Administration Program<--- To use Commerce.cgi with LinkPoint HTML, you will also need to login to your LinkPoint HTML Administration Program and make a few changes. The LinkPoint HTML Administration Program can be accessed at the URL provided to you by Cardservice Internation in your Welcome Letter. 1) Receipt's top 2) Receipt's bottom The text entered for 'Receipt's top' and 'Receipt's bottom' will appear on both the customers confirmation e-mail, and the receipt page displayed after the order is placed. 3) Order Submission Form URL Enter the URL of your order submission form - the web page from which control is passed to the secure web server for card processing. This enables a check of the referring web page for each transaction, in order to prevent fraud. For example: http://www.yourserver.com/yourstorename/yourorderform.html or if you are using a secure web server: https://www.yourserver.com/yourstorename/yourorderform.html or if you are generating the form in a CGI: http://www.yourserver.com/yourstorename/yourorderform.cgi 4) "Thank You" Page URL Enter the URL of your "Thank You" page - the web page where you want to take a customer if a transaction was approved. This should be the full URL to your Commerce.cgi store (preferably, this should be a secure URL to avoid browser warnings after the order is processed.) 5) Check here if this url is a CGI script. 6) Check if you wish to automatically display specified URL after the LinkPoint HTML receipt page. Numbers 5 and 6 are check boxes....you should check them both! 7) "Sorry" Page URL Enter the URL of your "Sorry" page - the web page where you want to take a customer if a transaction was declined and the customer decided not to try again/canceled the order. 8) Check here if this url is a CGI script. 9) Check if you wish to automatically display specified URL after the LinkPoint HTML receipt page Numbers 8 and 9 are check boxes. Check Number 8 if your 'sorry' page is a cgi script. Check Number 9 to automatically redirect the customer to your 'sorry' page when their order is declined. 10) Company Logo Graphics URL Enter the URL of your company logo graphics if you want it to be displayed at the top of each page. This URL must point to a secure site, use HTTPS protocol. Please make sure that your image fits the page. 11) Background Graphics URL Enter the URL of your background graphics if you want to substitute the default one. This URL must point to a secure site, use HTTPS protocol. 12) Company Name Enter your company's or store's name here. It will be displayed at the top of each page. You can enter up to 30 characters including spaces. 13) Custom Fields It is VERY important that you enter the following 6 Customer Fields exactly as listed. Do *NOT* click the check box to make them 'viewable' Enter these in the 'Name' column ordnum custnum shippingamount shippingmethod subtotalamount salestaxamount Captions for these are not required, but you can enter these if you like in the 'Caption' column Order Number Customer Number Shipping Price Shipping Method Subtotal Sales Tax 14) Customer's Receipt Check here if you would like to receive a copy of each receipt ----------------------------------------------------------------- Adding Products To Your Datafile Although there is no set limit to the amount of products that can be maintained by Store Manager (or used by Commerce.cgi), we generally recommend that you use caution (100 to 200 products max). This is for performance reasons, mostly. Nothing is programmed into manager.cgi or commerce.cgi to limit the amount of products, but you may see server performance problems if your datafile becomes too big....just be careful and consider yourselves warned :-) The 'Add A Product' screen of Store Manager can be access here: http://www.careyinternet.com/dev/cgi-bin/store/protected/manager.cgi?add_screen=yes Obviously, you need to change this to reflect your specific URL and path. 1) Reference # - This value is entered automatically by Store Manager. This is not a SKU number, but simply a unique number needed by Commerce.cgi to identify this particular product 2) Category - This should be one word only, no spaces 3) Price - just the numeric price, no $ sign needed 4) Product Name - two or three words to identify the product. This value is displayed in the shopping cart. 5) Image File - This is just the name of the image file, not the complete URL or path! If you've correctly set the 'URL To Images' field in the Program Settings screen, you this image should display correctly on your Commerce.cgi product pages. 6) Option File - the filename of your options file NOT the complete URL or path. The options files are located in the /store/html/options directory. Check out the sample file called gift_option.html for reference. 7) Shipping Price - This should be set to your base shipping price for each product. See the 'Shipping' Price section of this Read Me for more complete details. 8) User Defined Field One through Five - these five fields allow you to store up to five pieces of data that can be displayed on your product pages by placing 'tokens' within the productPage.inc file. These are defined in the upcoming discussion called "Editing the look and feel of your product pages" 9) Description - This is where you enter the description and information about the product. HTML can be included here as well.. ----------------------------------------------------------------- Editing Products Within Your Datafile The Edit Product screen can be accessed here: http://www.careyinternet.com/dev/cgi-bin/store/protected/manager.cgi?edit_screen=yes Obviously, you need to change this to reflect your specific URL and path. Here you will select the product you wish to edit, and then you will be taked to a form similar to the Add A Product form where you can make your changes. ----------------------------------------------------------------- Deleting Products From Your Datafile The Edit Product screen can be accessed here: http://www.careyinternet.com/dev/cgi-bin/store/protected/manager.cgi?delete_screen=yes Obviously, you need to change this to reflect your specific URL and path. Here you will select the product you wish to delete. Use this screen with care!! ----------------------------------------------------------------- Shipping Price As mentioned in the 'Adding Products To Your Datafile' section of this Read Me, every product has a fixed 'base shipping' price assigned in the datafile. To add some additional flexibilty, there is now a way to add in additional levels of 'upgrade' shipping. First, you will need to determine which orderform you are using. This is dependent upon how you are processing your orders. Look in the /store/html directory and you'll notice four files named *-orderform.html, They are: AuthorizeNet-orderform.html iTransact-orderform.html Linkpoint-orderform.html Offline-orderform.html Choose the orderform that matches your method of order processing, download this file in ascii mode and open it up in your text editor. Look for this SELECT box: This is where you'll add your levels of upgraded shipping. Notice how the "VALUE=" statements contain pipe delimited data such as 5|U.P.S. Two Day - Upgrade The '5' indicates 5% will be added to the base shipping price defined in the datafile. The 'U.P.S. Two Day - Upgrade' is the method of shipping that will be recorded with the order. ----------------------------------------------------------------- Adding your Header, Footer, and Frontpage The header and footer is displayed on all of your dynamic product pages. There are separate header and footer files which are displayed on the orderform, allowing you to include secure links to images more easily. The frontpage is simply a static HTML page that is parsed by the script and displayed when commerce.cgi is accessed. 1) Create your standard header HTML and save it in a file called store_header.inc. This file should NOT include or tags - use the sample store_header.inc as a guide. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 2) Create your secure header HTML and save it in a file called secure_store_header.inc. This file should NOT include or tags - use the sample secure_store_header.inc as a guide. This file can contain secure links to images if needed. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 3) Create your standard footer HTML and save it in a file called store_footer.inc. This file should NOT include or tags - use the sample store_footer.inc as a guide. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 4) Create your secure footer HTML and save it in a file called secure_store_footer.inc. This file should NOT include or tags - use the sample secure_store_footer.inc as a guide. This file can contain secure links to images if needed. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 5) Create your Frontpage HTML and save it in a file called frontpage.html. Upload this file and place it in the directory /cgi-bin/store/html. ----------------------------------------------------------------- Editing the look and feel of your product pages We've tried to make it a little easier for desigers to edit the look and feel of the product pages. There are now template files located in the /cgi-bin/store/html/html-templates directory which will allow you to edit various parts of the product page without digging through the script. The template files are: cart_footer.inc change_quantity_footer.inc delete_items_footer.inc productPage.inc secure_store_footer.inc secure_store_header.inc store_footer.inc store_header.inc The productPage.inc template allows you to drop 'tokens' into the file to easily display product data from the datafile. Here are the possible values... %%image%% %%name%% %%description%% %%price%% %%shippingPrice%% %%userFieldOne%% %%userFieldTwo%% %%userFieldThree%% %%userFieldFour%% %%userFieldFive%% Please note: these tokens are for display only - these values are not included in your order log or confirmation e-mails.