1. Separate navigation from account readiness
Stripe sends a connected account to return_url when the holder finishes the flow or selects Save for later. This does not mean all information has been collected or that the account has no outstanding requirements.[2] Treat the redirect as a navigation event: the user has returned to your application, but the server still needs to establish what happened.
Recommended product behavior is to show a checking state, retrieve the account associated with the signed-in user and then show the next action. Do not display an approval badge merely because the browser reached a particular path. This distinction matters when someone completes only part of the form, closes the browser or returns after requirements have changed.
2. Issue the link inside an authenticated session
The documented Account Link is temporary and single-use because it grants access to the account holder’s personal information. Stripe instructs platforms to authenticate the account holder before redirecting and not to email, text or otherwise send the link outside the platform application.[2] A support email should direct a user back to your own authenticated onboarding entry, not contain a stored Account Link.
At link creation, use the connected account ID, refresh_url and return_url. The collection_options.fields choice distinguishes currently_due for incremental collection from eventually_due for up-front collection.[2] Record the intended collection choice on the server so the recovery route can recreate the same flow. Keep the temporary URL out of routine support transcripts as an implementation precaution.
3. Make refresh generate a new link
Stripe uses refresh_url when a link expires, has already been visited or is otherwise invalid. The documentation specifically notes that messaging clients may visit links for previews, consuming them before the intended user arrives.[2] A link that fails immediately is therefore not, by itself, evidence of a rejected business or failed identity check.
The refresh route should call your server to create a new Account Link with the same parameters, then redirect to the new URL.[2] As an operational safeguard, resolve the connected account through the authenticated session rather than trusting a freely editable account identifier. If creation fails, show a recoverable error and preserve the ability to retry; do not loop indefinitely between the expired URL and your return page.
4. Inspect requirements after the return
The return URL passes no state. Stripe says to retrieve the account and inspect its requirements hash, or listen for account.updated and cache the account state in your application. If onboarding is incomplete, provide a way to continue later.[2] A plain request to your return route is not a signed statement of verification status.
Use a clear internal distinction between flow exited, outstanding information requested and the account’s actual operational status. Requirements vary with country, business type and requested capabilities, and can change over time.[2] A no-action message based on an earlier snapshot should not prevent a later account update from creating a new task. Keep this guide scoped to onboarding information; separate capability and payout checks belong in your account-readiness policy.
5. Choose the right continuation flow
An account_onboarding link can collect outstanding requirements for a new account or an existing account with new requirements. An account_update link has different restrictions: Stripe only allows it where the platform is responsible for requirement collection, and not for accounts with access to a Stripe-hosted Dashboard.[2] Do not replace every broken onboarding link with an account_update link as a generic repair.
The hosted flow is supported in web browsers, not embedded web views within mobile or desktop apps. Live-mode refresh and return URLs must use HTTPS, although HTTP can be used in a testing environment.[2] Before launch, inspect the actual deployment configuration; success on a local HTTP callback does not prove the live callback is acceptable.
6. Test exits, expiry and recovery separately
Recommended test cases are a complete flow, Save for later, an already-visited link, an expired link, an unauthenticated refresh request and a failed link-creation request. In each case, record the account ID, route taken, latest requirements snapshot and next action shown. These are a test plan, not measurements from a live Connect account.
The acceptance criterion is not simply that all paths reach a success screen. A stale link should lead to a newly generated link for the correct authenticated account; an unfinished flow should lead to a continuation prompt; and a completed flow should still be evaluated against current account data. Stripe’s account.updated event provides notifications when requirements and account information change.[2] Reconcile those updates with the state your user sees, without storing identity documents in ordinary application logs.
Sources and dates
Official Stripe documentation in English. No publication or update date is stated; retrieved and checked on 2026-09-21. The retrieval date is not a source publication date. This is editorial research, not a PayIn feature claim, account eligibility check, or legal advice.
- [2] Stripe-hosted onboarding · Checked 2026-09-21; source date not stated.