Making a Donation Center With PHP, MySQL and PayPal's APIs

It all started last month when I received the following email:

Hey there Tutorialzine!

Thanks for publishing such great tutorials, you have truly helped me increase my (growing) development skills. I know you enjoy getting ideas for tutorials, so I thought I'd toss one your way.

Donation buttons are a very common among blogs and websites in general, but they often don't provide much else than a button for someone to click and pay. Why not kick it up a notch and create a sweet "donation center", which doesn't just take donations, but perhaps includes a "meter", a top-donator list, and various other bells and whistles that may encourage the visitor to donate?

Devon

You are right, Devon, it is always nice to hear fresh ideas for tutorials. And a donation center is a great chance to experiment with PayPal's APIs and build something that many people can benefit from.

Note: This tutorial is quite old and doesn't work in PHP7 and above. We are keeping it online only as a reference.

The Idea

PayPal provides numerous APIs and integration options for third-party developers. One of these is the Donation button, which you can generate straight from PayPal's site and include directly into your pages. Conversion rate for these buttons is typically minimal, but the right incentive can make a big difference.

The idea is to have a dedicated Donation Center. This is a place, where you get to see what a difference your donation would make, and a list of people who have already donated.

After choosing the amount you wish to donate and clicking the button, you are redirected to paypal.com to complete the transaction. After this is done, you are redirected back to the donation center where you can fill a form and get included in the official Donor List.

Step 1 - Database

The script uses two tables - dc_donations and dc_comments. The first stores the donation data which is passed in a request from PayPal (we will come back to this in the PHP step of the tutorial).

The second table holds the information about the donors, which they fill for themselves on the thank you page.

You can create these tables in your database by running the SQL code from tables.sql (found in the download archive) from the SQL tab of phpMyAdmin. You can also just upload the file via the "Import" feature.

After this remember to add your MySQL login details to connect.php.

Step 2 - XHTML

Moving to the markup of the donation center iself. Donate PHP is the only page which your visitors see. The other page is thankyou.php, which is displayed only to the donors, once they've completed the donation process.

donate.php

<div id="main">
    <h1>Donation Center</h1>
    <h2>Show Your Support for our Cause</h2>

    <div class="lightSection">
        <h3>Hello, dear visitor!</h3>
        <p>This is Tutorialzine's Donation Center...</p>    

        <!-- The PayPal Donation Button -->

    </div>

    <div class="chart">
        Our Goal
    </div>

    <div class="donations">
        <?php echo $percent?>% done
    </div>

    <div class="clear"></div>

    <div class="donors">
        <h3>The Donor List</h3>
        <h4>Folks Who Showed Their Support</h4>

        <div class="comments">

        <!-- PHP Code that generates the comments -->

        </div> <!-- Closing the comments div -->

    </div> <!-- Closing the donors div -->

</div> <!-- Closing the main div -->

The .lightSection div holds the message that we show to the visitor of the page and the markup of the PayPal donation button, which you can see below. After this is the Pie chart which shows how much of our initial goal is met. The chart is generated with Google's Charting API. Lastly is the .donors div, which holds a list of donors that have already donated.

donate.php

<form action="<?php echo $payPalURL?>" method="post" class="payPalForm">
    <div>
        <input type="hidden" name="cmd" value="_donations" />
        <input type="hidden" name="item_name" value="Donation" />

        <!-- Your PayPal email: -->
        <input type="hidden" name="business"
        value="<?php echo $myPayPalEmail?>"/>

        <!-- PayPal will send an IPN notification to this URL: -->
        <input type="hidden" name="notify_url"
        value="<?php echo $url.'/ipn.php'?>" /> 

        <!-- The return page to which the user is
        navigated after the donations is complete: -->

        <input type="hidden" name="return"
        value="<?php echo $url.'/thankyou.php'?>" /> 

        <!-- Signifies that the transaction data will be
        passed to the return page by POST: -->

        <input type="hidden" name="rm" value="2" /> 

        <!-- General configuration variables for the paypal landing page. -->

        <input type="hidden" name="no_note" value="1" />
        <input type="hidden" name="cbt" value="Go Back To The Site" />
        <input type="hidden" name="no_shipping" value="1" />
        <input type="hidden" name="lc" value="US" />
        <input type="hidden" name="currency_code" value="USD" />

        <!-- The amount of the transaction: -->

        <select name="amount">
        <option value="50">$50</option>
        <option value="20">$20</option>
        <option value="10" selected="selected">$10</option>
        <option value="5">$5</option>
        <option value="2">$2</option>
        <option value="1">$1</option>
        </select>

        <input type="hidden" name="bn" value="
        PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest" />

        <!-- You can change the image of the button: -->
        <input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" name="submit" alt="PayPal - The safer, easier way to pay online!" />

    <img alt="" src="https://www.paypal.com/en_US/i/scr/pixel.gif"
    width="1" height="1" />

    </div>
</form>

The PayPal Donation button is structured as a regular html form. When you click the Donate graphic, the form is submitted to PayPal. A number of customizations are available, such as the the amount of the donation, the email of the recipient of the donation and many more (the full list of options is located here). Each of this options is added as a hidden field to the form.

Note the return and the notify_url variables. The first takes the URL of the page to which the user is redirected after the completion of the payment (in our case thankyou.php), and the other is a special page, which listens for PayPal's Instant Payment Notifications (IPN).

When a payment occurs, PayPal sends a special IPN notification to a page on your server. Data about the transaction is passed along the way, including the amount received, the email of the payee, currency and more. For example our IPN listener page, ipn.php, inserts the amount received to the donations table, which is later used by the Donation Center to calculate how much money has been gathered and what percentage of the goal has been met.

Now lets move to the PHP part of the tutorial.

Step 3 - PHP

As mentioned in the previous step, when a payment occurs, PayPal sends an IPN notification to your script, which contains all kinds of data for the transaction. Implementing this IPN listener page involves a lot of coding, as the script must validate that the notification was issued by PayPal.

Lucky for us, there are nice people out there who have already implemented these validations and packed them into an easy to use PHP5 PayPal class. Now lets take a look at how this is used:

ipn.php

require "paypal_integration_class/paypal.class.php";
require "config.php";
require "connect.php";

$p = new paypal_class;
$p->paypal_url = $payPalURL; // $payPalURL is defined in config.php

if ($p->validate_ipn()) {
    if($p->ipn_data['payment_status']=='Completed')
    {
        $amount = $p->ipn_data['mc_gross'] - $p->ipn_data['mc_fee'];

        mysql_query("   INSERT INTO dc_donations (transaction_id,donor_email,amount,original_request)
                        VALUES (
                            '".esc($p->ipn_data['txn_id'])."',
                            '".esc($p->ipn_data['payer_email'])."',
                            ".(float)$amount.",
                            '".esc(http_build_query($_POST))."'
                        )");
    }
}

function esc($str)
{
    global $link;
    return mysql_real_escape_string($str,$link);
}

First we create a new paypal_class and assign it PayPal's URL. The rest is just a matter of calling the $p->validate_ipn() method and it will do all the hard work for us. If everything went OK, we insert the amount of the transaction, the email of the payee and the transaction id to the dc_donations table. It is probably a good place to note, that this page is not visible to the end user, it only exists to listen for IPN notifications from paypal which happen on the backend.

thankyou.php

require "config.php";
require "connect.php";

if(isset($_POST['submitform']) && isset($_POST['txn_id']))
{
    $_POST['nameField'] = esc($_POST['nameField']);
    $_POST['websiteField'] =  esc($_POST['websiteField']);
    $_POST['messageField'] = esc($_POST['messageField']);

    $error = array();

    if(mb_strlen($_POST['nameField'],"utf-8")<2)
    {
        $error[] = 'Please fill in a valid name.';
    }

    if(mb_strlen($_POST['messageField'],"utf-8")<2)
    {
        $error[] = 'Please fill in a longer message.';
    }

    if(!validateURL($_POST['websiteField']))
    {
        $error[] = 'The URL you entered is invalid.';
    }

    $errorString = '';
    if(count($error))
    {
        $errorString = join('<br />',$error);
    }
    else
    {
        mysql_query("   INSERT INTO dc_comments (transaction_id, name, url, message)
                        VALUES (
                            '".esc($_POST['txn_id'])."',
                            '".$_POST['nameField']."',
                            '".$_POST['websiteField']."',
                            '".$_POST['messageField']."'
                        )");

        if(mysql_affected_rows($link)==1)
        {
            $messageString = '<a href="donate.php">You were added to our donor section!</a>';
        }
    }
}

After the use has donated, he is redirected by PayPal to our thank you page. Here he can add himself to the donor list by filling in a form. Wen redirecting, PayPal places transaction data in the $_POST array, which is available to thankyou.php. We can use this data to confirm that the user has in fact donated, and not just navigated manually to thankyou.php, bypassing PayPal. After the form is submitted, the user is added to the dc_comments table.

donate.php

require "config.php";
require "connect.php";

// Determining the URL of the page:
$url = 'http://'.$_SERVER['SERVER_NAME'].dirname($_SERVER["REQUEST_URI"]);

// Fetching the number and the sum of the donations:
list($number,$sum) = mysql_fetch_array(mysql_query("SELECT COUNT(*),SUM(amount) FROM dc_donations"));

// Calculating how many percent of the goal are met:
$percent = round(min(100*($sum/$goal),100));

// Building a URL with Google's Chart API:
$chartURL = 'http://chart.apis.google.com/chart?chf=bg,s,f9faf7&cht=p&chd=t:'.$percent.',-'.(100-$percent).'&chs=200x200&chco=639600&chp=1.57';

Google's Chart Api is an easy way to generate any kind of chart. To use it you just have to create a URL to http://chart.apis.google.com/ which contains settings such as background color, type of chart (in our case a Pie), and a comma-separated list of values which serve as the data. You can include this URL as you would do a regular image, and a chart will be dynamically generated for you.

donate.php

<?php
    $comments = mysql_query("SELECT * FROM dc_comments ORDER BY id DESC");

    // Building the Donor List:

    if(mysql_num_rows($comments))
    {
        while($row = mysql_fetch_assoc($comments))
        {
            ?>

                <div class="entry">
                    <p class="comment">
                    <?php
                        echo nl2br($row['message']); // Converting the newlines of the comment to <br /> tags
                    ?>
                    <span class="tip"></span>
                    </p>

                    <div class="name">
                        <?php echo $row['name']?> <a class="url" href="<?php echo $row['url']?>"><?php echo $row['url']?></a>
                    </div>
                </div>

            <?php
        }
    }
?>

Later in donate.php, we are building the donor list after running a query against the dc_comments table.

Step 4 - CSS

Having all the markup generated and included in the page, it is time to style it. You may find it surprising but the entire design is entirely CSS based and does not use a single image (apart from PayPal's Donate button image that is).

styles.css - Part 1

*{
    /* Universal page reset */
    margin:0;
    padding:0;
}

body{
    /* Setting default text color, background and a font stack */
    font-size:13px;
    color:#9bb370;
    background-color:#f9faf7;
    font-family:Rockwell, 'Courier New', Courier, Georgia, serif;
}

p{
    font-family:Arial, Helvetica, sans-serif;
    font-size:20px;
}

h1{
    /* The Donation Center text */
    border-bottom:1px solid #E3EBD2;
    color:#639600;
    font-size:70px;
    line-height:1;
    margin-left:-20px;
    padding:0 0 0 30px;
}

h2{
    /* The subtitle, notice the line-height property */
    border-left:1px solid #E3EBD2;
    color:#ABC084;
    font-size:35px;
    height:35px;
    line-height:75px;
    margin:-70px 0 0;
    padding:55px 0 0 10px;
}

h3{
    color:#639600;
    font-size:38px;
}

#main{
    /* The main container div */
    margin:40px auto;
    padding:0 0 0 20px;
    position:relative;
    width:860px;
}

You may notice in the demo page, how the Donation Center heading and subheading form an interesting set of lines. These are in fact the bottom and left borders of the h1 and h2 respectively.

styles.css - Part 2

.chart{
    /* The Google Chart is set as this div's background via the style attribute.
    The negative text-indent moves the text outside the box */

    margin:0 0 0 300px;
    text-indent:-300px;
    width:200px;
}

.donations,.chart{
    color:#ABC084;
    font-size:50px;
    font-weight:bold;
    float:left;
    height:200px;
    line-height:200px;
}

.donations{ text-align:right; width:340px;}
.comments{ margin-top:60px;}
.entry{ margin-bottom:50px;}

.comment{
    background-color:#edf2e4;
    padding:20px;
    position:relative;
    margin-bottom:20px;
}

.name{
    color:#639600;
    font-size:24px;
    font-style:italic;
    font-weight:bold;
    position:relative;
}

.name a.url{
    color:#C0D39C;
    font-weight:normal;
    padding-left:10px;
}

.tip{
    width:0;
    height:0;
    bottom:-40px;
    left:20px;

    /* A neat CSS trick which creates a triangle shape*/
    /* from the div's top border */

    border:20px solid #f9faf7;
    border-width:20px 15px;
    border-top-color:#edf2e4;
    position:absolute;
}

Creating a triangle shape with CSS is also possible by setting the width and the height of the div to zero and specifying a big value for the widths of the borders.

With this our PHP & MySQL Donation Center is complete!

Conclusion

You can use this donation center to turn the usually anonymous act of donating funds into a more social and open process. You can possibly modify the code to include Twitter & Facebook integration or improve it in any other way you see fit.

What do you think? How would you improve this code?