h1. codeigniter-paypal-ipn
h2. Overview
codeigniter-paypal-ipn is a CodeIgniter library for working with the PayPal IPN (Instant Payment Notification) service. The library acts as a listener for the PayPal IPN service and logs the orders to your database using either Doctrine or CodeIgniter active record.
This library is also available for Symfony2 - please see the "symfony2-paypal-ipn":https://github.com/orderly/symfony2-paypal-ipn repo.
h2. Description
This library focuses on the "post-payment" workflow, i.e. the processing required once the payment has been made and PayPal has posted an Instant Payment Notification call to the IPN listener (aka your CodeIgniter IPN controller).
This library handles:
Note that this library currently supports the web_accept and cart transaction types; order refunds are not currently supported.
Also note that this library will not work (will return 500 Internal Server Errors) if CodeIgniter's CSRF protection feature is left enabled. However, in a future version of CodeIgniter you will be able to enable @csrf_protection@ but whitelist the IPN action - see this "pull request":https://github.com/EllisLab/CodeIgniter/pull/236 for more details.
All pre-payment functionality (e.g. posting the checkout information to PayPal) and custom post-payment workflow (e.g. sending emails) is left as an exercise to the reader.
h2. Dependencies
There are two versions supplied: one using CodeIgniter's modified version of the Active Record Database Pattern, and one using Doctrine (tested with 1.2.3). For the second option you might find the CodeIgniter guide "Using Doctrine with CodeIgniter":http://codeigniter.com/wiki/Using_Doctrine_with_Code_Igniter/ helpful background.
h2. Installation
To create the MySQL tables required by codeigniter-paypal-ipn, run the SQL file found in the @common/sql@ folder against your db.
Download all of the remaining files from the @common@ folder and deploy them into your CodeIgniter installation following the same folder structure as found in GitHub. Then choose between the @activerecord@ and @doctrine1.2@ folder, and deploy those files into your CodeIgniter installation as well.
Please note that two different example controllers are provided: one which performs no notification following a successful order, and one which sends an order confirmation email via Smarty. Choose whichever of these example controllers fits your business requirements best, or create your own custom one (e.g. using a Twig email template instead of a Smarty one).
Check that csrf_protection in your CodeIgniter is switched off (disclaimer: the author Alex Dean accepts no responsibility for issues arising from disabling csrf_protection).
Finally, update your sandbox and production variables as found in @config/paypal_ipn.php@
h2. Usage
An example of how to use codeigniter-paypal-ipn can be found in @controllers/example.php@
h2. Credits
This library is inspired by:
h2. Disclaimer and Warning
The author Alex Dean does not accept any liability for any processing errors made by codeigniter-paypal-ipn, or any financial losses incurred through its use.
In particular, this library does not fulfil the PayPal IPN requirement to "verify that the payment amount actually matches what you intend to charge. Although not technically an IPN issue, if you do not encrypt buttons, it is possible for someone to capture the original transmission and change the price. Without this check, you could accept a lesser payment than what you expected." (This verification step is out of scope for this library because it would require integration with your product catalogue.)
Additionally this library does not properly handle refunds. Typically refunds are stored as a new order line in @ipn_orders@ with a negative balance, but even this is not 100% predicatable.
And finally the author accepts no liability for the recommendation to disable CodeIgniter's CSRF protection.
h2. Copyright
codeigniter-paypal-ipn is copyright (c) 2011 Alexander Dean, alex@keplarllp.com
h2. License
codeigniter-paypal-ipn is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
codeigniter-paypal-ipn is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with codeigniter-paypal-ipn. If not, see "http://www.gnu.org/licenses/":http://www.gnu.org/licenses/.