Hrm, I've seen most who migrate spend a similiar time to your estimate. I know you've already migrated, but I'm really sorry it took that long, and I'd really like to hear where we can improve the docs. Would you mind emailing dev-feedback@stripe.com (and feel free to CC edwin@stripe.com).
[Not the GP, but 100% in agreement with them, except that we abandoned updating our integration.]
I'd really like to hear where we can improve the docs.
IMHO, the fundamental problem is that as the data model and API have become more complicated, the explanatory documentation has become less coherent. It feels like jumping around a Wiki now.
More specifically, we couldn’t find anything to show us the big picture of how SCA actually works with Stripe’s system. We also couldn’t find useful end-to-end walkthroughs with code samples to learn by example, hence my suggestion in the other comment you replied to. Lacking a frame of reference from one source or the other, all the detailed documentation about Stripe.js and APIs doesn’t help very much, because you don’t know what you need to look up in the first place or how anything fits together.
This was compounded in our case because after spending considerable time swapping messages with Stripe support, in which we did explain that we’d read all of your documentation and we did also describe our (very simple) existing subscription set-up process in terms of specific Stripe.js and API calls, the responses were just boilerplate references to documentation pages we’d already read. Of at least five different people from Stripe who replied to me over more than two weeks, not a single message mentioned any specific function in Stripe.js or the API or any specific webhook, despite several explicit requests and sending specific details on that level from our side at Stripe’s request.
To put this in perspective, please consider that when we first integrated with Stripe, it took one Stripe.js call, usually one API call and one webhook to tokenize card details, set up a Customer and Subscription with that card, and then act on each successful payment. I wrote that code myself in less than an hour, and I think it was described start-to-finish on no more than two or three pages on Stripe’s documentation site.
At the risk of making this comment antisocially long, but with the suspicion that we have not been the only ones following this path, I’ll describe what happened this time instead. The first of several links I was sent by Stripe support in one of those emails went to a page about saving card details for later (https://stripe.com/docs/payments/cards/saving-cards-after-pa...). Within just the first step of that page, there are at least six different concepts we hadn’t previously used in our integration that were mentioned, most of them without any sort of introduction, definition or link. Some of these are clearly very important concepts in SCA world, like a new PaymentIntents API and distinguishing on-session from off-session payments. OK, so we need to learn about those. Off we go to the API documentation, where we do find PaymentIntents, which in turn refers us immediately to the PaymentIntents API explanatory page (https://stripe.com/docs/payments/payment-intents/creating-pa...). This gives us a general idea of what PaymentIntents do (remember, when we integrated before, you didn’t even have concepts like Invoices in your API) but then starts talking about manual and automatic confirmation. So before we’ve finished reading the introduction on that page, we already have two more new concepts, and there’s a third link to a comparison between them, but that refers to one-time payments and we’re trying to set up a subscription, so now we’re jumping context and don’t know whether what we’re reading is actually relevant to our use case or not.
That last paragraph could continue for literally several more days of finding our way around, often going in circles. We’ll later be confused by the difference between PaymentIntents and SetupIntents, several similarly named but apparently quite distinct functions in Stripe.js v3 that might replace the old call to create a token, the difference between a source and a payment method, which actions happen synchronously and which are or might become asynchronous in the new world of PaymentIntents and SCA, and many other such questions. We’ll also wonder how any of this fits in with things like Dunning, which was the other big improvement we had hoped to make back when we first started reading about the latest APIs and contacted Stripe support for advice. One important thing you’d notice by the end of the story is that at no point did we ever discover what triggers step one on that very first documentation page to start with — is it a replacement for the old tokenization using Stripe.js, a replacement for the old Customer.create API call, something we have to do in addition to those things at some point?
This comment is already far longer than I had intended, but I hope that gives you some idea of how the current documentation and support systems are not working as well as they used to, from the perspective of a long-time Stripe merchant just trying to update their integration to the new APIs to maintain the equivalent of functionality we already had.
If I were tasked with improving the docs then I would start with an exercise to identify all of the explanatory pages for the new PaymentIntents API, SCA migrations, Dunning, and anything else related. Then I’d get someone, preferably someone who doesn’t already intimately understand how SCA works and Stripe’s API, to go through and highlight every concept or technical term that hasn’t yet been explained before it’s used. I suspect that would identify many points of potential confusion, but with several recurring themes. Next, I’d take a step back, look at how SCA works, look at how the Stripe data model and new APIs work, determine which are the foundational concepts that keep coming up but haven’t been explained first at the moment, and then write a one-page introduction to the big picture and how these concepts fit together. That is the key page that is completely missing at the moment. And then ideally, I’d go from there straight to the kind of walkthrough mentioned elsewhere, showing how to set up a subscription or a one-off charge using the new Stripe.js, APIs and webhooks with reference to the main concepts from that overview page. From that starting point, there is a frame of reference, and the more detailed explanatory pages and full API specs might make more sense to someone starting an integration essentially from scratch with little prior knowledge.
I'm glad I wasn't the only one who had issues with the "support circle".
Usually Stripe is on the ball but I dunno, I had a very non-productive back and forth with them. Non-productive in the sense that it took a long time to get anything that was in response to my initial email and that in the end I didn't learn anything I didn't know before I sent the first email.
Their first couple of replies just tried to get me to use their hosted checkout even though I mentioned needing coupon codes early on which is not supported by that. I also included a super detailed explanation of my workflow (bullet points, using headers, in depth break down of everything) and it was clear their hosted checkout was no way possible to use -- not even the automatic payment intents was viable due to the lack of validation I had to do server side when using automatic PI. Manual PI with a million hoops to jump through or forfeiting sales with Charges was the only option.
It really felt like the support person didn't read the request. It felt like they skimmed it for 5 seconds for keywords (or maybe this was algorithmic) and then made a copy / paste suggestion from a script just to make sure they hit a daily quota of "emails answered". It took a number of these until I started to get responses back from someone who sounded like they read the initial email.
I'm thankful Stripe exists but the worst possible thing you can ever do in support besides ignoring a customer is having the customer spend 45 minutes writing the most detailed request for help possible and then getting a canned response that was already deemed not able to be used in the original email that was sent. It's just in your face proof that support didn't even read it. Then you have to spend 5 back and forth emails over a week just repeating what you wrote in the first email.
I wish multi-billion dollar companies hired support people who cared as much about the company as the CEO. I guess this is why solo devs and smaller teams tend to offer the best support -- simply because the person answering emails is the person running the business or is massively invested in it.
If it’s of interest, our recent experience and the impression it created were very similar. We also somehow seemed to wind up with two or possibly three concurrent discussions going on, possibly because my initial contact went unanswered so I wound up chasing. We still use my business email address as our point of contact with Stripe, so if you look for chris.newton in your tracker, you should find all of the relevant discussions.
I just want to follow up with after emailing edwin, I was put in contact with someone who is on a different level than the support team I've talked with originally.
We got in touch late Friday so a resolution wasn't made (not enough time), but it's clear he spent more than 1 minute skimming the support message and it felt like he really put in serious effort to help me in my specific situation. I think everything will be crystal clear in the end after a couple of emails (and these aren't just repeating emails, it's to deal with moving forward with new info after implementation).
I wish this type of support was the default. It never would have happened without this post on HN happening. There's a lot of value in having in depth emails about specific problems because it leads to documentation improvements that benefit everyone (plus it makes your paying customers happy on the spot because they got help using your product).
I wonder whether that might also be what the last person from Stripe support meant when they mentioned sending us to some sort of specialist. Unfortunately by that point we’d already spent more than two weeks going back and forth with numerous people replying but no actionable advice, so we declined and made other arrangements. However, I did also send them some notes similar to my comments here, so perhaps the negative experience in our case could at least be helpful for improving their documentation for others in the future.
I had this exact experience recently too! Stripe was so easy at first so my estimate to upgrade was only a day, but the number of concepts and the muddled way they’re introduced meant day after day I was still working out if I really needed a payment intent, what would getting charge authority look like, do I even need any of this since I’m not doing business in Europe (in the end no, I migrated to the ‘old’ charges api, which the token api used to be). It ended up taking 5 days and causing quite a bit of angst with my cofounder due to a customer deadline
Combined with Stripe not refunding merchant fees, which was what triggered me to rewrite the payment process to delay processing until the last possible moment and making our own customer facing process more complicated, my most recent experience was less magical (like it was the first time) and more like dealing with a giant bank
I really like products like connect, and the original front end SDK (elements feels like overreach), but if someone hungrier came along they’d definitely get a look in
