PayPal IPN Agent

This page is for helping people set up validation software to handle IPNs on their own server. This will hopefully change in the future, and I will start offering a customizable IPN service, using this software. And if anyone wants to know how secure the backend IPN handler is, they can look at the source code themselves, unlike the other IPN services out there. :)

This software is released under the GPL.

• Download 1.0.2
  
• Archive
  
• Example
  
• config
  

"IPN Agent" version 1.0.2
A PayPal IPN Backend Handler for PHP
Kees Cook
$Date: 2004/07/28 01:57:01 $

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.
  

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