A good first question to ask about a data model is, "where does the data live?"
In general, we think it's a good idea to make Stripe the "one true source" for as much of your customer and billing data as possible.
Our company went the opposite way, we have our own model and we abstract stripe as a payment option supported. Recently with the same model we were able to add Paypal and other country specific payment methods.
My last company processed >$100MM/yr of tshirts, split between Stripe and PayPal. Stripe was wonderful; PayPal was hell. It required a lot of engineering effort to build and maintain the system, even as simple purchases (no subscriptions). But if you're selling impulse buys online, PayPal is required.
Current company is B2B SaaS, smaller team, and I said "no freaking way" to PayPal. Built the subscription system around Stripe. Lack of PayPal has probably cost a few sales but our pace of development is much faster, and the new features we're able to roll out (like a referral program) move the needle more.
If you go the "straddle multiple billing systems" route, expect to dedicate one fulltime engineer to billing for the life of the project. That may be reasonable for a team of 10, but it's death for a team of 2.
Out of interest, why did you go down the avenue of hacking together your own system to handle subscriptions? Surely you've limited yourself like you've said you have to build out every time you want to attach another payment method like paypal - Is this not more expensive than looking into a Merchant of Record handling these complexities for you?
There must be some sort of miscommunication here. My (SaaS) subscription system is vanilla Stripe without abstraction. My (single-purchase, tshirt) system was an abstraction across Stripe and PayPal.
I can only imagine the elevated pain of abstracting across multiple subscription systems. Ouch.
My bad must have been a miscommunication here. I was about to expand on those key differences between payment gateways vs Merchant of Records. http://bit.ly/2Us1OWM - Could still be an interesting read as it explores those key elements of what you have to juggle.
As a solo developer on a project which needs flexible payment options (also t-shirts) that's why I need to pick a payment solution that supports paypal besides other methods.
Paddle looks like the service I need on the long run:
I have a polymorphic ledger table of Credit, Spend, Payout.
I scan recent invoice history periodically to keep Credits up to date. Payouts are via PayPal masspay. Spends (using credit balance to offset their SaaS bill) are created on the invoice.created webhook, which adds a corresponding negative line item to the invoice.
I considered doing everything in Stripe - you can add pending invoice items instead of credits and payouts, then 'spends' are just the natural processing of bills - but it would have been very difficult to get analytics (eg, total outstanding payout liability).
+1
I recent saw a couple of cases of small companies who chose to depend on Stripe for managing their payment data to save cost on initial development. As a result, their operations staff struggled between Stripe's admin panel and their internal tools even to answer simple user questions.
Eventually, when they decided to streamline their payment and billing operations on their own tools, due to historical data on Stripe servers, they built a custom presentation layer on top of Stripe APIs. They ended up spending pretty much the same time and effort as they would have done by managing the business flows on their own systems and storing all the data on their DBs and using Stripe just for processing payments. Worse yet, they still depend on Stripe for stuff like reporting.
Like most things in engineering, you can move the tradeoffs around to optimize for different use cases.
The "one true source" approach allows you to avoid writing logic to keep data in sync between your customer records and Stripe's systems. It also implicitly pushes you to think about how to store enough data in Stripe that the Stripe dashboards become your interactive way of managing and viewing customers. Those are both big enough wins that I do think it's the right approach to take for lots of folks who are just spinning up charging for a product, and for relatively simple recurring revenue use cases.
If you need to use multiple payment processors, or you need to have a complex view of your customer and lifecycle, then it's not the right approach.
Yea. Customer and billing isn't something good to hand over to another system you don't control. As a payment processor and API though, Stripe is great
Couldn't agree more. Reading over it's tied to Stripe and their implementation, not even any sort of abstracted interfaces. Vendor lock-in isn't a good plan and to your point, make it easier to add another payment system when needed. Good choice
I'll take vendor lockin over being locked into a bunch of homebrew garbage that some former developer managed to sucker the entire company into creating because of "vendor lockin". So many times engineers come up with fears about "vendor lockin" and forget how easy it is to lock the company into an unsupported, half-baked homebuilt product that has nothing to do with the company's core business.
I've seen it with reporting and analytics, I've seen it with frameworks, I've seen it with deployment systems, build systems and configuration management systems. I've seen it with payment systems, crappy half-baked hybrid cloud implementations, database provisioning systems and more. All in the name of "avoid vendor lock-in".
Being locked into your own garbage-tier product that has nothing to do with your business sucks. If stripe kicks the bucket, you won't be the only person in that boat and there will be a path forward. Know what is worse? How about when the only developer who can support your crappy half-baked payment system leaves the company? Which stack overflow article will show how to get out of that mess? Talk about vendor lockin! You locked yourself into your own mess!
Considering how Stripe caused an abrupt vendor disappearance when buying Index, resulting in a tidalwave of broken integrations (as Stripe closed Index with no notice, and stopped responding to clients), I wouldn't trust them to support a platform for any period of time to ensure a smooth transition.
Stripe might leave the servers online in a half broken state for a few weeks, but they will not answer tickets or phone calls about critical issues if they've decided to can a product.
I think it really depends on the situation. Low level functionality (eg payments api) is more generic than high level functionality (billing cycles, dashboards, handling failed payments, etc) and therefore more likely to have a solution which will completely solve your problem.
Question: did you plan the abstraction by looking at multiple providers first then figuring out the abstraction that would work well for all of them or did you just look at Stripe and luckily come up with an abstraction that also worked for other providers?
I'm encouraged by your success of this model. I'm currently struggling with the 'billing system as source of truth' model.
We built the abstraction around the requirements for our business model, although after some iterations it became similar to the model used by Stripe (customers, sources, plans...). We support saved payment options and on them we do recurring billing and one-stop payments.
A user for us can have multiple sources and a source is a saved external card or payment method, in the case of Stripe a source is a combination of the Stripe customer id and Stripe source token.
Most payment gateways support some kind of token that represents a saved card or similar on which you can do a charge.
There is a very nice implementation of this called KillBill: it's a self-hosted invoicing system that can connect to many payment providers like Stripe/Paypal/...
It's really nice to be in control of the invoicing, without having to implement it ourselves, and of course not depend on only one provider. It also has support for taxes with plugins.
Stripe's "getting started" documentation, as well as this article, show us how easy it is to get started with Stripe - if you ignore the existence of taxation.
The article is completely missing any mention of tax, be it sales tax or VAT. This is my biggest complaint of Stripe.
For a lot of us, we live in countries where we simply _have_ to start collecting and remitting tax from the very first customer.
Couldn't agree more, cool to see they indicate that they're working on it but then as I'm sure you're aware of there is so much more needed than just the dealing of tax, how do you deal with the likes of managing your chargebacks? Support? - This post expands on how Paddle helps here: http://bit.ly/2Us1OWM
Makes sense - I guess it's just an unclear emphasis on their offering which essentially is taking that work off your hands. What would you prefer to see?
I've just finished a Stripe integration[0]. Given Stripe's developer first reputation I thought this would an easy job that wouldn't take more than a couple of days. Boy was I wrong! In the end, it took me about 3 weeks.
Small disclaimer here, I was implementing Stripe Billing, not Stripe Payments. The Billing suite is a lot more complicated compared to the Payment suite.
Nonetheless I took me a really long time to figure out all the special cases such as: renewing a card, switching to a different payment method, up/downgrading a plan, multiple currencies, etc.
At some point you'll be almost finished with the integration and only then do you find the need to implement webhooks for certain asynchronous payment methods (especially needed when you are in Europe). Once implemented, webhooks give you endless new workflows to handle, and many race conditions between your frontend and backend. So it constantly feels like one step forward and two steps back.
I don't think it's Stripe's fault though that my implementation took so long. Stripe's documentation is pretty solid. It's just that billing touches just about every part of your stack (frontend, backend, database, testing, tooling, accounting) and it's painful if you find out you have a bug that caused you to over/undercharge a customer. You need to take your time to get it right.
I'm a Stripe fan, so my perspective on this is that Stripe has done an incredible job making "easy things easy," and a pretty good job making "hard things possible."
There are things I'd love to see added to the Stripe Billing APIs (some of which I mentioned in the article), but I have a really healthy respect for the amount of good work that's gone into the design of an API that, as you say, touches just about every part of a potential customer/payments workflow.
Stripe's API has consistent naming, a clean design of the core data objects, consistent data formatting and request patterns, good dashboard tools for seeing what's happened in requests and webhooks, and great documentation. All of which are non-trivial, and basically none of which any of the other "name brand" APIs I've used in the last year or so do. :-)
Yes and no. Some parts of the documentation can be clarified in my opinion.
For example: if you change the default payment method of a Customer, the default payment method of all this customer's Subscriptions is not changed. The documentation is not clear about that.
Also, if you remove a payment method from a customer, the subscriptions seems unaffected. If you're not careful you might still end up charging this customers card when the subscription auto-renews.
I'm still a fan of Stripe though. I have my fair share of experience implementing other PSP's and they were an unbelievable PITA. As far is my experience goes, Stripe is miles ahead of their (european) competitors.
You're right, their documentation is great and the API is nice to work with, but you are forced to do things their way. I was recently working with Billing and ran into a pretty big issue: A customer on a recurring plan upgrades to a more expensive plan. As long as the customer has a valid source on file, the upgrade is processed. Stripe's default is to adjust the payment to be collected and charge it on the next invoice, which comes at the end of the billing period. If you want to charge the difference immediately, you can by manually forcing an invoice. The problem is that the invoice doesn't close for 24 hours and you can't force it to close any faster. If the customer's payment source is declined when the invoice closes, you just gave them 24 hours access to your premium upgrade which you now have to detect and rescind after being alerted via a webhook. There's nothing in the documentation that warns about this or offers a solution, and worse yet, rolling the user back to their previous plan is not an option. For some use cases, it might not be a big deal, but for most businesses that is a nightmare. The easy stuff is indeed easy, but once you start to wander off of The Path, things can get very difficult.
Our experience is that manual invoices are charged right away. I wonder what's different about our setups? The only thing I can think of off the top of my head is webhooks that aren't responding, which would delay the invoice closing. But I think that would make the delay 72 hours, rather than 24.
I misspoke, it's 1 hour, not 24. Can be found here [0].
Regardless, the upgrade happens _before_ the customer is charged, so unless you put a hold on your system and wait for that invoice to close, you're still giving them access before they've paid (Stripe's system will shown them as having the new upgraded plan before the invoice closes). And with the charge re-tries and back-off they use, if your webhooks aren't listening and reacting, you've still opened up your product to a user who hasn't paid for up to days at a time. I would be very interested to know how you got yours to close instantly, if it is doing that.
You're right, it's not synchronous! I looked back at our development notes and it seems like we were seeing about 15 minutes, generally, between creation of the manual invoice and finalization/payment. But that was using our test, not production Stripe API keys, and was a fairly small set of anecdata. I don't have better data because we ended up not rolling out any features that required manual invoice generation.
That defeats the entire purpose of using the Billing product. Best I could come up with is to auth the source for the amount and see if it is accepted, then let it die by not capturing. But then you have customers who complain about being double charged.
Stripe's generally consistent, except for three different ways to enter a name:
name
account_holder_name
first_name + last_name
And four different structures for addresses:
address_line1
address.line1
legal_entity.line1 (a personal address, old as of new version)
legal_entity.personal_address.line1 (personal address when the prior is a business, old as of new version)
It didn't take me nearly as long to implement Stripe Billing (a couple of days) but that's because all they can do is sign up for my one subscription plan, cancel, and update their card.
There are surprising edge cases that crop up. For example, canceling a subscription and then restarting it is actually somewhat painful.
I found Stripe usage quite complicated. It felt like they were handling very complex use cases at the expense of simpler ones (which are probably the majority).
It's one of those things where once you're already "in the know", the simple use cases are in fact simple to implement. But sifting through the massive and complex API set, with outdated and partial documentation/examples all over the internet, it's very difficult to get into. Every single example starts with "this is not production ready..." And the official docs are difficult to piece together into an "E2E best practices" setup.
Not saying there is a better solution, just that as a competent dev with a simple use case, I found Stripe overly complex.
We are currently working on a new version of our Checkout product[0] and would love feedback. We are working on making the simplest drop-in integration to get up and running on Stripe, and we support Stripe Billing! Send me any thoughts you have (matt at stripe).
I’m curious why there is an even number of cents requirement on stripe’s end?
I’m also not a fan of the quantity 1 line item rollup, although I understand the workaround. For the customer receiving the invoice, it makes it harder to breakdown the invoice in an automated way, since the detail info is moved to a text block.
This was a really interesting article, thanks for writing!
At my last startup, we used our DB as the single source of truth. I think using Stripe as the source of truth like you suggest would have alleviated a lot of our issues keeping things in sync.
My biggest pain point though was around managing features on the client side. We had a bunch of different plans from lots of iterating (and customers coming from different sources that had similar but slightly different experiences), so it became hard to decide "should I allow the user to see this feature/do this action?". I haven't yet seen a great way to handle that. The plans literal here looks like a great starting point though!
Yeah, I definitely feel your pain regarding iterating on plans and features.
Stripe explicitly makes it hard to modify most aspects of Stripe-level plans after they are created, which definitely is the right call because user expectations about recurring payments need to remain stable. But that means you have to build your own plan->feature mapping to manage a proliferation of plans, if you do any experimenting with or evolution of your pricing.
Agreed, making the plans hard to modify definitely makes sense, but then I feel like I need another abstraction on top of Stripe. Have you come across any good ways for handling this?
No, haven't seen anything. Everything looks like a hammer, of course, but to me this just feels like a general software engineering thing, if that makes sense -- building an abstraction on top of a library service. Our plan is to evolve the plans literal in our code into this abstraction (it already kind of is). Next step is probably to add something a little like feature flags, but we're still thinking this through.
Yes, subscriptions can be implemented manually. We did that two years ago before Stripe had the full “Billing” API.
One big win you get with Billing, though, is automatic generation of invoices each subscription period. It’s nice not to have to write that code, and the automatic invoices tie in nicely to a few other things Stripe can do better than we can, like automatic retries of payments that fail.
I so wish Stripe would stop ignoring a number of countries and make their billing available there (Poland is an example). I am stuck with Braintree and it is not a happy ride.
And here's your startup idea: Build a complete and configurable front-end to Stripe Billing that does all the hard work behind the scenes and lets existing Stripe users "upgrade" to billing without the implementation pain.
I've researched something like this some months ago and couldn't find anything that had the quality and features we needed. I'm sure lots of companies would pay for a solution like this (my company included).
I had a similar impression when I was implementing Stripe for my business. It seems like there's a lot of boilerplate and heavy-lifting that I would have preferred to just abstract away using some existing service instead of spending the hours on getting it working in a way others probably already have.
Would you be open to sharing your thoughts on how you'd like something like this to work? I might be interested in giving it a shot. My email address is hello@wyatt.engineer
I have something just about ready to launch that tries to do this. My goal is to make creating web apps as simple as blogging is when you use WordPress.
I am putting the finishing polish and fixes on a platform and marketplace using this software, just working on the final integration tests that verify it all works together.
Maybe noob questions, but how to do tests with stripe API? For example, how to write a test for plan upgrade? From what I remember there can be set testing env in stripe but the shortest subscription time was 1 day, so how to use it in automatic tests?
We disable live API interaction w/ stripe in our tests and use hardcoded response values. You can use a library to do this or patch the stripe sdk - depending on the language/framework you are using.
You should never write tests against a live API. Always mock APIs and handle what happens when e.g. they send a 501 response, etc. Stripe has testing libraries in Ruby and other languages which are very easy to use.
I'm eternally amazed at the rate of speed at which any HN comment section derails into off-topic nonsense. What does this have to do with the linked article? Is it possible to do what's described in the article with PayPal?
Simple. Send the customer to PayPal with a subscription request, the amount and customer id. They activate the subscription and pay. Get that id back via IPN after each new subscription. Deliver the service. Done!
How does that match the use case here, with billing per minute? If the user has to confirm each subscription, you can't efficiently create new subscriptions for e.g. each call. You also can't know beforehand how much you'll need to bill. If you're at the end of the month sending a single "here's everything" request, I fail to see how that's different from what's described in the article.
Exactly my point. PayPal also makes it extremely simple for fixed amount monthly subscriptions - which is my use case. I do use Stripe, but not for subscriptions. This is the reason why.
