Free PHP PayPal Tool Box

What is this?

PHP PayPal Tools Box is a PHP class that you can use to:

• generate PayPal Donation button
• generate PayPal Recurring Donation button
• generate PayPal payment forms
• validate the IPN (Instant Payment Notifications)

The Class also has a simple way to prevent tampering with the items price. This class requires PHP 5.

View Demo

Follow the link for a small demo of the forms. View Demo.

Short history

Lately I’ve spent a lot of time integrating PayPal into different websites that use Joomla or WordPress or even custom made code. For what I needed, the already available plugins where not enough, so I always ended up writing code. Therefore I decided to create a PHP class to handle the creation of the PayPal form and the handling of Instant Payment Notification without too much hassle.

Create a PayPal payment HTML form

Step1. Include the “paypaltoolbox.php” file where the main class is.

Step2. Instantiate the class giving as parameters your PayPal account, if you want to use the sand box and the URL that should be used for IPN (Instant Payment Notifications).

Step3. Prepare your list of items and their price and optionally a unique invoice id.

Step4. Generate and output the PayPal forum with the Buy Now button

//include the required file
require ( dirname( __FILE__ ) . "/" . "paypaltoolbox.php" );

//instantiate the Class( paypal_email, test_mode, options_array )
$pp =  &new PayPalToolBox( "johndow"."@"."example.com", false, array (
        "notify_url" => "http://example.com/paypal/ipn_process.php" )
	);

//setup the items you need to sell and a unique invoice id to track this
//transatiocn
$items = array( "My Super Product" => "49.00" );
$invoice_id  = 12345; //should be unique number

//display the HTML form with the PayPal button
echo $pp->getHtmlForm( $items, array( "invoice_id" =>  $invoice_id ) );

Validate and take action on IPN

Validating the IPN from PayPal is done with a simple method call.

In your file that will process the IPNs you have to include the PHP class, instantiate it and then call the validateIPN() method. This method returns true if the IPN is a valid one and if the form data was not tampered with!

In case of validation failure use the getValidationError() method to get an explicative text message.

//include the class file
require( dirname( __FILE__) . "/" . "paypaltoolbox.php" );

//instantiate the class
$pp = &new PayPalToolBox();

//validating the IPN is a simple method call
if( $pp->validateIPN() ){
	//TODO: Add here code to handle a IPN Success
	//$_POST["invoice"] will have you uniquite invoice_id
}else{
	$error = $pp->getValidationError();
	//TODO: Add here code to handle a IPN Falure
}

Generate PayPal Donation Buttons

After you instantiate the PayPalToolBox class all you have to do is call the getDonationButton() method.

//instantiate the Class( paypal_email, test_mode, options_array )
$pp =  &new PayPalToolBox( "johndow"."@"."example.com", $test_mode, array (
        "notify_url" => "http://example.com/paypal/ipn_process.php" )
	);
//generate and output a donation button
echo $pp->getDonationButton();

View Demo

Generate PayPal Recurring Donation Buttons

OK, I admit PayPal does not support recurring donations. However! You can setup a recurring payment and present that as a recurring donation on your web site. And you can do that with PayPal using subscriptions. So basically the visitor agrees to send you a monthly payment, and you can can consider that as a monthly Donation.

Here is how to do it (of course you need to include the proper files first):

//instantiate the Class( paypal_email, test_mode, options_array )
$pp =  &new PayPalToolBox( "johndow"."@"."example.com", $test_mode, array (
        "notify_url" => "http://example.com/paypal/ipn_process.php" )
	);
//generate and output a recurring donation button for $50.00
echo $pp->getRecurringDonationForm( 50.00 );

You can also present a select box for the visitor to select the amount they would like to donate monthly. Use the same getRecurringDonationForm() but as the first parameter set an array with the labels and donations amounts, as in the example below:

//instantiate the Class( paypal_email, test_mode, options_array )
$pp =  &new PayPalToolBox( "john"."@"."example.com", $test_mode, array (
        "notify_url" => "http://example.com/paypal/ipn_process.php" )
	);
//generate and output a recurring donation button that allows
//the visitor to select the amount from a given list
echo $pp->getRecurringDonationForm( array(
        "Donate $1" => 1.00,
        "Donate $10" => 10.00,
        "Donate $100" => 100.00
) );

See this in action: view demos

Features

• Can generate Donation buttons
• Can generate PayPal payments forms
• Easy validation of IPNs
• This class will sign the form data to make sure users do not tamper with the price or the currency
• Is JavaScript ready. You can configure it to hide the submit button and so create a completely hidden form that you can submit with JavaScript (using jQuery, mootools or something like that). You can even set your custom HTML id for the form if the default one (“paypal_toolbox_form“) is not suitable for you.
• Has support for PayPal sandbox so you can do your tests before going live.
• Being a class can be easily integrated without danger of names collision in your PHP code.
• If you miss configure it, or forget to add required configuration, the class will complain about it with a clear message.
• It supports an array of options allowing you to customize every aspect of the form: form id, IPN notify URL, currency, button image, show/hide the submit button.

View Demo.

What this is not

This is NOT a shopping cart. This is just a payment gateway. This means that once you have your items collected, you can use this class to place an order with PayPal and then validate and process the IPN.

How to create a hidden form for JavaScript

To create a hidden form that you can submit from JavaScript (using jQuery, mootool or other libraries), you just have to tell this class not to draw a submit button.

You do that by setting the flag show_submit to false. And you should also provide a unique HTML id. See below:

//generate a hidden form to be submitted with JavaScript
echo $pp->getHtmlForm( $items, array(
		"invoice_id" => $invoice_id,
		"form_id" => "my_form_id",
		"show_submit" => false
		));

Then you just have to do something similar to this:

<a href="javascript:void(0);"
   onclick='document.getElementById("my_form_id").submit();'>Click me</a>

Integrations

At the moment of writing the class comes stand alone, but it can easily be integrated into a WordPress Plugin, or Joomla! extension, or simply in your PHP application. In the future I plan to write some simple integrations for WordPress and Joomla!

Download

Download the ZIP archive. It contains a few examples to get you started.

Requirements

This requires PHP 5.

Support

If you have questions or need help on how to use this Class, either contact me or comment on this post.

Licence

This code is free to use as long as you leave my name in the PHP comments and the links back to this site. Also this code is offered to you as is with absolutely no warranty. Please do you own testing.