"IPN Agent" version 1.2.0
A PayPal IPN Backend Handler for PHP
Kees Cook <paypal@outflux.net>
$Date: 2005/02/10 18:08:27 $

Overview
--------
I wrote this tool since I couldn't find any others that did the FULL job.
However, I am also notoriously bad at (impatient with) finding software,
so it's possible another one with the similar functionality exists.

This tool was designed to handle Instant Payment Notifications from
paypal.com.  Since I wanted to design it as separate from any existing
cart or payment system, this tool simply takes IPN information,
verifies it, and then stores it into a local database.  It is up to the
cart or other payment system to then examine the resulting transaction
lists to determine the state of the world.  Basically, this tool lets
PayPal update your database with what they think the status of any given
payment is.

Paypal's documentation of how their IPN system works was last seen at
https://www.paypal.com/en_US/pdf/ipn.pdf
I would suggest giving it a read, just to understand what's happening.

"IPN Agent" Features
--------------------
- Verifies the IPN with Paypal.  (All the other IPN software does at
  least this part.)

- Actually verifies that the SSL Certificate is owned by paypal.com.
  SSL is useless unless you can actually verify the owner of the domain.
  To use this, you must have a "root Certificate Authorities" file.
  All modern browsers come with one, and there is a debian package
  named "ca-certificates" that has the file as well.

- Stores results intelligently in a database for later examination.

- Runs external tool on a "Completed" payment.  Once a transaction is
  actually finished, an external tool can be called to perform final
  price verification.  One of the easiest ways to defraud a merchant
  using PayPal is to just change the price of all the items in a
  shopping cart.  With an external price verification system, you can
  hook up to any shopping cart system.  Once that is finished, it can
  continue to perform other functions to react to the completed payment.

Upgrading
---------
If you're upgrading from a 1.0.x version of IPN Agent to 1.2.x or later,
you will need to change the name of a column in your database.  There was
a bug in the 1.0.x series where "option_selection" was incorrectly named
"option_select".  If you are running MySQL, the command to make this change
is:
 ALTER TABLE ipn_options CHANGE option_select option_selection VARCHAR(127);

Missing
-------
- Subscriptions.  I just haven't bothered to investigate the fields
  sent during a subscription.  We can do that in the next version.

Requirements
------------
- PHP (version 4 or better).  I tested under 4.3.4.
- PEAR DB (version 1.6.0 or better).  I tested under 1.6.1.
  You may need to explicitly upgrade your version of PEAR's "DB" package.
  Run "pear list" to see what version of "DB" you have installed.  If it
  is younger than "1.6.0", run "pear upgrade DB" to get the latest.

Files
-----
README        - This documentation.
COPYING       - The GPL, the license for this software.
config.txt    - Should be edited and renamed to "config.php".  See
                "Setup" below.
sql.sh        - Shell script to generate the expected SQL tables.
ipn_agent.php - The core PHP "IPN_Agent" class source.
ipn.php       - The script that instantiates an IPN_Agent object and
                is actually responsible for taking the incoming POST
                from PayPal.
pay.php       - Example PayPal payment form.
paid.php      - Example "return" script.  See "pay.php".
cancel.php    - Example "cancel" script.  See "pay.php".
DESIGN        - The mindless gibbering of my design work for IPN_Agent.

Setup
-----
1) Configure.
   Rename "config.txt" to "config.php", and edit it to set up all the
   variables.  The listed defaults are all just examples.  Don't forget
   you MUST have a password defined for your database DSN.
2) Set up database.
   If you have the command-line "php" interpreter, run
	./sql.sh | mysql -u root -p
   Otherwise, rename "sql.sh" to "sql.php", edit it to remove the first
   two lines and the last line (leaving just the PHP code) and access it
   from your browser.  Take the output and run it through "mysql -u root -p"
   to create your IPN database tables.  If you do this, please rename
   "sql.php" back to "sql.sh" so other people can't read your database
   password.  ;)
3) Hook up to your cart/website/whatever through the "run_stored" or
   "run_completed" script.  (And do price verification!)
4) Have fun!

Testing
-------
To test everything, you can formulate IPN queries at 
https://www.eliteweaver.co.uk/testing/ipntest.php
But you'll have to update the 'url' variable in "config.php" used for
IPN verification.  Don't forget to change it back when you're done
testing.

