Michael Kovacs' photos More of Michael Kovacs' photos
Recommend Me Cable Car Software logo

Sunday, January 15, 2006

Working with paypal as a developer

I've been working with paypal's developer sandbox and payment mechanisms as of late and while it's not been completely horrible I really wonder how someone else hasn't come along to eat paypal's lunch based on the site usability and clarity of documentation.

First it's not entirely clear when you visit paypal.com what exactly you need to do to get going. You end up clicking through various links not entirely certain that what you're looking for is contained within one area. Over time I've been able to get all the information I've needed via 3 means:

1) The paypal site (pages and PDF integration manuals)
2) The paypal hacks book (not sure this book is worth the price but it was a little helpful)
3) The developer forums (I didn't post or spend much time here but some google searched provided answers in this forum)

Now this could be just me but I didn't find what I thought would be the most common case which is "I have a site and I know how to code, show me all the steps, cut to the chase and give me a good example site to follow.". Paypal doesn't do this but the paypal hacks book did go into some of this a little bit though could've been better as it is just a collection of small hacks.

So at any rate, for anyone else out there that wishes to integrate paypal into their site I'm going to put down some of the "skinny" here that you need to understand in order to know how to proceed.

First off Paypal has a couple different mechanisms that you can utilize for processing payments:

1) A web services API
2) URLs that you call and that trigger callbacks to your site. These are known as IPN and PDT. IPN stands for "Instant payment notification" which is sort of ironic because it's asynchronous and is advertised to be mostly instant but can be delayed by up to 4 days. PDT, which stands for "Payment data transfer", is synchronous and will return transaction information if you provide paypal with a return URL after the transaction is complete. I'll get into more detail about the differences here in a minute.

I chose to go with #2 for what I interpreted to be the most expedient way to get this work done partially because ruby's support here seems to be kind of light and not commonly used yet so I figured HTTP POST and GET might be safer for now.
OK so #2 is my choice but do I use IPN or PDT? Let's go over how each one works roughly...


  1. The user clicks on your payment button which posts a form to paypal's site containing information about the transaction (product description, item number, your business email, price, etc).
  2. The user makes their payment at paypal's site. (The user isn't returned to your site unless you specify a URL to return to)
  3. Paypal then calls back to a URL you provide to them, i.e. http://mysite.com/paypal_ipn_callback In this callback paypal provides all the information about the transaction so that you can verify things are correct and proceed to the next step(s) for your customer. This URL is intended to be a "behind the scenes" conversation between yourself and paypal.
  4. When your site receives this callback you acknowledge the call with paypal by making a call back to verify the contents of the transaction.
  5. Paypal either returns a VERIFIED or FAILED result to your call.
  6. Proceed based on the results of the transaction (ship your product, contact the customer if there's a problem, etc)

Like I said earlier this callback from paypal to your site is asynchronous so if you'd like to make products available to users for immediate download this can present a problem especially if the delay is several days. For cases where you'd like to have instant downloads it seems like PDT is the better choice. I was hesitant at first about PDT because it seems like there were several warnings about IPN being the recommended and more reliable mechanism. It's possible to use a combination of both but first let's go over how PDT works..


  1. The user clicks on your payment button which posts a form to paypal's site containing information about the transaction (product description, item number, your business email, price, etc).
  2. The user makes their payment at paypal's site.
  3. The user is returned to a URL you specify with the details of the transaction embedded into the URL. i.e. http://mysite.com/thank_you&txn_id=sjkjfa234j&blah=foo (This return URL is either given to paypal in your buy now button or in your account settings)
  4. Your site takes the transaction ID, a PDT identifier that is given to you by paypal when you enabled PDT in your settings, and makes a call back to paypal to verify the transaction is valid.
  5. Paypal returns immediately with a status message and, assuming the transaction is valid, the details of the transaction.
  6. You then proceed to process the results of the transaction and deliver your product.

So as you can see the mechanisms are very similar with the major difference being the response time guarantee. PDT is synchronous but you are warned that it may not be available and that the use of IPN for a backup and verification mechanism is recommended.

So now that we've got an idea of how the mechanisms work how do we actually use this stuff? The first thing to do is to signup for a developer account and create a sandbox. This painful mechanism is just a mock of the real paypal site and what your account would be like when you're ready to go live. The main reason that it's painful is that the session times out what seems to be every 5 minutes. So while you're working on your code you end up having to log back in and relaunch your sandbox.

OK, you've got your developer account, created a sandbox, launched it, and are ready to start testing transactions. What do I need to do next? Well depending on if you're using IPN, PDT, or both you need to do some configuration. This configuration
resides under the "My account" tab in the "profile" subtab. Here you'll find the settings for IPN and PDT under "Instant Payment Notification Preferences" and "Website Payment Preferences" respectively.

After you've set things up you can create your code to call paypal, receive callbacks, and process your transactions. There's certainly more details in there, for example you're going to want to create another account in your sandbox that you can use for making purchases and have paypal generate a fake CC number to store in that account. This was just meant to get to the salient points of how the paypal mechanisms work and what's required of someone writing code. I can certainly go into more detail and even post my ruby code for handling IPN and PDT as the existing library out there for rails focuses solely on IPN and is basically a few convenience methods for acknowledging an IPN callback from paypal.

Hope this is helpful to someone out there embarking upon paypal integration.

Cool. Now I know who to talk to if I ever want to do this...
Good overview, thanks!
thanks. I'm just starting to look into paypal integration, and the documentation is indeed scattered.
Very clear and up-to-the-point
Hi All,

I could not find any documentation on how to integrate with Java/JSP. Anyone got any ideas on that?
If you're using Rails...I tried Paypal integration and I found their tech support to be so laughably horrible that I abandoned them. Not to mention extensive downtime on the Developer site from which you're supposed to download your API credentials. It turned into a bad joke. Since then I opened an account with Authorize.net and have been using the ActiveMerchant plug-in to communicate with them...piece of cake and never had any problems.
Thanks..Good overview
Hi Micheal,

It's 2010 right now and I had to do a paypal integration, I also had exactly the same experience as you, telling you that time does not solve some problems, it's incredibly dense information and developer documentation doesn't normally lead you in the right direction, can confuse you, the NVP documentation examples are programmed by what looks like a first year business student, has no good programming conventions, it's messy, ugly and not what I would call a good template, but it works.

In PHP, which is not the same I grant you, there are more problems in that there isnt even a good library to use that I can just create an object, call 5-6 methods with parameters and bam, done. Nooooo, thats too easy. Instead you can use an off the shelf cart to do it for you, except when they are not usable in your system either due to the huge amount of styling/redesigning you'd have to do (negating the benefits of using them through absorbtion of the time saved) or because they don't install on your environment, or need things you cannot give them. So in the situation where you need to do a custom job, your custom job extends to writing a paypal layer as well.

even phppaypalpro was awful, it didnt work, the documentation didnt explain why it didnt work and after 2 days of trying to debug a system I didnt understand, I just gave up. Why can't everyone just do it "the right way"!!!

The sandbox, as you quite rightly said 3 years ago when you wrote this post, is awful, is that seriously the best they could do? Is google checkout (which I recognise didn't exist 3 years ago) doing this in the same way? I doubt it.

paypal I think has created a dinosaur that cannot be changed, nor killed because of it's huge size, it just has to continue, even years later, with the same problems, because the engineering challenges of rewriting parts are just too hard, too error prone, or just impossible.

What I have done, is write a small library that you can drop a single php script into your website, create an object, call some methods and communicate with paypal, I've developed it to be simple, as clean as possible and as extendable as possible (because at the moment, it just supports what I need, which is quick'n'easy webpayments pro). I think what I will do is sell it on my website, using paypal of course (hahahahaha) for 5 euros a download, you reckon I have a market?

of course, I am not here to sell that library, I am just pointing out that after all that hard work, I've done something that I don't think anyone else has done and I did it all because of problems we both experienced. that paypal is just a dinosaur and I am waiting for the meteorite to destroy them all so we can get on with our lives and not waste time on systems that are not fit for purpose.
Hi, I found good java paypal library at sourceforge.net - http://paypal-nvp.sourceforge.net/index.htm
I found this very usefull. I was looking for a quick overview of how paypall works what needs to be done to get started.
As a Paypal developer I am using Paypal Express Checkout API. I have a premium account properties in one file and business acccount in a second one. Its much convenient. You will find it here: http://www.paypaljava.com
try the link with great tutorial for Java Paypal Developers!
Nice tutorial really helped for implementing paypal using java
very usefull information thanks
today is 2016 and your review still relevant. Tons of documentations on the website, but so hard to reach the goal. As java developer I'd like to receive a simple callback from paypal to my server. I'm digging tones of code and docs, but still no progress...
BTW, www.paypaljava.com doesn't exist anymore :(

Post a Comment

<< Home

This page is powered by Blogger. Isn't yours?