Recently I've been doing some work for neo.org, an NGO and social network based in Switzerland. During the past month I've integrated Twitter (authentication, direct messages, updates) and Paypal (purchasing) into this Ruby-on-Rails-based site, and looking back, I realize that I enjoyed one of these integration projects -- and not the other. Both projects were about the same amount of work, and required me to write similar amounts of code. I've been trying to figure out why working with Paypal was frustrating for me, while working with Twitter was fun.
Was it library/gem support? No, not really. Both twitter and paypal are widely used by rails sites, so it wasn't hard to find decent gems. I used the twitter and activemerchant gems, and both served me well.
Documentation? Yeah, this was a big part of the problem.
With twitter, I did spend some time reading out-of-date blog posts, but once I found that the latest versions of the twitter gem support twitter auth, I realized this gem was going to make my life as easy as I could expect it to be, and decided not to bother with the TwitterAuth gem (though I did find several bloggers recommending it). The sample twitter-app was a big help in understanding exactly how the pieces fit together. This meant that early on, I had a pretty clear idea of exactly what I was going to need to do. Moreover, twitter.com has great documentation. Pleasant to read, well organized, gets to the point.
For the Paypal integration, I quickly found Using Paypal with Rails, which was tremendously helpful. But I also found plenty of contradictory advice, some recommending Spree (a layer on top of ActiveMerchant), and a pretty strong recommendation from Cody Fauser for using PayPal Express, rather than the PayPal Website Payments Standard. After a fair bit of reading, I concluded that Spree is complex, imperfect, and wouldn't make my life any easier. I also concluded that using PayPal Express wasn't worth the extra effort required, given neo.org's simple requirements. But when it came to actually getting the work done, I found it very difficult to find answers to specific questions -- because Paypal's documentation is rather poor. They have a maze of similar products and protocols, and it is painful to get a clear overall picture of what's going on. I finally found this forum article buried away somewhere that clearly explains the various options available for getting back the financial transaction data, and I sorted out for myself why, when the user comes back to your site, the return or finalize action is sometimes called with a GET, and other times with a POST ... but it didn't make me happy. And none of the documentation I read makes the rather obvious point (in hindsight) that your testing has to be done from a publicly accessible server for Paypal's server to be able to POST back to you.
It's also worth noting that testing was more straightforward with Twitter than with Paypal, and the transition from development to production was also easier.
Although Paypal's poor documentation was a key factor in my dissatisfaction, I think the root cause of the problem is simply the complexity of Paypal's offerings. This makes it difficult to have good documentation, and makes it hard for newcomers to get oriented. The tools and backend admin interfaces are initially somewhat overwhelming, and after 3 days of use, not my friend. Somehow my test store got destroyed at one point; I have no idea what I did wrong. And several times I got mysterious errors while using their sandbox website (not errors from my client code, just errors from my manual interactions with the admin interfaces). In the end, everything seems to work fine, but ... I work with Ruby and Rails because they give me pleasure, and the tools are rich enough that it's possible to create things that are beautiful.
Paypal isn't beautiful. Twitter's okay. Fun integration projects bring more beauty into your life.