Then I found stripe. What a treat. Everything was documented and the documentation itself was both readable and didn't go in endless circles like the paypal ones. The error messages were helpful. And every api endpoint had an example, which is hugely helpful: HUGELY! All the other API developers out there can learn from this: you can't underestimate the value of having a working example. Not only that but the testing is much easier in stripe, and there's no need for a bunch of seperate accounts and sandboxes that don't make sense.
Oh and did I mention that the variables describe themselves: the first 3 or 4 letter of an ID says what it is (subscription or etc). Genius! It's little things like this which make Stripe stand out orders of magnitude above the rest of all the APIs in the world.
I hope you guys rule the marketplace for payment processing and wish you all the success you deserve.
Stripe's success in payment processing sends a clear signal to the Paypals and API developers of world: If you're producing an API that sucks, it creates an opportunity for someone else to come eat your lunch. :)