What is this?

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

  • generate PayPal Donation button
  • generate PayPal “Recurring” Donation button
  • generate PayPal payment forms
  • validate and respond to IPN (Instant Payment Notifications)
  • validate and respond to PDT (Payment Data Transfer)

This library requires PHP 5, and the PDT validation requires that you have cURL installed and configured.
Download ZIP Archive

View Demo

Follow the link for a small demo of the forms. View Demo.
PHP PayPal Tool Box Demo

Short history

Lately I’ve spent a lot of time integrating PayPal into different websites based on Joomla or WordPress or even custom code. For what I needed, the already available plugins where not enough, so I always ended up writing new code. Therefore I have decided to create a PHP library to handle the creation of the PayPal form and the handling of Instant Payment Notification and Payment Data Transfer without too much hassle. This library had to be simple enough to use, and yet easy to extend in the future if required.

General Usage of the Library

The library has a main factory class that you should use to get access to the various objects you will need.

Include in your code the file “paypaltoolbox/PayPalFactory.php’

Use the static methods in that class to create the other objects.

Have a look at the example files provided in the archive to see various usage patterns.

Create a PayPal payment HTML form

Step1. Include the factory class: “paypaltoolbox/PayPalFactory.php’

Step2. Create a PayPalFormPayment using: PayPalFactory::getPaymentForm( email, list_of_items);

Step3. Configure the payment object to add things that you may need: new currency, return url, notify url (for IPN), cancel url, invoice number and switch between live and Sandbox Paypal.

Step4. Generate and ouput the HTML code for this form.


//include the PayPal Tool Box factory
require_once( "paypaltoolbox/PayPalFactory.php" );

//************************************************
//A more comprehensive example of a payment configuration
$form = PayPalFactory::getPaymentForm( "your_account_at_email.com",
           array( "Product Aa" => "11.50", "Product Bb" => "23.50" ) );
$form
//(Optional): disable shipping address requirement
->disableShippingAddress()

//(Optional): set an invoice number for this transaction
->setInvoiceNumber( "ABABABAB" )

//(Optional):configure test mode, default FALSE)
->setTestMode( false )

//(Optional):configure currency, default USD
->setCurrencyCode( "EUR" )

//(Optional but important): Configure where should
//          PayPal send IPN notifications
->setNotifyUrl( "http://your-website.com/example-ipn-validator.php" )

//(Optional): where should customer be returned after payment
->setReturnUrl( "http://your-website.com/example-return-thank-you-page.php" )

//(Optional): where should customer be returned if she cancels payment
->setCancelUrl( "http://your-website.com/cancel-return-page.php" );

echo "Comprehensive payment setup:<br/>";
echo $form->getHtmlCode();

Validate and take action on IPN

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

You need to include the PayPalFactory class in your code and use that to create a PayPalIpnValidator object.

Rember to configure this object to use the Sandbox or not!

A simple example is below. For a more comprehensive example look at: example-ipn-validator.php in the archive.

//include the factory class file
require_once( "paypaltoolbox" . DIRECTORY_SEPARATOR . "PayPalFactory.php" );

//validate the notification from PayPal
$result = $validator->validateIpn();

if( $result ){
    //TODO: IPN was validated, add here code to update database and
    //so on. You should also check that you do not validate the same
    //IPN multiple times

}else{
    //TOD: IPN validation has failed. You should log this for manual
    //Investigation later.

    //get the Validation log for inspection
    $validator->getLogMessages();
}

Generate PayPal Donation Buttons

As always, include the PayPalFactory class and use the getDonationForm( your_email ) method to build a PayPal donation form object.

See example-donations.php in the archive or have a look at the very simple exmaple below:

//include the PayPal Tool Box factory
require_once( "paypaltoolbox/PayPalFactory.php" );

//Very basic donation setup
$basicButton = PayPalFactory::
 getDonationForm( "your_account_at_email.com" )
     ->setDonationName( "Your contribution" );

echo "Very basic donation setup:<br />";
echo $basicButton->getHtmlCode();

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. (Just make sure this is OK with the accounting department!)  And you can do that with PayPal using subscriptions. So , in short, the visitor agrees to send you a monthly payment, and you can can consider that as a monthly Donation. (Again check the law where you live, if you can consider this a donation or not).

See the file: example-recurring-donations.php in the archive or look below.

Simple “recurring donation”:

//include the PayPal Tool Box factory
require_once( "paypaltoolbox/PayPalFactory.php" );

//Simple recurrent "donation" of 100 EUR
$basicForm = PayPalFactory::
getRecurrentDonationForm( "your_email_example.com" )
  ->setDonationName( "Donate 100 EUR monthly")
  ->setDonationAmount( "100" )
  ->setCurrencyCode( "EUR");

echo "Example of simple 'recurring' 100EUR donation:<br/>";
echo $basicForm->getHtmlCode();

You can also present a select box for the visitor to select the amount they would like to donate monthly:

//include the PayPal Tool Box factory
require_once( "paypaltoolbox/PayPalFactory.php" );

//Simple recurrent "donations" with a drop down menu
//Of course this class supports setting the notify url, cancel url, and so on
//just as you can see in example-donations.php
$form = PayPalFactory::getRecurrentDonationForm( "your_email_example.com" )
->setDonationAmount( array(
"Donation $10" => "10",
"Donation $20" => "20" ,
"Donation $30" => "30" ,
"Donation $40" => "40" ) )
->setCurrencyCode( "USD" )
;

echo "Example of 'recurrent' donation with select:<br/>";
echo $form->getHtmlCode();

See this in action: view demos

Features

  • Can generate Donation buttons
  • Can generate PayPal payments forms
  • Easy validation of IPNs
  • Easy validation of PDTs
  • 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.
  • Has support for PayPal sandbox so you can do your tests before going live.
  • If you miss configure it, or forget to add required configuration, the class will complain about it with a clear message.
  • Very customizable

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 (and/or PDT). If you want a shopping cart you will still need to write code to collect the items.

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.

//include the PayPal Tool Box factory
require_once( "paypaltoolbox/PayPalFactory.php" );

//Very basic payment setup
$basicButton = PayPalFactory::getPaymentForm( "your_account_email.com",
     array( "Total" => "100.10" ) )
->disableShippingAddress()
    ->removeSubmitButton() //<-- will no longer have a submit button
;

echo "Very basic payment setup:<br />";
echo $basicButton->getHtmlCode();

$formId = $basicButton->getHtmlId();

Then you just have to do something similar to this:

<a onclick="document.getElementById(&quot;my_form_id&quot;).submit();" href="javascript:void(0);">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 licensed under a Creative Commons Attribution 3.0 license. Basically 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.

Tagged with:
 

One Response to Free PHP PayPal Tool Box

  1. Bruno says:

    Thank you Ilie for this big upgrade !
    I’ll test it tomorrow :)

Leave a Reply to Bruno Cancel reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Set your Twitter account name in your settings to use the TwitterBar Section.