Open-source Shopping Cart Solutions

Open-Source Shopping Cart Solutions Installation information for integrating a shopping cart with Checkout by Amazon using open-source solutions

© 2008-10 Amazon.com, Inc. or its Affiliates

Table of Contents 1

Open-source Cart Solutions .................................................................................................................1 1.1 Other Documentation...................................................................................................................1 1.2 What’s New in This Document .................................................................................................... 2 2 osCommerce Plug-in V 1.0 ................................................................................................................... 3 2.1 Updates ........................................................................................................................................ 3 2.2 README.txt.................................................................................................................................. 3 2.3 INSTALLATION_GUIDE.txt .......................................................................................................... 8 3 Zen Cart ............................................................................................................................................... 13 3.1 Updates .......................................................................................................................................13 3.2 README.txt.................................................................................................................................13 3.3 INSTALLATION_GUIDE.txt ........................................................................................................ 18

ii

Open-Source Shopping Cart Solutions

1

Open-source Cart Solutions

You can integrate with the third-party cart integration solution of your choice. For your convenience, we provide code samples for two open-source cart providers, osCommerce and Zencart. You can download zipped files using the links below: •

osCommerce solution (v 2008_11_11_1.11) (http://www.oscommerce.com/)

•

Zencart solution (v 2008_12_03_1.10) (http://www.zen-cart.com/index.php)

The following pages contain basic instructions for using these cart solutions. Notes If you use these plugins, remember that you will use Seller Central for your order management. When you integrate your cart with Checkout by Amazon, you will need to use your Merchant ID in your cart. Your Merchant ID is a 14-character string, similar to this: A1B2C3D4E5F6G7. Here are the steps to view your Merchant ID in Seller Central: 1. Click the Settings tab. 2. Click Checkout Order Pipeline. 3. View your Merchant ID. Your Merchant ID is not the same as your Merchant Token, which is used for applications such as ASON.

1.1

Other Documentation

You can read our downloadable files (PDF) to understand more about Checkout by Amazon.

1

© 2008-11 Amazon.com, Inc. or its Affiliates Resource Getting Started Guide (PDF)

Implementation Guide Using the Create Checkout Button Feature (PDF) Implementation Guide Using HTML-based Button Code and Shopping Carts (PDF) Implementation Guide Using XML-based Button Code and Shopping Carts (PDF) Best Practices Guide (PDF) Launch Checklist (PDF) Callback API Guide (PDF) Instant Order Processing Notifications API Guide (PDF) Using Custom Data Fields (PDF) Open-Source Shopping Cart Solutions (PDF) Installing and Configuring the osCommerce Plug-in (PDF)

Audience, Purpose, and Goals For merchants who want to use a simple, step-by-step approach in setting up Checkout by Amazon on their websites, from start to finish. The Getting Started Guide walks merchants through the process, from gathering the required information for signing up for an account setting up a button on their websites. For merchants who want detailed information about integrating their website with Checkout by Amazon using the Create Checkout Button feature in Seller Central. Designed for a simple copy-and-paste HTML solution for your webpages. For merchants and developers who want detailed information about integrating their website with Checkout by Amazon using HTML-based buttons and shopping carts. Designed for HTML-based integration. For merchants and developers who want detailed information about integrating their website with Checkout by Amazon using XML-based buttons and shopping carts. Designed for XML-based integration. Contains the best tips for merchants who want to set up their websites to use Amazon Payments, with advice for planning, setting up, and day-to-day operations. For merchants and developers planning to set up and use Checkout by Amazon on their site. For developers who want to build their own applications to calculate shipping and tax rates as well as promotional discounts and then send these results to Checkout by Amazon. For developers who want to automate order notifications with Amazon Payments. For merchants and developers who want to include custom data fields in their carts. For developers interested in open-source carts that support Checkout by Amazon (currently osCommerce 1.x and Zen Cart). For developers interested in the osCommerce open source cart, v. 2.0 and greater.

1.2

What’s New in This Document

Ver 2.1

Date 2014-06-03

1.8 1.7 1.6 1.5 1.0

2014-03-27 2011-10-31 2010-08-09 2009-03-05 2008-07-29

2

Changes Updated references to a menu option “Access Key” to “MWS Access Key”. Updated, or removed out dated, broken links. Clarification of access and secret access keys. Updated to reflect current functionality. Updated Zen Cart Plug-in to support several new features. Updated the osCommerce Plug-in V 1.0 section to include link to newer 2.0 solution. Initial release.

Open-Source Shopping Cart Solutions

2

osCommerce Plug-in V 1.0

This section describes how to use the osCommerce Plug-in V 1.0. If you want to use the newer version of this plug-in, download and read Installing and Configuring the osCommerce Plug-in (PDF).

2.1

Updates

Update version 2014_03-27 2008_11_12_1_11

Problem Access and Secret Key information unclear. Cart allows description field of greater than 255 characters. Path found to bypass Checkout by Amazon.

2008_09_29_1_10

Plug-in allows 4-digit price. Cart sets weight to 0 and "LB" or drops weight value entirely.

Change Updated README.txt information. Long descriptions are cut off before being sent to Checkout by Amazon. Added Checkout by Amazon to login page. Only 2-digit price allowed. Sets weight to specified value and “lb”, not “LB”.

Here is the Readme and Installation Guide for the osCommerce Plug-in V 1.0:

2.2

README.txt CHECKOUT BY AMAZON PAYMENT MODULE FOR OSCOMMERCE Author: Allison Naaktgeboren Copyright: 2007-2008 Amazon Technologies, Inc. *-*-**-***-*****-********-************* *-*-**-***-*****-********-************* CONTENT SECTIONS (in order of appearance) *-*-**-***-*****-********-************* INTRODUCTION NOTICES FOR CERTAIN SOFTWARE COMPONENTS REQUIREMENTS RELEASE NOTES SETUP ON ADMIN UI SUPPORT & PROJECT HOME LINKS *-*-**-***-*****-********-************* INTRODUCTION *-*-**-***-*****-********-************* Please understand that by installing Checkout by Amazon Payment Module for osCommerce, you are agreeing to understand and abide by the terms of the license, as written in LICENSE.txt. Important links are grouped together in a separate section for your convenience. The most current documentation on Checkout by Amazon can be found on its website. *-*-**-***-*****-********-************* NOTICES FOR CERTAIN SOFTWARE COMPONENTS *-*-**-***-*****-********-************* 1. Notices for Software Components Licensed Under the GNU General Public License. The following are notices for software components that are free software licensed under version 2 of the GNU General Public License (the “GPL”), the full text of which is set forth in the LICENSE.TXT file accompanying

3

© 2008-11 Amazon.com, Inc. or its Affiliates this package, as published by the Free Software Foundation (such software, collectively, the “GPL Software”). Portions of these software components have been modified by Amazon.com in order to function with Amazon's Checkout by Amazon service. a.

Modification Notice.

The GPL Software has been modified [2007-2008].

b.

Terms Applicable to the GPL.

The full text of the GPL is set forth in the LICENSE.TXT file accompanying this package. You may redistribute the GPL Software and/or modify it under the terms of the GPL. The GPL Software is distributed WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. You may, for a period of up to three years, obtain, for a charge equal to the cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code. See the terms of the GPL for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. c. Name and Copyright Notice. The following are the names of the GPL Software and the applicable copyright notices: - osCommerce Online Merchant (c) 2000-2008 osCommerce - Zen Cart (c) 2003-2008 Zen Ventures LLC - XmlBuilder.php (c) 2006 Google Inc. 2.

Notices for Software Components Licensed Under the PHP license.

The following are notices for software components that are free software licensed under the PHP License version 3.0 (such software, collectively, the “PHP Software”). a. Terms Applicable to the PHP Software. The PHP Software includes PHP, freely available from http://www.php.net/. Redistribution and use of the PHP Software, in source and binary forms, with or without modification, is permitted provided that the following conditions are met: 1.

Redistributions of source code must retain the following copyright notice, this list of conditions and the following disclaimer. "Copyright (c) 1999 - 2006 The PHP Group. All rights reserved."

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The name "PHP" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. 4. Products derived from this software may not be called "PHP", nor may "PHP" appear in their name, without prior written permission from [email protected]. You may indicate that your software works in conjunction with PHP by saying "Foo for PHP" instead of calling it "PHP Foo" or "phpfoo"

4

Open-Source Shopping Cart Solutions

5. The PHP Group may publish revised and/or new versions of the license from time to time. Each version will be given a distinguishing version number. Once covered code has been published under a particular version of the license, you may always continue to use it under the terms of that version. You may also choose to use such covered code under the terms of any subsequent version of the license published by the PHP Group. No one other than the PHP Group has the right to modify the terms applicable to covered code created under this License. 6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes PHP, freely available from ". THIS SOFTWARE IS PROVIDED BY THE PHP DEVELOPMENT TEAM ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PHP DEVELOPMENT TEAM OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. b.

Name and Copyright Notice.

The following is the name of the PHP Software and the relevant copyright notices. - HMAC.php (c) 1997-2005 The PHP Group. All rights reserved.

*-*-**-***-*****-********-************* REQUIREMENTS *-*-**-***-*****-********-************* (1) osCommerce 2.2rc2a must be installed Other versions are untested. (2) Seller account from Amazon.com Please see Seller Central website in "LINKS" section of this document. *-*-**-***-*****-********-************* RELEASE NOTES *-*-**-***-*****-********-************* (1) Carefully follow all instructions in INSTALLATION_GUIDE.txt (2) You must have set up an Amazon Seller account & have your merchantID. (a) Log in to Seller Central (b) Click Settings > Checkout Pipeline Settings (c) View your Merchant ID on the Checkout Pipeline Settings page. (3) It is strongly encouraged to generate keys from Seller Central, and have your key ready to enable signed orders. Unsigned orders are very vulnerable to fraud. (4) Note that Checkout by Amazon standards do not allow weights of products to be 0 at this time. Thus, a weight tag = 0 will be removed from the XML cart before the order is processed (5) Please note that if you choose to use your own checkout success page, as discussed below, YOU are responsible for clearing the contents of the

5

© 2008-11 Amazon.com, Inc. or its Affiliates customer cart, as identified by ClientRequestId. If you wish to create your own success return page and use the popup order summary from Checkout by Amazon, you will need to include the necessary scripts. (6) The orders that are processed through Checkout by Amazon will not appear in the osCommerce records or database. Please log in to Seller Central to review the orders processed though Checkout by Amazon. (7) Checkout by Amazon does not at this time support the tax or shipping settings in osCommerce. You, the seller, will need to be sure that your desired tax and shipping rates are configured in Seller Central. (8) The price that is included in the XML carts sent to Checkout by Amazon from osCommerce includes promotion prices set in osCommerce, .i.e. the promotion has already been applied to the item. If you, the seller, also configure promotions in Seller Central, these will be applied in addition to the promotion from osCommerce. (9) Please note that the SKU, Title, & Description fields of products may be truncated when building the Checkout by Amazon cart. This is to comply with the standards set by Checkout by Amazon. Please see the Checkout by Amazon documentation in "LINKS" section below. *-*-**-***-*****-********-************* SETUP ON ADMIN UI *-*-**-***-*****-********-************* --Login in as the Administrator --click on 'Modules" tab on left hand side menu --click on "Checkout by Amazon" in the module list --click the "install" button the right hand side --click on the "edit" button --enter the following fields: ----Checkout button size This determines size of the Checkout icon. ----Button style This option determines style & color of the Checkout icon ----Enable Checkout by Amazon module This must be set to "true" to use Checkout by Amazon ----Sort Order display This determines how displays should be sorted ----Checkout by Amazon Merchant ID This field is required to enable Checkout by Amazon. You receive this ID when you sign up for an Amazon Seller account. ----Enable order signing We strongly encourage you to use signed orders. Unsigned orders are vulnerable to fraud. This is required if you wish to enable Fulfillment by Amazon. (Please see "Fulfillment by Amazon section below) ----Secret Key This value is required for creating signed orders. Please treat the secret key like a password. It is paired with the MWS Access Key. You must sign up for a key with Amazon Marketplace Web Services (MWS) website. Please see the "LINKS" section below. ----Access Key This value is required for creating signed orders. This key is paired to the Secret Key, but does not need to be protected like a password. You must sign up for your keys with Amazon Marketplace Web Services (MWS) website. Please see the "LINKS" section below. ----Operating Environment Sandbox - testing environment for your convenience. Transactions are not actually processed. You are encouraged to test Checkout by Amazon on your site before fully enabling the module. When in Sandbox mode, a

6

Open-Source Shopping Cart Solutions warning will appear below the Checkout by Amazon icon on the shopping cart page. Production - fully enabled environment. Transactions will be processed ----Cart Expiration Time This is an optional setting. It is the amount of time before a customer's cart expires, and is reset. If you choose not to set this value, the cart will not expire. ----Fulfillment by Amazon Select whether you, the seller, will fill your orders, or participate in "Fulfillment by Amazon" program. Please see Amazon's Seller Central for more information. ----Cancelation Return Page The page you would like customers to return to if they choose the cancel the order in the Checkout by Amazon pipeline. The default setting will return your customers to the catalog index page. This will not clear the customer cart. ----Success Return Page The page you want customers to return when they successfully complete an order in the Checkout by Amazon pipeline. The default setting will return your customers to the index page in your osCommerce store. This assumes that you have modied index.php as per the INSTALLATION_GUIDE to include the Amazon code. Redirecting to the osCommerce page 'checkout_success.php' will not work because osCommerce requires customers to have logged in, which they do not do in the Checkout by Amazon process. Please note that if you choose to use your own checkout success page, YOU are responsible for clearing the contents of the customer cart, which is identified by ClientRequestID. If you want to create your own success return page and use the popup order summary from Checkout by Amazon, you will need to include the necessary scripts. --Click the "Update" button at bottom of page --Review your site --You are strongly encouraged to test a couple of orders in the "Sandbox" environment before enabling "Production" environment *-*-**-***-*****-********-************* SUPPORT & PROJECT HOME *-*-**-***-*****-********-************* The latest documentation on Checkout by Amazon can be found at in the LINKS section below. Documentation for osCommerce integration can be found on the Amazon Seller Community website, under Amazon Payments Forums, titled "Integrating with osCommerce Cart" The latest version of Checkout by Amazon for osCommerce can be downloaded from the link below. *-*-**-***-*****-********-************* LINKS *-*-**-***-*****-********-************* Checkout by Amazon Documentation & Seller Central https://sellercentral.amazon.com/gp/help/ Amazon Marketplace Web Services (Amazon MWS) https://developer.amazonservices.com/index.html/186-5510975-5406814 Amazon Web Services http://www.amazon.com/webservices Amazon Seller Community Website http://www.amazonsellercommunity.com/forums/ Download Checkout by Amazon Payment Module for osCommerce http://amazonpayments.s3.amazonaws.com/documents/oscommerce_ checkoutbyamazon_plugin_2008_07_29.zip Fulfillment by Amazon https://sellercentral.amazon.com/gp/help/200144670

7

© 2008-11 Amazon.com, Inc. or its Affiliates

2.3

INSTALLATION_GUIDE.txt INSTALLATION INSTRUCTIONS: CHECKOUT BY AMAZON MODULE PAYMENT MODULE FOR OSCOMMERCE Author: Allison Naaktgeboren Copyright: 2007-2008 Amazon Technologies, Inc. *-*-**-***-*****-********-************* *-*-**-***-*****-********-************* INSTALLATION OPTIONS *-*-**-***-*****-********-************* Please note that by installing Checkout by Amazon Payment Module for osCommerce, you are agreeing to understand and abide by the terms of the license, as written in LICENSE.txt. You have two options for installing the Checkout by Amazon Payment module within osCommerce. If you have a fresh installation, please follow the directions in "FRESH INSTALLATION" below. If you already have an existing copy of osCommerce, please follow the directions in the section marked "EXISTING INSTALLATION". Please note, if you already have Google Checkout installed, the last step of the EXISTING INSTALLATION is different, please read the directions carefully. *-*-**-***-*****-********-************* FRESH INSTALL *-*-**-***-*****-********-************* Once you have a fresh installation of osCommerce, please copy the following files to the following directories: Copy /checkout_by_amazon/ & its contents to OSC_DIR/catalog/checkout_by_amazon/ Copy index.php to OSC_DIR/catalog/ This will overwrite the existing copy Copy shopping_cart.php to OSC_DIR/catalog/ This will overwrite the existing copy Copy checkout_payment.php to OSC_DIR/catalog/ This will overwrite the existing copy Copy login.php to OSC_DIR/catalog/ This will overwrite the existing copy PLEASE NOTE THAT THE FOLLOWING TWO FILES ARE DIFFERENT, BUT HAVE SAME NAME AND BELONG DIFFERENT PLACES. Copy checkout_by_amazon.php to OSC_DIR/catalog/includes/modules/payments/ Copy the english/modules/checkout_by_amazon.php to OSC_DIR/catalog/includes/languages/english/modules/payments/ Log in as Administrator in osCommerce's Administrator UI and follow the instructions, in README.txt. Please be sure to read the "Requirements" section as well. *-*-**-***-*****-********-************* EXISTING INSTALLATION, (INCLUDING WITH GOOGLE CHECKOUT INSTALLED) *-*-**-***-*****-********-************* To modify an existing installation to support Checkout by Amazon, you will need to install several new files and modify a few existing osCommerce files. New files: Copy /checkout_by_amazon/ & its contents to OSC_DIR/catalog/checkout_by_amazon/ Copy checkout_by_amazon.php to OSC_DIR/catalog/includes/modules/payments/ Copy the english/checkout_by_amazon.php to OSC_DIR/catalog/includes/languages/english/modules/payments/ Modifications to OSC_DIR/catalog/index.php: There are two changes needed in index.php. The first is the portion

8

Open-Source Shopping Cart Solutions of code which clears the customer carts in osCommerce. The second calls the scripts which present the customer with the Checkout by Amazon pop up containing their order details. Add, ~line 26 (before the closing ?> tag) the following code: // BEGIN CHECKOUT BY AMAZON CODE require_once("checkout_by_amazon/checkout_by_amazon_constants.php"); //emptying the cart if($HTTP_GET_VARS['amznPmtsReqId'] ){ $cart->reset(); } // END CHECKOUT BY AMAZON CODE Add, ~line 43, (before the tag), the following code: media="screen" rel="stylesheet" type="text/css"/> type="text/javascript"> /> With the following code:

9

© 2008-11 Amazon.com, Inc. or its Affiliates Modifications to OSC_DIR/catalog/login.php There are three changes, all are adding code. Add, ~line 14 (after require('includes/application_top.php'); ), the following code: require_once("checkout_by_amazon/checkout_by_amazon_constants.php"); Add, ~line 85 (before the tag), the following code: media="screen" rel="stylesheet" type="text/css"/> type="text/javascript"> Add, ~line 220 (before body_text_eof): Code before:

10

Open-Source Shopping Cart Solutions Code to add: Code after: