#james_best-practices
queen jackalBOT
👋 Welcome to your new thread!
⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.
⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.
🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1379091066887737419
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
plucky grail
Hi, we document it here: https://docs.stripe.com/api/payment_intents/object?api-version=2025-05-28.basil#payment_intent_object-setup_future_usage
This parameter indicates that you intend to make future payments with this PaymentIntent’s payment method. Can you share more on why you would want to finalize on the server-side even if the customer will be on session at each payment?
high fern
Simplicity of the integration is the biggest reason. Why introduce asynchronous polling and failure handling when we can immediately know if the payment succeeded or not?
For context, we're a very small team, with a comparatively large userbase. It's a two-sided marketplace where sellers are offering a time-sensitive service and need to know quickly if the payment succeeded or not. Our current source-based integration is synchronous, so a change to an async architecture is a big shift
plucky grail
That makes sense. As it's documented, if you do not intend to save the payment method, you'd use:
'should_save_payment_method - This flag controls whether or not the customer requested to save their payment method with you in the PaymentSheet UI. If true, set setup_future_usage to “off_session”.'
high fern
That's the part that confused me... why off_session and not on_session?
Is the implication that if it's on our backend, it's ALWAYS considered off_session, even if it's happening contemporaneously with the checkout on the front end?
plucky grail
If you use the payment method later, when you confirm the payment on the server side - it's possible that the issuing bank asks for additional authentication for instance. This flag let's us communicate to the issuing bank that the customer is not on session and have consented for us to use the payment method later off_session. It is still possible that the issuing bank asks for 3DS regardless
high fern
Ah I see. So if they have a saved payment method with 3D secure, that extra validation is handled by stripe (client side) and cannot be separated from the actual call the finalize the payment?
plucky grail
I'm unsure what 'cannot be separated from the actual call the finalize the payment' means but we let the issuing banks know that teh customer is not on session. If the issuing banks asks for 3DS anyways, you will need to handle that to handle next action
queen jackalBOT
high fern
Maybe this example will help illustrate:
User adds a 3DS payment method
Some time later
Client: User is in checkout flow
Client: User selects their 3DS method
Server: Create a PaymentIntent
Client: Perform 3DS authorization
Server: Finalize the payment (on_session or off_session)?
undone hemlock
Hi there 👋 if your client is online in your app, they're on-session.
Off-session payments are payments you make when your customer is not actively on any of your surfaces (site, app, etc). This is more common for Subscription flows/recurring payments. For instance, a gym membership can be charged automatically each month, I don't have to log into a portal and explicitly pay the fee, so that payment the gym makes automatically is an off-session payment since I'm not on their site/app to make it.
high fern
Ok, thanks for confirming Toby. My confusion stemmed from this bit of doc:
should_save_payment_method - This flag controls whether or not the customer requested to save their payment method with you in the PaymentSheet UI. If true, set setup_future_usage to “off_session”.
Which implies that server-side payments are always off-session
undone hemlock
I can see how that could be confusing, but I think we may have just assumed that when saving a payment method, that you're saving it with the intention of processing off-session payments in the future, rather than on-session ones.
high fern
Sometimes I'm a bit too literal 😅
So just to circle back and summarize:
- Customers request a service with a seller in the app
- Payment is either immediately captured (if the seller has auto-confirm enabled) or authorized in full, then captured when the seller confirms manually
- In either case we immediately let the customer know if their payment was successful
- Customers can save their payment methods and re-use them, but they are always in-app when they initiate the payment
This seems like a reasonable use case to finalize payments server-side? And if the payment is authorized while the customer is in-app, but captured later, is that still considered on-session?
undone hemlock
Payment is either immediately captured (if the seller has auto-confirm enabled) or authorized in full, then captured when the seller confirms manually
Minor correction of verbiage here, it would be "when the seller captures manually". Confirming a payment is when you request the transaction be authorized, capturing the payment happens after that and is when the funds are actually moved.
There's nothing in that flow that is standing out to me as requiring the use of a flow where you finalize payments on your server, rather than confirming payments client-side, but there may be context/business requirements on your side that justify that which I'm not aware of.
high fern
I suppose I am thinking of it more from the inverse position, what is the justification for a client-side payments flow that introduces asynchronous failure and significant complexity? Aside the from the general advantages of asynchronous architecture. which may very well be the only justification needed
undone hemlock
Client-side doesn't introduce async flows. You still know immediately if the payment succeeded if you're only accepting instant-notification payment methods.
high fern
The order fulfillment becomes necessarily async, though
undone hemlock
Oh, you're trying to avoid the need to use webhook endpoints for order fulfillment?
high fern
Correct. It would be a big paradigm shift for us
undone hemlock
Gotcha. Yeah, you can trade off adding some processing time in your checkout flow (since you'll need to make extra API calls to your backend), in exchange for having context on your server already for kicking off downstream flows.
high fern
Okay, thanks for the insights both 🙂 I will weigh both approaches