I lead the development of edX’s E-Commerce platform (Otto), and one of my biggest frustrations is integrating with payment processors. We currently use CyberSource and PayPal, and both have been painful to integrate.
In both instances the pain comes from poor communication. My team spent about a week writing the CyberSource Secure Acceptance Web/Mobile integration primarily due to poor documentation regarding the payment lifecycle. I had to hack in support for refunds by integrating their SOAP API! You read that correctly: in 2015 I wrote a SOAP client in Python.
PayPal’s REST API is much better-documented. I was grinning for much of the comparatively short two days it took to integrate it. My excitement was somewhat muted when I discovered there is no way to test payment failures. I even called and spoke with their support team who assured me that the HTTP status codes will adequately communicate failures.
Wrong! Fast forward to production, and we continue to see random errors that seem to only be documented at StackOverflow. I’ve also received emails from PayPal stating that a previously approved payment has been rejected, and we should hold off on shipping an order. Did I mention that we only sell digital good (for now) that are immediately fulfilled?
I was resigned to accept these issues as “normal”. We had plans to retry PayPal requests when the sporadic errors occurred. We had plans to work on a highly available message queue that sits in front of our CyberSource endpoint to ensure we received payment notifications (to complete an order) in the event Otto was inaccessible.
Now I have plans to move to Stripe and/or Braintree!
We just finished an internal hackathon and, in less than two days, I integrated both Braintree and Stripe! I haven’t magically become a payments expert in the last two months. Both companies have simply created some of the best documentation I have ever seen:
The documentation is simple and easy to navigate. It has clear, concise, examples for the most popular languages. Those examples read as if they were written by developers who actually used the software, not thrown together as an afterthought. I have never been so excited about documentation! I’m so excited that I am blogging…about documentation.
Until yesterday I had not realized the true power of good documentation (for a good product, of course). It is simple: I’m recommending that our company (and our open source users) use Stripe and/or Braintree.
I like Braintree because it was recommended by a friend, and they have PayPal integration. However, since we already have a (mostly working) PayPal integration and want to eventually accept Alipay payments, Stripe edges out Braintree. If anyone from Braintree is reading this, if you can get Alipay integration you win the bags of money.
I’m starting to rant and show my payments geekery. I’ll close by simply stating that if you produce software intended for use by other developers, produce equally good, if not better, documentation as well. You might just win over a few developers.
NB: Yes, we will be updating Otto’s documentation before it is officially open-sourced and supported later this year.