Gallery2:Modules:checkout

Lets users order items from G2 via email or buy them via PayPal, NoChex, or Google Checkout

Important Note: Checkout and its associated modules are neither related to nor compatible with the "cart" module included with the core distribution. You should use one or the other system, but not both. If you wish to use checkout please uninstall cart.

Second Important Note: The payment plugins like checkoutpaypal and checkoutemail - and all other checkout plugins like checkoutdownload etc. - require checkout to be installed as well. Install and configure checkout first, then add the other modules from the checkout series that you wish to use.

Third important note: zipcart isn't compatible with checkout. Use the checkoutdownload module if you want customers to download images from your Gallery.

There are extension modules that will download pdf invoices, allow customers to download images and also link purchased items to groups so when configured correctly people can buy access to other images/sizes/albums.

Version 0.4.3 of checkout is written and tested with Gallery 2.3.

Contributors to the module include dleaberr1, turnbulm, jayhen and alecmyers.

Installing the modules

Use the "get more plugins" tab via the admin/plugins page of your Gallery installation. Checkout is in the community repository, so you should make sure to activate the community plugins box before updating the available plugins list. Checkout, checkoutpaypal, checkoutemail, checkoutdownload, checkoutgroups and checkoutpdfinvoice are in the Commerce section of the list.

You should disable the cart module when you install checkout, as both have an 'add to cart' command and it's easy to muddle the two with confusing results.

Also note that in order for anonymous (guest) users to be able to purchase items you must add the '[checkout]purchase items' and/or the '[checkout] purchase albums' permissions to the Everybody group. At installation time this is done for you at the root album level for the 'purchase items' permission, but not the 'purchase albums' permission. If you want albums to be purchased, or only some items, or want only registered users (or selected users) to purchase things then you'll need to adjust the permissions yourself.

module(s) capabilities

• per-item/album pricing A tab on the edit item page for each album/item allows product prices and parameters to be customized on a per-album or per-item basis
• Email reporting of orders to administrators and customers
• Order status tracking means that certain plugins (checkoutpaypal) can automatically acknowlege payment receipt, trigger notifications and permit downloads, where configured. For manual payment options (cheque, bank transfer) one-button order status updates are triggered from the order management page
• Online assistance facility whereby you can add items, products and discounts to visitors' carts in real time, before they checkout and place their orders.
• Open architecture means that new modules can be added to the series to customize product management, postage options, emails and other order parameters.
• Discounts can be configured for a wide variety of order criteria, including minimum value, number of products, membership of Gallery groups (for registered users) and customer-entered discount codes (coupons) can be configured.
• A customer-facing order status page allows customers to check the progress of the order and download files at the appropriate times (where configured.)
• Extensible payment architecture means new payment methods can be added.

'Checkout' core module

The core module requires some configuration. It's all presented on a single page in the admin view, and is pretty straightforward. Work carefully through the options setting them as appropriate to your business.

The Checkout module also creates two new Gallery permissions called [checkout] Purchase item and [checkout] Purchase album. You can specify which items are available for purchase by which users simply by using Gallery's existing permissions framework to set this permission on albums and items. Setting the purchase-item permission on an album controls whether the 'add photo to cart' menu option is displayed for photos in and under that album. Setting the purchase-album permission controls whether the 'add album to cart' menu option is displayed for that album and for its sub-albums.

By default, the "Everybody" group is given the Purchase Item permission at installation time. To change the permission settings navigate to the top of your Gallery and choose "Edit Permissions" on each album. Add a new group permission for group "Everybody" (or "Registered Users" if you prefer) allowing the permissions as appropriate, or remove the existing one.

checkoutpaypal - the 'paypal' payment plugin

The PayPal plugin allows you to accept PayPal payments for items in the cart. Again, everything is on one page. The fields are:

• PayPal email address is the parameter that links your gallery installation to your PayPal merchant account. When you set up your PayPal account, this would have been the email address that you registered. It is very important that this address is correct, otherwise users could end up paying money to the wrong PayPal account.
• Currency code for PayPal payments is the currency that PayPal will take money in. The list is complete for all supported PayPal currencies at the time of writing - you cannot take payments in any other currencies. See the following URL for more information: http://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_intro-outside

• PayPal Operating Mode allows you to switch the module to operate with the PayPal 'sandbox' instead of taking live payments. In order to use this feature, you will have to sign up for a PayPal developer account. The sandbox is a development environment that operates exactly like the real PayPal environment, but does not actually take money for real. More information can be found at the following URL: https://developer.paypal.com/

Before you can accept PayPal payments, you need to be signed up with a PayPal account! If you haven't already done this, go to https://www.paypal.com/cgi-bin/webscr?cmd=_registration-run and sign up for either a 'Premier' or 'Business' account (both are free to sign up for).

• In Postage Calculations you don't need anything set apart from the checkbox at the bottom of the page to allow checkout's transaction-based postage values to be used. The easiest way to set this is to click the 'Clear Settings' button, then 'Save'.

• If you are going to use the PayPal sandbox (see notes in Section 3) then you should repeat this setting for your sandbox merchant account.

• You must have IPN's turned off (they are by default, but don't be tempted to turn them on) - since checkoutpaypal enables them automatically itself, without assistance.

• You must not set a tax rate to be added to your orders. For security reasons, checkoutpaypal will reject payment notifications from paypal if the order total fails to match, if for instance tax or shipping has been added by paypal.

• Paypal's ToS forbids attempting to load paypal pages inside a frame. If your website design is horrible and icky and uses frames, checkoutpaypal will not work. There are unofficial workarounds if you want though: see http://www.pdncommunity.com/pdn/board/message?board.id=basicpayments&thread.id=15340

• To receive 'international' characters ("Iñtërnâtiônàlizætiøn") as part of names and addresses received via Paypal go to your Paypal account settings: profile -> language encoding -> More Options then set the options as follows:

checkoutgoogle - the 'Google Checkout' payment plugin

See further details here: Gallery 2:Modules:checkoutgoogle

checkoutemail - the 'email' payment plugin

The email plugin allows the contents of the cart to be emailed to a designated address, along with delivery information. You can then collect payment by other means (e.g. cheque) before fulfilling the order. You must customize the email 'confirm.tpl' (modules/checkoutemail/templates/email/confirm.tpl) template in this module to include your payment information (bank details, cheque address and payee etc) so the customer receives this data on how to pay as soon as their order is confirmed.

checkoutdownload

This module extends checkout to allow customers to download zip-files containing the images they have ordered. Configuration options are explained on the site admin page for this module, and in the checkout tab of the Item (or Album) configuration page. Default download options for each product are set in the checkout tab of the Edit Album page for the root album. Download buttons/links appear on the customer's confirmation email and also the customer's order status page.

checkoutgroups

This module extends checkout in two ways. Firstly it enables different products to be offered to users who belong to different groups. So, registered users can see different item/product combinations to guest (anonymous) users, for example.

Secondly it allows you to automatically add customers to groups when orders are paid. A "purchase group" can be set for any individual product/item combination, and when an order with that item & product is completed the user who placed the order is added to that group. Possible uses for this feature include: purchasing access to larger images, purchasing access to albums, and allowing future discounts for returning customers - depending on what permissions are preassigned to the group to which the purchaser is to be added.

Both these facilities are enabled from the extension to the checkout tab on the edit item (edit album/edit photo) page.

Since groups operate for registered users full use of these features will require users to log in before placing their order.

checkoutpdfinvoice

Download invoices to print and mail to customers with this module. Although no configuration is needed you will have to edit the (included) pdf template from which the invoice is constructed in an external application such as Adobe Illustrator to include your logo and address details. Invoices can be downloaded from the button on the order management page.

Testing

Please, please, please test your installation before you let it loose on real people's credit cards!

If you've signed up for the PayPal sandbox then the first stage of testing is to put the module into 'sandbox' mode in the admin page, and try a couple of transactions yourself. You can verify that you're in the sandbox when making the payment because the PayPal URL will be https://www.sandbox.paypal.com/.....

If you haven't signed up for the sandbox then the easiest way to test is to make a live purchase at your own site on your own credit card. Once it's been processed you can log into your PayPal merchant account and refund the payment. (Note: PayPal will not allow you to use any credit card that is registered with them for making purchases so you will need to have access to a card that has never been seen by PayPal.)