===== PayPal Payment Gateway =====
The PayPal payment gateway can be enabled to use PayPal as your payment processor.  The gateway supports the following features:
  * Encrypted Buttons
  * Automatic selection between a standard PayPal account and a micro-payment account based on the total charge.
  * Buy Now, Add to Cart and Donation buttons

==== Configuration ====
Gateway configuration is done by editing the gateway in the plugin's "Payment Gateways" option.  There are four possible account types that should be configured:  Production (Primary and Micro-Payment) and Sandbox (Primary and Micro-Payment).  This allows you to 1) switch between Production and Testing by simply checking a box, and 2) have the plugin automatically determine whether to use the Primary account or the Micro-Payment account depending on the order amount.

If you choose to encrypt your PayPal buttons, you also need to upload your public certificate file to PayPal for each of the four account types and record the certificate ID assigned to PayPal for each one.

If you do not have a Micro-Payment account, you can set the Micro-Payment Threshold value to zero.

^Option^Description^
|Production Business E-Mail|Your primary seller account e-mail address|
|Production Micro-Payment E-Mail|If you have a PayPal account set up for micro-payments, enter that account e-mail address here.|
|Sandbox Business E-Mail|Enter your primary sandbox account here.|
|Sandbox Micro-Payment E-Mail|Enter your sandbox micro-payment account here.|
|Testing (Sandbox) Mode?|Check this box to test payments via the sandbox.  Un-check when you're ready to go live.|
|Micro-Payment Threshold|The amount that determines whether the Main or Micro-Payment account is used.  Amounts greater than or equal to this amount are paid to the Main account, amounts less than this number use the Micro-Payment account.|
|Encrypt PayPal Buttons?|Check this box to have your PayPal buttons encrypted for added security.  You'll also need to enter values for the certificate ID's and keys filenames.|
|Full path to PayPal Public Certificate|Enter the full path to Paypal's public certificate file on your server.|
|Your PayPal Certificate ID|Enter the certificate ID that PayPal assigned when you uploaded your public certificate for your Main account|
|Micro-Payment Certificate ID|Enter the certificate ID that PayPal assigned when you uploaded your public certificate for your Micro-Payment account.  If you use a Micro-Payment account, you must upload your certificate to both.|
|Sandbox Certificate ID|Enter the certificate ID created by PayPal for your primary sandbox account.|
|Sandbox Micro-Payment Certificate ID|Enter the certificate ID created by PayPal for your micro-payment sandbox account.|
|Full path to your Private Key|Enter the full path to your private key file, e.g. ''/var/www/private/data/paypal/keys/private.pem''.|
|Full path to your Public Key|Enter the full path to your public key file, e.g. ''/var/www/private/data/paypal/keys/public.pem''.|
|PayPal Url - Production|Enter the PayPal URL to be used for production purchases, e.g. ''https://www.paypal.com''.|
|PayPal Url - Sandbox|Enter the PayPal URL to be used for testing, e.g. ''https://www.sandbox.paypal.com''.|
|Enabled|Check this box to enable this gateway.  Un-check it to disable the gateway.|
|Buttons|Select the button types that will be provided by this gateway.  The options are ''Buy Now'' and ''Donate''.|
|Order|Enter a number to represent the order for this gateway.  Gateways will place their buttons on product lists and order checkout in the order indicated here.  In some cases, only the first gateway (the one with the lowest order number) will be used.|

====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.

<note important>Your keys should be stored outside of any publicly-accessible directory, and it's a good idea to also store them outside of the plugin's directory structure.  A directory such as <private>/data/paypal/keys would be a good place.</note>

  - Create a directory where the keys will be stored.  You'll need to enter this directory as part of the configuration items above.  The web server does **not** need write access to this directory.
  - 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.
    - Repeat this process for your Micro-Payment account, if you have one.
  - 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.  **These keys should //not// be stored in any Internet-accessible location.**  The web server does **not** require write access to these files.
  - Go into the plugin Configuration area and update the values under "Encrypted Button Support".
    * Enter the Certificate ID that you recoded earlier in the "Certificate ID" spaces.
    * 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"

===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 un-encrypted buttons 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.

==== Multiple PayPal Accounts ====
You can have up to two PayPal accounts to support the normal fee structure and micro-payments.  Micro-payments are charged at a different rate which makes them a good choice for charges under $10.00.

In the gateway configuration screen, enter an email address for both account types and enter an amount to be used as the threshold.  Charges of this amount or more will use the regular account and charges less than this amount will use the micro-payment account.  You must enter an account for both, even if it is the same account email address.  Alternatively, you can set the threshold to zero to always use the regular account.

==== 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/paypal_ipn.php", or at "/subdirectory/paypal/ipn/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/paypal_ipn.php',
    );
  }