Form Tools: generic form processing, storage and access script
Setting up a PayPal-Enabled Form with Form Tools Tutorial Index

Introduction

In my experience, working with PayPal is like pulling teeth. I find their interface deeply unintuitive and convoluted, and their documentation - although extensive - virtually impossible to navigate. If I had any other choice for online payments, I'd leap at it in a second. But I don't: PayPal is the worldwide standard. So until Google Checkout takes over the market, we have to suck it up and learn to do things their way!

This tutorial aims to explain how to integrating your Form Tools form with PayPal and make the process as simple as possible. I've included a zipfile (see below) which does a lot of the dirty work (such as the IPN correspondence) automatically.

Although this tutorial is about setting up a donation form, you can apply anything you learn here to add any PayPal-enabled form, such as a shopping cart for ordering merchandise. Also, although this is about PayPal, the same general process applies for most external payment gateways - so if any any point you want to jump ship and use Google Checkout, WorldPay or something else, you can still learn a lot just by understanding the process described herein.

The bulk of this tutorial is less to do with Form Tools than it is PayPal. Most of the work is figuring out how to send and receive information from PayPal in a format they require. Hooking it up to Form Tools is actually fairly simple, although conceptually may prove a little confusing at first if you're not familiar with Form Tools' "code" submission type. The tutorial begins with an top-down discussion of the overall process. I chose to start with the abstract process rather than the details because it really is vital that you understand precisely what you're trying to do. It's not the sort of task you can just implement then understand in retrospect - you'd be unlikely to succeed setting up your form without knowing what's going on first!

As always, I've tried to keep this tutorial as simple as possible for the not-so technically literate. Here are the requirements:

  • Basic PHP and HTML knowledge, including knowing how HTML form submissions work
  • A PayPal account
  • A PayPal developer's account.
  • This zipfile released by PayPal and modified by myself.It contains a number of pre-built pages for implementing a form on your site.
  • A strong cup of coffee. Or two. Or possibly three.

All of the above points will be discussed below. You can see an example of a PayPal enabled form with Form Tools' own donation form. If this tutorial comes in handy, how about seeing it in action and making a donation? ;-)


Overview

Let's start with a pretty, unintimidating diagram which outlines the whole process. I've simplified a few things (such as the fact that the user can cancel at virtually any step) to keep it clear.


Here's a few important points:

  • All PayPal pages are wrapped in a blue box. These pages are pre-built by PayPal and reside on their servers - generally you don't have to worry about them very much. The pages in the grey box reside on your website. As you can see, when the user fills in and submits the form, they are redirected to and from the PayPal site to complete the transaction.
  • PayPal offers a little control over the appearance of their pages to provide a little homogeneity for the user making the payment - but not much.
  • The first form page - although a single page in the diagram - can be the final page in a sequence of pages, e.g. in a shopping cart process where they enter information bit by bit on separate pages. For simplicity - and because our Donation Form example only requires it - the form is only one page long for this tutorial. Speaking practically, it makes no difference.
  • The "Review Page" is necessary step, but when the user reaches that step, they can be automatically redirected to PayPal if you wish. It is your choice whether or not you display any form submission content for review on that page. Since the donation form is a single page containing very few fields, I felt that this step was not necessary and made it automatically redirect with javascript.

Instant Payment Notification (IPN)

IPN is a service provided by PayPal that automatically notifies your server the instant a transaction occurs. This lets us ensure that all successful payments get marked as "paid" in our Form Tools database.

And here's the other piece of good news: you don't really need to know how it works. The zipfile contains a file with all the functions needed to interact with PayPal to confirm a purchase and mark the submission as complete. So... let's get started setting up your form!


Step 1: Setting up your Form

A look at our donation form

For the sake of this tutorial, we're going to work with a concrete example: the donation form on this site. If you haven't already done so, download the zipfile containing the form and PayPal files - you'll need them for the next section. You might want to open them up and look at them while reading this section.

Here's what the form looks like:

* First Name
* Last Name
* Email Address
City
* Amount $ (Canadian)
Country

You can add as many fields as you would like to this form, but that's outside the scope of this tutorial. One tip, though: if you plan on adding other fields and expect them to get to PayPal, be sure to read the Adding PayPal Checkout to Your 3rd-party Shopping Cart document, listed below in the References section.

Files and Folders

Here's a list of all the files and folders in the zipfile.

  • includes - folder
    • config.inc.php - written by PayPal. This file contains various configuration settings for your form.
    • global_config.inc.php - written by PayPal. Some global configuration settings.
    • main.css - just a custom stylesheet.
    • validation.js - for add basic validation on the donation form.
  • cancelled.php - the page that users get redirected back to if they cancel a donation on the PayPal site.
  • index.php - the donation form.
  • ipn.php - a script that handles the IPN interaction with PayPal.
  • process.php - the review / submit to PayPal page (not to be confused with Form Tools' own process.php file).
  • success.php - the page that users get sent to after a successful donation.

Adding the donation form to Form Tools

  1. Upload the entire content of the zipfile to your website, perhaps in a /donate folder.

  2. log into Form Tools and click on the "Add Form" button on the Forms page.

  3. On the first page ("Main Information") fill in the relevant information:
    1. set the form URL to the URL of the index.php you just uploaded.
    2. set the submission type to "Code" and "Submissions need to be finalized".

  4. The next page will now generate some PHP and HTML for your particular form.
    • For #1, copy and paste the two lines of code into the top of your process.php page that you just uploaded. You should see a comment at the top of the page saying which two lines to overwrite.
    • For #2, copy and paste the two HTML lines, e.g.
      <input type="hidden" name="form_tools_initialize_form" value="1" />
      <input type="hidden" name="form_tools_form_id" value="8" />
      into your index.php page. Again, you will see a comment showing which two lines to overwrite.
    • Ignore #3; the process_form() code is already added to the top of your process.php page.

  5. So far so good! Now, open up your index.php page in your browser (if it's already open, click refresh so it's got the latest changes). Fill in all fields and click "DONATE". You should a message like this:
  6. Now return to Form Tools and click the "Refresh Page" button at the bottom of the page. This will then show you a "NEXT STEP >>" button to let you continue. Click it.

  7. On the next page you will see all database fields listed. You may want to delete the "DONATE" field since it's not needed. Just check it's "Del" checkbox and click "UPDATE". After changing the field sizes to whatever you want, click "NEXT STEP >>" again.

  8. This next page lets you control the appearance of the form in Form Tools.
    • click "SMART FILL" and rename the display names to whatever you want.
    • check whatever fields you want to appear as columns on the main submission listing page (recommended: 3 or 4).
    • click "UPDATE" then "NEXT STEP >>" to continue.

  9. Finally, as it says on the final page, remove this hidden field from your form:
    <input type="hidden" name="form_tools_initialize_form" value="1" />

And that's it! All form submissions will now be stored by Form Tools, but they will NOT appear in the user interface by default. In order to make them appear, we need to "finalize" them. This step is coming up...!


Step 2: Configuring your Donation Form with PayPal

  1. Get a PayPal account
  2. Configure your PayPal account (the "Auto Return" setting)
  3. Get a PayPal Developer account
  4. Configure your form to send the correct values to PayPal
  5. Customize the files for your server
  6. Making some test payments
  7. Going live!

Get a PayPal account

If you haven't already done so, sign up for a PayPal Account here. Choose the account type (Personal, Premier or Business) that is right for your particular case. This account (email address) will be where all donations will be sent.

  1. Personal
    • free to send / receive payments
    • cannot receive payments from credit cards
    • limited to $1,000 in payments per month
  2. Premier
    • fee for accepting payments
    • may receive payments from credit cards
    • includes a wide variety of tools (like PayPal shopping cart, subscriptions, recurring payments and more)
  3. Business
    • Unlike the other accounts, your PayPal account is displayed as your company name instead of your personal name.
    • same fees as the Premier account and allows payments from credit cards

Due to the Personal account's limitation of not being able to receive payments from credit card, I'd recommend you opt for a Premier or Business account - despite the fees.

Configure your PayPal account

Next, if you have a Premier or Business account, you'll need to make a small configuration change to your PayPal settings.

  • Log into PayPal
  • Click on your "Profile" tab
  • Click on "Instant Payment Notification Preferences"
  • Check the "Instant Payment Notification" checkbox and enter in the URL of your ipn.php file (located in the zipfile) into the Notification URL field. Note: you can override this URL for any form (so you can use the same PayPal email to accept payments on multiple sites).

Get a PayPal Developer account

In order to test your form to check that everything works the way you want, you will need a PayPal developers account. You can sign up for one here.

Configure your form to send the correct values to PayPal

Next, you will need to configure the PHP script to send the appropriate values to PayPal for processing. Open up the includes/config.inc.php file and edit the following lines, found at the very top. 

// PayPal settings
$paypal["business"]      = "joebloggs@something.com"; // your PayPal account
$paypal["site_url"]      = "http://www.formtools.org"; // your website root URL
$paypal["image_url"]     = "/images/logo.jpg"; // (optional: will be included in PayPal pages if defined)
$paypal["success_url"]   = "/donate/success.php"; // where the user is directed to after successful payment
$paypal["cancel_url"]    = "/donate/cancelled.php"; // where the user is directed to after cancelled payment
$paypal["notify_url"]    = "/donate/ipn.php"; // the location of the ipn.php file (in zip)
$paypal["currency_code"] = "CAD"; // [USD,CAD,GBP,JPY,EUR]
$paypal["post_method"]   = "fso"; // "fso": fsockopen, "curl": cmd line, "libCurl": PHP compiles with libCurl
$paypal["curl_location"] = "/usr/local/bin/curl"; // only needed if you use the curl or libcurl post_methods
 
// When you are finished testing, change this to: https://www.paypal.com/cgi-bin/webscr
$paypal["url"]           = "https://www.sandbox.paypal.com/cgi-bin/webscr";

After changing those settings, you're ready to put through a test submission.

Customize the files for your server

Next, you need to customize the paths to the Form Tools files in two of the files: process.php and ipn.php. At the top of both of those two files, you'll see these two lines: 

require("/path/to/FormTools/global/library.php");
require("/path/to/FormTools/process_code.php");

Update them to the appropriate paths for your server.

In ipn.php, after those two lines, make sure the $form_tools_form_id value in ipn.php is correct as well.

Making some test payments

Now the fun / horror starts! Log into your PayPal Developer's account. Everything done through a developer account is "pretend" only - no money is actually changing hands. It provides a useful service to debug your form before pushing it live.

After logging in, you will need to create two accounts: one for the "seller" (i.e. to simulate YOUR account), and one for the buyer. Be sure to enter the seller email as the $paypal["business"] option in the config.inc.php file listed above.

Now open up your form in your web browser. If you configured everything properly, after submitting your form you should be redirected to the PayPal site where it will prompt you to log in. Log in using one of your test accounts and make the payment. Again, everything you do in the PayPal sandbox (i.e. while the paypal URL is: https://www.sandbox.paypal.com/cgi-bin/webscr) is fake. No payments are actually made, it's simply for test purposes only.

Make sure you try putting payments through, cancelling payments and clicking on "Return to Merchant" on the PayPal site to verify all links work properly.

Lastly, if you chose to do the optional section above with setting up a custom field in the database for the PayPal return information (see the end of the Adding the donation form to Form Tools section), you will need to uncomment the section at the top of success.php and set the appropriate form ID.

Going live!

And finally, it's time to go live! All you need to do to push it live is to change that one value in your includes/config.inc.php file. Change this line: 

$paypal[url] = "https://www.sandbox.paypal.com/cgi-bin/webscr";

to this:

$paypal[url] = "https://www.paypal.com/cgi-bin/webscr";

And, if necessary, change the $paypal["business"] line in config.inc.php to your real paypal address. And you're done!


A Few Final Tips

  1. Working with the Developers section of PayPal can be pretty bewildering at first, but it makes more sense the more time you spend with it. Don't forget that when using the PayPal sandbox, emails don't get sent to your normal email account, but to your development email account.
  2. If your payments are going through properly, but nothing appears in Form Tools, chances are the IPN isn't configured properly. Try adding some mail("your@email.com", "subject", "message"); lines in ipn.php to confirm that PayPal is at least posting information to that URL. If not, you know the problem is either with your $paypal["notify_url"] setting or with the setting you set up in your PayPal account under IPN Preferences.
  3. If you get stumped, try posting either in our forums or on the PayPal developer forums (listed below)

References


Has this tutorial helped? See it in action and donate now! :-)