glFusion Wiki

Site Tools


paypal:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

paypal:start [2010/02/02 22:34]
paypal:start [2016/07/16 19:39] (current)
Line 1: Line 1:
 +====== PayPal Plugin v0.4.3 ======
 +
 +The PayPal plugin allows you to have an online product list and accept payment
 +via PayPal. ​ The PayPal plugin supports downloadable merchandise.
 +
 +This is an updated version of the //Paypal Plugin for Geeklog//, originally developed by Vincent Furia. ​ This version adds several new features especially for glFusion 1.1.6 and higher.
 +
 +===== Requirements =====
 +
 +  * glFusion v1.1.6 or newer
 +  * A PayPal business account
 +  * For [[paypal:​start#​Encrypted Buttons|encrypted PayPal buttons]], access to openssl.
 +
 +=====Features=====
 +  * Sell items on your site using Paypal.
 +  * Support for [[paypal:​start#​Encrypted Buttons|encrypted Paypal buttons]]. (new)\\ Buttons are automatically created when a product is updated.
 +  * Support for comments. (new)
 +  * Support for product ratings (glFusion 1.1.7 and newer). (new)
 +  * Support for multiple product images. ​ Images may be uploaded via the product catalog rather than being uploaded separately. (new)
 +  * Downloadable products may be uploaded directly via the product form. (new)
 +  * Search products using glFusion'​s search (new)
 +  * Include product links in other text using [[paypal:​start#​AutoTags]]
 +  * [[http://​www.leegarner.com/​dokuwiki/​doku.php/​glfusion:​glpaypal:​pluginintegration|Plugin Integration]] - Plugins may provide items for sale to be included in the Paypal catalog. (new, experimental)\\ Some possibilities are:
 +    * Event Fees
 +    * Site Membership Fees
 +    * Advertising
 +
 +Screenshots can be seen [[http://​www.leegarner.com/​mediagallery/​album.php?​aid=18&​page=1|here]].
 +
 +===== Installation =====
 +
 +The PayPal ​ Plugin uses the glFusion automated plugin installer.
 +Simply upload the distribtuion using the glFusion plugin installer located in
 +the Plugin Administration page.
 +
 +<​note>​Always back up your database before installing or upgrading a plugin!</​note>​
 +
 +The plugin may be installed manually, if necessary.
 +
 +==== Manual Installation ====
 +  - Extract the tarball into the //​private_dir///​plugins directory.
 +  - Move the public and admin directories
 +    * Move //​private_dir///​plugins/​paypal/​public_html to //​public_html///​paypal
 +    * Move //​private_dir///​plugins/​paypal/​admin to //​public_html///​admin/​plugins/​paypal
 +  - Create a download log file called //​paypal_downloads.log//​ in the //​private_dir///​logs directory. ​ Make sure that the web server can read and write to this file.
 +  - Create a working directory for creating encrypted PayPal buttons. ​ The default location for this is //​private_dir///​data/​paypal,​ but it can be anywhere the web server can read, write and create files. ​ (If you use a different location, you need to update the plugin configuration accordingly.)
 +  - If you are upgrading from version 0.3.2 or earlier, rename your config.php file to config.old.php. ​ Starting with version 0.4.0 all configuration is done through the online configuration system.
 +  - Visit {site_url}/​admin/​plugins.php. ​ Click "​Install"​ next to the PayPal plugin.
 +
 +===== Upgrading =====
 +
 +The upgrade process is identical to the installation process, simply upload
 +the distribution from the Plugin Administration page.
 +
 +==== Upgrading to version 0.4.0 ====
 +<note warning>​If you are upgrading from version 0.3.2 or earlier, **you must back up your database before upgrading** the Paypal plugin. ​ This version (0.4.0) is substantially different than previous versions and makes significant changes to the database schema</​note>​
 +
 +Other notes:
 +  * During the upgrade, values from your existing configuration file (config.php) will be loaded into the online configuration system and the file will be renamed to "​config.old.php"​. ​ If you need to restore an earlier version of the plugin you'll need to rename that file back to "​config.php"​.
 +  * Several new fields are added to the product table, among them a field to hold the date when the product was added to the catalog. ​ This may be used in the future to create a "New Products"​ block or for similar purposes. ​ During the upgrade, this value will be set to the current timestamp.
 +
 +=== Summary of Changes in 0.4.0 ===
 +  * Moved the configuration from config.php to online configuration
 +  * Added support for creating encrypted PayPal buttons.
 +  * Added product category table for more structured category assignments.
 +  * Added donation support.
 +  * Added support for multiple images uploaded with the product record.
 +  * Allow selection of file or upload of new one.
 +  * Added support for physical products. ​ Added new "​weight"​ field for shipping. Shipping can be set up in the PayPal account profile.
 +  * Added "​taxable"​ field to override PayPal-profile tax setup per item.
 +  * Expanded currency support to all PayPal-supported currencies.
 +  * Added selection of button types per product (buy now, add to cart, etc).
 +  * Added support for plugin-supplied products. ​ Added API functions to allow plugins to generate encrypted and plain buttons.
 +  * Enhanced the IPN handler to notify plugins of purchases related to them.
 +  * Integrated with glFusion'​s site search, added keyword field to products.
 +  * Added user comment support to products. ​ Enabled by default.
 +  * Added user ratings support to products (glFusion 1.1.7 or later only).
 +  * Added purchase notifications to admin.
 +  * Revised the user interface and product catalog using tabs and admin lists.
 +  * Added slimbox for viewing expanded thumbnail images.
 +  * Added blocks for random, popular and featured products.
 +
 +=====Usage====
 +===Autotags===
 +Autotags can be used to embed product information into a static page or story. ​ The autotag format is
 +  [paypal:​product_id optional_text]
 +Where //​product_id//​ is the numeric database ID number of the product and //​optional_text//​ is the text to display in the link.  If the text parameter is omitted, then the product name will be shown.
 +
 +===== Administration =====
 +==== Configuration Options ====
 +Configuration Options are set by the Paypal section in the site Configuration area.  There is no config.php required unless you wish to override any other settings.
 +
 +^Option^Description^
 +|Paypal URL|This is the URL to the Paypal site.  The default value is set to "​www.sandbox.paypal.com",​ which should be used during setup and testing. ​ When you're site goes live, change this to "​www.paypal.com"​.|
 +|Testing Mode|This should be set to "​Yes"​ during testing. ​ This helps ensure that any IPN messages from Paypal are treated as test values.|
 +|Receiver Email Address|This is an array of email addresses that you use with Paypal. ​ The element ID's must be numeric (0, 1, 2, etc).  Your primary business email address **must** be set as item "​0"​.|
 +|Currency|Select the currency that your site uses.  Only one currency type is supported.|
 +|Anonymous users can buy?|Set this to "​Yes"​ to allow anonymous visitors to make purchases. ​ If this is "​No",​ then visitors must log in before they can purchase items.|
 +|Email User upon purchase?​|Set this to "​Yes"​ to send an email acknowledgment to the buyer. ​ Note that they will also recieve an payment acknowledgment from Paypal, but this allows you to send something similar to an invoice.|
 +|Attach files to user's email message?|If this is "​Yes",​ then downloadable files which are purchased will be attached to the acknowledgment email (assuming "Email User upon purchase"​ is also "​Yes"​). ​ If this is "​No",​ then the buyer will need to visit your site to download the purchased file.  Note that the buyer can still download the file from your site until the expiration time runs out.|
 +|Attach files to anonymous buyer email?|This is the same as "​Attach files to user's email message"​ above, but applies specifically to anonymous buyers. ​ If you allow anonymous buyers to purchase downloadable files, then this **must** be set to "​Yes"​ or the buyer will never be able to get their files.|
 +|Notify administrators of purchases?​|Choose when an administrator will receive an email as a purchase is made.  If you are selling physical items that require some intervention on your part (such as shipping the item), you are strongly encouraged to receive notifications at least for physical item sales. ​ The notification email is sent to the configured site email address.|
 +|Add to main menu?​|Setting this value to "​Yes"​ adds a "​Products"​ menu option under the "​Extras"​ menu.  If you prefer, you can set this to "​No"​ and manually add a menu option anywhere you like.|
 +|Default sort order for product display|Select the field that will be used initially to sort the product listing.|
 +|Max products displayed per page|Enter a number for the maximum number of products to be displayed on a single page in the product list.|
 +|Category Columns|Enter a number for the number of columns used to create the category links at the top of the product listing.|
 +|Use internal CSS tabbed menu?|If this is "​Yes",​ then the menu in the product catalog will use the styles defined by the plugin. ​ This gives you the opportunity to customize the look of the menu, if you like.  If this is "​No",​ then the standard glFusion tabbed menu will be used.|
 +|Max number of product images|Set this to the maximum number of images that may be uploaded with a product.|
 +|Enable Comments?​|Select "​Yes"​ to allow site users to add comments to products, similar to articles and other glFusion content. ​ Select "​No"​ to disable comments globally.|
 +|Enable Ratings?​|Select "​Yes"​ to allow products to be rated by site visitors. ​ Select "​No"​ to disable ratings completely.|
 +|Enable Left Blocks\\ Enable Right Blocks|Left and/or Right blocks may be disabled when the product catalog is displayed.|
 +|Max Thumbnail Dimension|Enter the maximum size (width or height), in pixels, that a thumbnail may occupy. ​ When thumbnails are created from uploaded images, they will be sized so that the longest dimension does not exceed this value while preserving the aspect ratio.|
 +|Max Image Width\\ Max Image Height|These are the maximum dimensions, in pixels, that a product image may occupy. ​ When the product images are uploaded, they will be resized to fit within these dimensions while preserving their aspect ratios.|
 +|Full path to downloadable files|Enter the //​complete//​ path to where downloadable files are stored. ​ The default value will be created during the plugin'​s installation process; if you change this you must make sure that your webserver has permission to read //and write// (for file uploads) to this path.  Files uploaded with the product form will be saved in this location.|
 +|Max size for downloadable files|Enter the maximum number of megabytes for downloadable files.|
 +|Debug IPN Messages|If you're having trouble handling the Instant Payment Notification messages from Paypal, enabling this option may help troubleshoot the problem by logging the complete message to the glFusion error.log file.|
 +|Debug|Enable this option to have a variety of detailed information logged to the glFusion error.log. ​ This does not include IPN messages; see above.|
 +
 +===Manual Configuration Options===
 +There are still a few configuration options handled by a configuration file, as these don't easily lend themselves to the online configuration. ​ These items are located in the "​paypal.php"​ file.  If you wish to change them, you should create a new config.php so that your changes will not be overwritten during a future upgrade.
 +
 +====Encrypted Buttons====
 +Starting with version 0.4.0, encrypted Paypal buttons are supported. ​ Encrypted buttons protect you from spoofed forms being sent to Paypal. ​ For example, someone could download view the source to your page, change the price of an item, and submit the form to Paypal.
 +
 +<​note>​When you switch between standard HTML buttons and encrypted buttons, the change won't affect existing products. ​ Product buttons are generated when the product is saved, so you'll need to reset the buttons by clicking the "Reset All Buttons"​ link under the "Other Functions"​ link in the administration menu.</​note>​
 +
 +These instructions assume that you are running your site on a Linux or UNIX server, or have access to one.  The keys that will be generated can be copied to another server.
 +
 +  - Create your own private key: <​code>​openssl genrsa -out prvkey.pem 1024</​code>​
 +  - Create your public key.  This creates a key good for one year: <​code>​openssl req -new -key prvkey.pem -x509 -days 365 -out pubcert.pem</​code>​
 +  - Upload your public certificate to Paypal
 +    - Log in to your Paypal merchant account
 +    - Under "My Account",​ select the "​Profile"​ submenu and click "More Options"​
 +    - Under the Seller Preferences column, click "​Encrypted Payment Settings"​
 +    - Click the "​Add"​ button and upload your **public** certificate file (pubcert.pem in this example)
 +    - After your public certificate is uploaded, record the Cert ID on the next screen. ​ You'll need to add it to the plugin configuration.
 +  - Download the PayPal public certificate. ​ While you're still on the "​Website Payment Certificates"​ screen, click the "​Download"​ button under "​PayPal Public Certificate"​ (but above your certificate list).
 +  - Save all the keys (privkey.pem,​ pubcert.pem and the Paypal public certificate) somewhere that your web server can read them.  The default configuration for the Paypal plugin assumes that they'​re in "​private/​plugins/​paypal/​keys"​. ​ **These keys should //not// be stored in any Internet-accessible location.**
 +  - Go into the plugin Configuration area and update the values under "​Encrypted Button Support"​.
 +    * Enter the Certificate ID that you recorded earlier in the "​Paypal Certificate ID" space.
 +    * Enter the full path to each the 3 key files that you saved in the previous step.
 +    * Check the "​Temporary Working Directory"​ value and make sure that it points to a directory that your web server can read and write to.  The default of "​private/​data/​paypal"​ should work correctly.
 +  - Finally, enable support for encrypted buttons by setting "​Encrypt Paypal Buttons?"​ to "​Yes"​.
 +<​note>​Once you are satisfied that encrypted buttons are working correctly, you should block non-encrypted payments by editing your "​Website Payment Preferences"​ in your PayPal profile. ​ If non-encrypted payments are accepted then payments may still be spoofed.</​note>​
 +
 +===Testing===
 +To test the encrypted buttons, simply save a product record. ​ You don't need to make any changes; whenever a product record is saved, the buttons are regenerated. ​ If encrypted button support is off, or if it fails for some reason, then empty buttons are saved to the database to be later populated by HTML form variables. ​ If encryption succeeds, you'll see the encrypted value in the page source for the button.
 +
 +Sample non-encrypted button:
 +<code html><​form style="​display:​inline;"​ action="​https://​www.sandbox.paypal.com/​cgi-bin/​webscr"​ method="​post">​
 +  <input type="​hidden"​ name="​cmd"​ value="​_xclick"​ />
 +  <input type="​hidden"​ name="​business"​ value="​your_business_email@your.site"​ />
 +  <input type="​hidden"​ name="​item_name"​ value="​Test Product"​ />
 +  <input type="​hidden"​ name="​custom"​ value="​2"​ />
 +  <input type="​hidden"​ name="​item_number"​ value="​21"​ />
 +  <input type="​hidden"​ name="​amount"​ value="​29.95"​ />
 +  <input type="​hidden"​ name="​no_note"​ value="​1"​ />
 +  <input type="​hidden"​ name="​currency_code"​ value="​USD"​ />
 +  <input type="​hidden"​ name="​return"​ value="​http://​your.site/​paypal/​index.php?​mode=thanks"​ />
 +  <input type="​hidden"​ name="​rm"​ value="​2"​ />
 +  <input type="​image"​ src="​http://​your.site/​paypal/​images/​buynow.gif"​ border="​0" ​
 +        name="​submit"​ alt="​Buy Now with Paypal" ​
 +        title="​Buy Now with Paypal"​ />
 + </​form></​code>​
 +
 +Sample encrypted button:
 +<code html>
 +<form style="​display:​inline;"​ action="​https://​www.sandbox.paypal.com/​cgi-bin/​webscr"​ method="​post">​
 +  <input type="​hidden"​ name="​cmd"​ value="​_s-xclick"​ />
 +  <input type="​hidden"​ name="​encrypted"​ value="​-----BEGIN PKCS7-----
 +MIII6wYJKoZIhvcNAQcDoIII3DCCCNgCAQAxggE6MIIBNgIBADCBnjCBmDELMAkG
 +A1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExETAPBgNVBAcTCFNhbiBKb3Nl
 +...
 +WPByUPyWCCwB0buEtZESqUytnN5Tvqa+iO9ygpMuyIWjAMFP9pi1EmdHx9oWCaM3
 +7s4jet28JA/​DkXtKJ4jxKCv6kyBmJwIL82ICsu32KucT9vJVFvKDc5qH9J4F0m4V
 +horHdLB9bJtJXwtPar+oaE4o+snjrY6uTzHrF51mVA==
 +-----END PKCS7-----">​
 +  <input type="​hidden"​ name="​return"​ value="​http://​your.site/​paypal/​index.php?​mode=thanks"​ />
 +  <input type="​hidden"​ name="​rm"​ value="​2"​ />
 +  <input type="​image"​ src="​http://​your.site/​paypal/​images/​buynow.gif"​ border="​0" ​
 +        name="​submit"​ alt="​Buy Now with Paypal" ​
 +        title="​Buy Now with Paypal"​ />
 + </​form>​
 +</​code>​
 +As you can see, everything about the product and your business has been encrypted into a single value, and can't be changed.
 +
 +===Troubleshooting===
 +If button encryption fails, check your site's error.log file.  The encryption process logs errors there.
 +
 +If buttons can't be encrypted, then they are created as simple HTML forms so your site will still be usable. ​ Once you're satisfied that encryption is working properly, your should revisit your Paypal Profile and enable blocking of non-encrypted payments. ​ This is found by clicking "​Website Payment Preferences"​ under the "​Selling Preferences"​ menu.
 +
 +==== Instant Payment Notification ====
 +Paypal'​s Instant Payment Notification (IPN) messages can be used by the plugin to record transactions in its own database, allowing you to review transactions from within the plugin'​s administration interface.
 +
 +Further, the IPN messages allow other Paypal-enabled plugins to take action based on the purchase. ​ This may include automatically subscribing the buyer to some site feature, or allowing the buyer to immediately place the classified ad that they purchased.
 +
 +=== If you're using the Bad Behaviour plugin...===
 +You **must** whitelist either the IPN url on your site, or Paypal'​s IP address. ​ Whitelisting the URL is probably better since it won't be affected by a change at Paypal. ​ If you don't do this, your site will simply ignore IPN messages.
 +
 +The IPN url is at "/​paypal/​ipn.php",​ or at "/​subdirectory/​paypal/​ipn.php"​ if your site is accessed as "​http://​mysite.com/​subdirectory/"​. ​ You need to provide Bad Behaviour with everything starting from the first slash after the site name, up to (not including) the first question mark, if any.
 +
 +This change is made in public_html/​bad_behaviour2/​bad-behaviour/​whitelist.inc.php,​ in function bb2_whitelist(). ​ Examples:
 +  function bb2_whitelist($package)
 +  {
 +    // examples and other whistelists...
 +  ​
 +    // Includes two examples of whitelisting by URL.
 +    $bb2_whitelist_urls = array(
 +        '/​paypal/​ipn.php',​
 +    );
 +  }
 +
 +===== Known Issues =====
 +==== Version 0.4.3 ====
 +A couple of issues relating to anonymous access to downloadable products.
 +  * Download button is displayed to all anonymous users. ​ Once a purchase was made by an anonymous user, "​Anonymous"​ can see the download button until it expires. ​ {{:​paypal:​product.class.php.gz|}} fixes that by blocking all download buttons, except for free products, from anonymous users. ​ Unzip this file in your private/​plugins/​paypal/​classes directory.
 +  * Emails and files are not properly sent to anonymous users. ​ {{:​paypal:​baseipn.class.php.gz|}} correctly attaches files to anonymous buyers. ​ Unzip this file in your private/​plugins/​paypal/​classes directory.
 +
 +==== Version 0.4.0 ====
 +  * Comments cannot be disabled for individual products.\\ A bug in the Product class causes the "​Comments Enabled"​ selection to be ignored. ​ This is fixed in [[http://​glfusion.svn.sourceforge.net/​viewvc/​glfusion/​paypal/​trunk/​classes/​product.class.php?​view=log|SVN]] for version 0.4.1. The global comment setting is working; this only affects the per-product comment setting.
 +  * Some users have reported the inability to save new products. ​ Although this has not been duplicated in development or staging environments,​ enabling the global "​debug"​ option (see [[#​Configuration Options]]) may help determine the cause.
 +
 +===== PayPal Account =====
 +A paypal business account is required in order for this plugin to operate
 +correctly. ​ In addition, there are several items in your paypal account that
 +must be set up correctly in order purchcases to be logged.
 +
 +  - Create a PayPal business account (note: you can update an existing account to a business account by logging into the paypal account and clicking on   "​Upgrade Account"​) visit [[https://​www.paypal.com/​cgi-bin/​webscr?​cmd=_registration-run]]
 +  - Verify your account. ​ This is needed to transfer money out of your paypal account and into a bank account. ​ You can do this from your paypal account.
 +  - Update seller preferences. ​ From the "My Account"​ tab or your Paypal account, select the "​Profile"​ sub-tab. ​ Click on "​Instant Payment Notification Preferences"​. ​ Edit the preferences. ​ You want to ENABLE instant payment notification. ​ In the box provided for a URL, enter: ​ <​nowiki>​http://​{site_url}/​paypal/​ipn.php</​nowiki>​
 +  - Update *optional* seller preferences. ​ From the "My Account"​ tab or your Paypal account, select the "​Profile"​ sub-tab. ​ You may want to consider entering information for the following date: \\ * Sales Tax \\ * Shipping Calculations \\ * Payment Receiving Preferences \\ * Reputation \\ * Website Payment Preferences \\  * Custom Payment Pages  \\  * Invoice Templates \\ * Language Encoding
 +
 +===== License =====
 +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
 +
 +Copyright (c) 2009 by Lee Garner
 +
 +Based upon the Paypal Plugin for Geeklog version 0.2.0 by Vincent Furia (Copyright (c) 2005-2006 by Vincent Furia).
 +