Text Size

PDF

How To - Sell your PDF files by integrating Doculicious and PayPal

We've had a lot of requests for payment integration with Doculicious, and this is something we've thought about adding. One issue is that Doculicious is a little different than other form builders - a lot of the time the people who contact us want to sell the output of the form itself and not use the form as just an order form. People are selling Visa applications, Government forms, Award certificates and a range of other forms using Doculicious. Integrated payment within Doculicious will be a while away, so I thought the next best thing was to write a comprehensive tutorial on how to integrate Doculicious and PayPal.

This tutorial will explain how you can sell a PDF form on your website using Doculicious and PayPal, but the concepts here can easily be used to gather payment for any other type of order. After going through the tutorial, you will be able to create a process that is something like this:

  1. Customer fills in your Doculicious form from your website;
  2. When complete, they are redirected to a sales page where they can purchase the completed form for $10;
  3. They click through to PayPal and enter their payment details;
  4. They return to a Thank you page on your site;
  5. PayPal sends you an "Instant Payment Notification" informing you of the payment success or failure;
  6. On success, you send the customer a link to the completed PDF form.

This is going to be a fairly long post, so I've split it into sections and included a table of contents to make it easier to navigate. I'm going to go through the whole process - from how to set up a PayPal sandbox account for testing, to using the Doculicious API to retreive a submitted entry. So feel free to skip bits you don't need.

Table of contents

  1. Setting up a PayPal testing environment
  2. Creating a PayPal "Buy Now" button
  3. Create and configure the Doculicious form
  4. Set up your PayPal purchase form
  5. Create the PayPal IPN page
Setting up a PayPal testing environment

There are a couple of ways to test your PayPal buttons and integrations. The first, and easiest, is to use your normal business account and take advantage of the 60 day refund option that PayPal provides. This lets you cancel a transaction and all the fees will be refunded. PayPal lets you have 2 accounts - one business and one personal. So you just use your personal account to purchase from your business account and then refund after the transaction. Easy, but messy. After a small while it gets pretty annoying to keep refunding.

The second way is to use the PayPal testing environment ("the PayPal Sandbox") where you can create multiple buyer and seller accounts to test your buttons. This is much cleaner, and is pretty easy to set up.

First, go to the PayPal Developer web site and sign up for an account. Use a different email address than your other PayPal accounts. Once you are signed up, log in.

The PayPal sandbox let's you pretend to be a buyer and a seller, and create fake accounts with essentially play money and credit cards. For our purposes, we are just going to create one buyer and one seller account. Click on the "Create a preconfgured account" link.

You will then be shown a form like the following one. Select the account type as "buyer", choose an email address and make a note of the password. Make sure you add some money to the account balance.

Once created, go and do the same again, but make this one a "Seller" account. When you're done, you should have 2 accounts in your sandbox, like so:

We can now use these accounts to simulate our purchases, and also create buttons for testing without worrying about breaking our production setup. It's a good idea to write down both the email addresses and the passwords you noted down when creating them. Do this in notepad so you can access them easily later.

Remember, you need to be logged into the PayPal sandbox to use the mock buyer and seller accounts.

Whenever you make a purchase, you need to use the full buyer email address created for you. When you sell, you need to use the seller email address. Paypal also let you see all email communications. We won't be using that too much, but it is useful to know.

In the next section you need to create the button for selling your PDF, so enter the sandbox site using your pretend seller account. Click on the radio button next to the seller, and press on the "Enter Sandbox Test Site" button. A new window will display where you can log in using the password noted earlier. You are now inside the PayPal sandbox, and should recognize this as similar to your normal account screen.

Creating a PayPal "Buy Now" button

To sell our Doculicious PDF form, we are going to use a PayPal "Buy Now" button. You do this within the PayPal site by clicking on the "Merchant Services" tabk at the top, then click on the "Buy Now Button" link near the top. There are 3 steps to create your button:

Step 1 - Choose the button type and enter details

We need the Template UID here because later it is used when we call the Doculicious API.

  • The Item Name can be anything you want. 
  • The Item ID needs to be the Unique ID of your Doculicious Template. You can find this from the Doculicious Dashbord by clicking on the orange "api" link, and looking for the text labeled "Template UID".
  • Enter a Price
  • Enter the Currency
  • Continue on to Step 2

Step 2 - Track inventory, profit and loss

This step is pretty small, just make sure the check box to save the button at PayPal is clicked. You don't need to do this, but it makes it easier to edit later. When done, continue to Step 3

/p>

Step 3 - Customize advanced features

This step lets you add some advanced features, one of which is what we use to have PayPal notifiy us when a purchase is made. This is called the "Instant Payment Notification" and we can set up the URL that PayPal will notify here. There are also a few other things we can turn off, as they are not really needed, such as shipping address and customer message. If you would like this information, feel free to keep them turned on.

The IPN is how PayPal notify us of a successful payment. We don't send the completed PDF until we receive this, and it's valid!

  • Enter a URL for when customers cancel their checkout. This should be a page on your website with some information on how they can continue their purchase.
  • Enter a URL for then customers finish their checkout. This should be a page on your website that informs the customer of what they just purchased and when you will deliver it. We will go into more detail about this later when we create these pages.
  • In Advanced Variables, make sure the checkbox is clicked, and add the following line:

    notify_url=https://www.YOURWEBSITE.com/paypal/ipn.php

    (You can use HTTP here instead of HTTPS if you dont have an SSL certificate for your site, but you should really get one for security purposes.)

  • When done, click on the Create button at the bottom.

The next page will display the code that you need to put onto your website for this button to work. Make sure you copy and paste this into a text file for later. We need to make a couple of small changes before this goes onto your site. These will be outlined in a later section of the tutorial.

Create and configure Your Doculicious form

Click here to learn how to build a Doculicious form

If you are reading this tutorial, you most likely have a Doculicious form that you want to sell or integrate with a Payment gateway. If not, you can use one of the examples from the "Template Gallery" or create a new form first. You don't need anything fancy to follow this tutorial, you could even just create a basic test form to get everything working first. Once your form is created within Doculicious, you need to activate it which will automatically add it to your Doculicious Dashboard.

The Dashboard is where you can change the settings for your form. Below we explain what changes to make and why they are made. Below this is a quick summary (for those that don't like to read :)

Disable PDF download

You don't want the user to be able to download the PDF file once they have completed the form, so checking this will disable that feature.

Clicking on Disable PDF download will automatically check the Save Entries box. 

Optionally set notifications

When Save Entries is turned on, the system will allow you to set notifications. On premium accounts, you can also attach the completed PDF to the notification email, or use custom notifications to send the PDF to different email addresses depending on choices made on the form. This is a good time to set any notifications you may want to receieve. Don't use this to send the user their PDF file, as they wouldn't have paid at this point in time.

Turn on Redirect 

Please note that Redirect is a premium feature, and will not be available on free accounts.

After your user completed the Doculicious form, you want to redirect them to your payment page. So you need to check the Redirect box and enter the URL to your payment page. We will edit this page at a later step of this tutorial to add the PayPal button you created earlier, so now you can just put in the URL where you are going to put that page. It may be a good idea to create that page now so that you can test the redirect working. 

Summary

Ok, fo all you non-readers out there ... this is the quick summary of what we just did to configure the Doculicious form for PayPal integration:

  1. Turned on Disable PDF Download
  2. Turned on Redirect
  3. Entered a Redirect URL to a page with the PayPal button on it
  4. Turned on Save Entries (Optionally, added notifications.)
  5. Clicked Save
Set up your PayPal purchase form

We now need to create the page that people are redirected to after they complete your Doculicious form. This is pretty easy, and the main thing you need on this page is the PayPal button code that you copied earlier. However, we are also going to add another field which contains our unique entry ID of the submitted form. 

So, open up the page you set as the Redirect URL from the earlier step, and past in your PayPal button code. It should look similar to this:

1
2
3
4
5
6
<form action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post">
    <input type="hidden" name="cmd" value="_s-xclick">
    <input type="hidden" name="hosted_button_id" value="957FC8G74KTR4">
    <input type="image" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
    <img alt="" border="0" src="https://www.sandbox.paypal.com/WEBSCR-640-20110429-1/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

Now we need to add a small bit of PHP code before the PayPal button code. This gets the Unique ID of the entry just made so that we can send this to PayPal.

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php 
    //Check that the doculicious URI is set - It should be
    if(isset($_GET['dclcs_entry_uri']))
    {
        $uri = $_GET['dclcs_entry_uri'];
 
        //Put all the parts of the URI into an array
        $uri_parts = explode("/", $uri);
 
        //Get the last item in the array. This is the uniqeID of the submitted form 
        $document_id = array_pop($uri_parts);
    }
?>

Ok, we have the $document_id variable with the unique ID in it, so we can add a hidden field to the PayPal button code that contains this using the custom PayPal variable, which will ultimately be passed to the IPN code:

1
<input type="hidden" name="custom" value="<?php echo($document_id);?>">;

Add this line in between 2 of the hidden fields of the PayPal button.

This page will just have a PayPal button and nothing else, so you should add some more text above the button explaining things to your customer. Something like:

Thank you for using our service. Please click the button below to pay for your form using PayPal. Once confirmed we will send through a link where you can download the completed PDF file.

The completed code for the PayPal form page can be viewed here.

Create the PayPal IPN page

Ok, this is the final step - creating the PayPal IPN page. This is what links everything together to provide the PDF to your customer, and tells you that the payment was successful. You will remember that we provided PayPal the address of this page when creating our custom button, and it was something like this:

1
notify_url=https://www.YOURWEBSITE.com/paypal/ipn.php

You now need to create or edit that page and put in the PHP code which will talk to PayPal to verify the payment, then talk to Doculicious to get the completed PDF and finally email your customer with the details on how they can download the file. I will go through the file line by line explaining what we are doing. Top help you follow along, you can download an example containing all the code here.

In the first part of the IPN page we declare some default variables that are used later on in the script. This is where you customize the script with your details. The inline comments will explain what all the settings are for.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//CONFIGURATION OF DEFAULT VARIABLES
//Your PayPal Seller email address (Change to your PayPal sandbox email for testing)
$paypal_email = "chris@digitalcarpenter.com.au";
 
//The currency you use for your PayPal buttons
$currency = "USD";
 
//The cost of your form. Make sure you add the cents
$cost = "10.00";
 
//The email address used to send you notification emails
$from_email = "email@YOURDOMAIN.com";
 
//The email address used to receive notification emails on success or failure
$notification_email = "notifyme@YOURDOMAIN.com";
 
//Your API access ID and Security key from the API link on the dashboard 
$api_access_id = "xxxxxxxxxxxxxxxx";
$api_security_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 
//Send this back to PayPal to validate the fields
$req = 'cmd=_notify-validate';

 

The following lines are to verify with PayPal the values that are being sent. PayPal is doing a POST to this IPN page with all the details of your transaction. What you are doing here is sending those details back so that PayPal can verify you have the right information. This is to help ensure that people can't post to your IPN page and tell you about fake transactions.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//Add each field to a value we will post back to PayPal
foreach ($_POST as $key => $value) 
{
        $value = urlencode(stripslashes($value));
        $req .= "&$key=$value";
}
 
//Post back to PayPal
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
 
//PayPal Production
$fp = fsockopen ('ssl://www.paypal.com', 443, $errno, $errstr, 30);

 

Next we check if there was a failure communicating with the PayPal servers, and if there was send an email to the notification address you defined earlier with the details:

 

1
2
3
4
5
6
7
8
9
10
11
if (!$fp) 
{
 
        //Send an email on failure with the error message (errstr) from paypal
        $from = "From: " . $from_email;
        $to = $notification_email;
        $subject = "HTTP ERROR";
        $body = $errstr;
 
        mail($to, $subject, $body, $from);      
}

 

If we got a result from PayPal, we then check if it is "VERIFIED", and if so get the POSTed values that PayPal has sent us:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
else
{
    fputs ($fp, $header . $req);
    while (!feof($fp)) {
        $res = fgets ($fp, 1024);
        if (strcmp ($res, "VERIFIED") == 0) 
        {
            //The custom field contains the unique Doculicious Document ID of the completed form and the item_number contains the Template ID.
            $item_number = $_POST['item_number'];
            $document_uid = $_POST['custom'];
                        
            $item_name = $_POST['item_name'];
            $payment_status = $_POST['payment_status'];
            $payment_amount = $_POST['mc_gross']; 
            $payment_currency = $_POST['mc_currency'];
            $txn_id = $_POST['txn_id'];
            $receiver_email = $_POST['receiver_email'];
            $payer_email = $_POST['payer_email'];

 

We need to check if some values are what we expect them to be. Payment Status should be "Completed", the price should match what we have configured, as well as the currency and reciever email address:

 

1
2
3
4
if (($payment_status == 'Completed') &&      //check the payment_status is Completed
    ($receiver_email == $paypal_email) &&    //check that receiver_email is your Primary PayPal email
    ($payment_amount == $cost ) &&           //check they payed what they should have
    ($payment_currency == $currency))        //check that payment_amount/payment_currency are correct <span _fck_bookmark="1" style="display: none; "> </span>

Once we confirm that all that is good, we can now use the Doculicious API to get the PDF and save it to our website somewhere. To do this, we are going to use CURL. First we need to set the parameters for this:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//The full authorization string - needed for the header. API access and security codes are set at the top of the page
$auth = "authorization:DCS " . $api_access_id . ":" . $api_security_key;
 
//This is the URL to get completed the completed PDF for a specific entry. 
$resource_uri = "https://api.doculicious.com/entries/" . $item_number . "/" . $document_uid . ".pdf";
 
//Initialize curl and set URL and other appropriate options
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $resource_uri);
 
//Send the authorization details in the header
curl_setopt($ch, CURLOPT_HTTPHEADER, array($auth));
 
//This tells curl to return the actual result of the API call (ie, the PDF or XML error message). Returns False if HTTPS get fails.
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE );
 
//SSL Settings
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
 
//Execute the API call
$output = curl_exec($ch);

The last line of the above snippet of code executed the cUrl request, the next bit of code will process the response we receive from Doculicious. First we check that there were not any cUrl errors, then we get information about the cUrl response so we can check if Doculicious sent us what we wanted.

The 200 result means everything went OK. If Doculicious couldn't find the PDF we asked it for, we would have gotten a 404 response, and the code below would have printed out an error message.

If everything is OK, we save the file to our website, and email the customer with a URL to where they can download it.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
if(!curl_errno($ch))
{
        $info = curl_getinfo($ch);
 
        //200 means success.
        if($info['http_code'] == 200)
        {       
                //Save the PDF file to our website
                $my_file = "/YOUR/WEB/ROOT/customer-files/" . $document_uid . ".pdf";
                $fh = fopen($my_file, 'wb') or die("can't open file");
                fwrite($fh, $output);
                fclose($fh);
 
                //Create the URL where the customer can download their PDF
                $download_url = "http://www.YOURDOMAIN.com/files/" . $document_uid . ".pdf";
                
                //Send an email to the purchaser with a link to download the PDF file
                $from = "From: " . $from_email;
                $to = $payer_email;
                $subject = "Your PDF form is ready.";
                $body =  'Thank you for your purchase. Please use the link below to download your PDF file:' . PHP_EOL . PHP_EOL .  
                                 $download_url . PHP_EOL . PHP_EOL .  
                                 'Regards,' . PHP_EOL .
                                 'YOUR NAME' . PHP_EOL;
       
                mail($to, $subject, $body, $from); 
        }
        else //there was an error, so output the content
        {
                header("Content-type: " . $info['content_type']);
                echo $output;
        };
}

The rest of the file contains some error handling, basically sending notifications when things go wrong.

The completed code for the Doculicious PayPal IPN can be seen here.

Automatically create web forms from PDF forms

I love this photo ... it sort of sums up how I feel after releasing the latest version of our online PDF web form tool, Doculicious.com: happy, a little delirious and looking to relax on the beach after a hard bit of work. Sydney's getting cold now though, so I'll probably just stay in and program some more cool features.

Anyway, this latest release has something which has been on the drawing board for a while. The ability to upload a PDF file with fields and have it converted into a web form has been requested by many of our users, and I'm happy to say that our first version of this is ready to go. Our goal with this release was to enable someone with a bunch of PDF forms to upload them and have them automatically converted to web forms. This means that if you have a PDF file with fields, you will have a working web form in minutes after uploading it to Doculicious. If the original file doesn't have fields, the system will still help, but there will be some manual work to do. I'll give some tips on re-creating a form like this very quickly, so don't worry ... if your PDF files don't have fields, this new feature will still cut the time it takes to create a form by at least half.

PDF's are messy

PDF files are not nice ordered documents that make it easy to extract text. However, they print very well, and will pretty much look the same when sent to any printer. This gave us a clue as to how to implement the form conversion. We take the uploaded PDF and generate screenshots of each page by printing to an image file. We then create a new Doculicous template and use the images of each page as a background for that page. If the PDF has form fields, we re-create each one in the correct place, ensuring that drop down lists are filled with the right options, checkboxes and radio buttons are created and using the right groups and that some of the same formatting is applied, such as text alignment. Doculicious has a great feature that will scale images to load faster when viewed on the web, but will use a larger image when output as PDF. This lets converted forms stay small for the web form, but still print nice when downloaded.  Ok, enough background, here is the detail.

Converting your PDF to a web form

Doculicious makes this really simple. Just follow these steps:

Step 1 - Go to "Your templates" and click on the "Upload form" button

This will show the "Choose file" or "Browse" button , depending on your web browser. 

Step 2 - Click to choose a file to upload

You can choose a PDF file, postscript file or image files. Only PDF have form fields, but postscript can have multiple pages, and can be useful to convert a MS Word form into a web form. Images can be used to create single page templates, and are great if your source form is a scan of a paper form.

Step 3 - Wait for the PDF to Web Form conversion to complete

It should only take a few seconds, but PDF's with many pages could take a while. When completed, refresh the page to see your new template at the top.

Step 4 - Web form goodness! You're ready to rumble

That's it. If your PDF form had fields, they should be converted properly into Doculicious elements, so all you should need to do now is load up the template and check that everything looks ok, then press publish and activate it on your dashboard. Some things you may want to consider is turning on number validation for numeric only fields and checking that each form element has a nice name or your CSV downloads may be hard to decipher. Also, you may find that some elements may not line up perfectly with the background image. In my experience text boxes all work fine, but radio buttons and check boxes may be off by a few pixels. A small nudge using the arrow keys will fix this up in no time.

My PDF doesn't have fields, what do i do?

Don't worry, atleast 50% of your form is complete. You just need to add the text boxes and move them into position. Luckily you have a nice background image that will help you do this, and Doculicious' keyboard shortcuts will help you get this done fast. We'll soon be posting a video capture of how to do this really quick, but for now make sure you use the "c" for clone keyboard shortcut. Most text fields on a PDF form are the same width, border style, font style etc. You just need to create one text field, put it in place, and then press "c" select the new element and place in the right position, then press "c" and move the new one down to the right position, then press "c" ... you get the idea. Forms that use to take 60 minutes to re-create can be done in about 10 minutes or less!