Stripe Embedded Components vs Hosted Onboarding
By Shawn Michael Thomas II, Founder of Simple Easy Transactions · Published ·
Should my platform onboard businesses with Stripe Connect embedded components or Stripe-hosted onboarding? If the business owner should never leave my platform, I use Connect embedded components: my server opens an account session and Stripe's onboarding form appears inside my page. If I want the least to maintain, I send them to Stripe-hosted onboarding with a one-time link. Either way, coming back doesn't mean they finished. I check with Stripe for anything still due before I treat the account as ready.
AT A GLANCE
Embedded components vs Stripe-hosted onboarding.
| Question | Embedded components | Stripe-hosted onboarding |
|---|---|---|
| Where the business fills in details | Inside your platform, in Stripe's component | On a Stripe page, reached through a one-time link |
| What your server creates | An account session for that connected account | An account link with a return address and a refresh address |
| What else it can show | Payments, payouts, balances, notifications and more | Onboarding, and profile updates for some account types |
| Look and feel | Your page's font and background, plus appearance settings | Your name, color and icon from your Connect settings |
| Inside a mobile app's web view | Not supported; use Stripe's iOS, Android or React Native SDK | Not supported; open it in a real browser |
| What proves they're done | The account's requirements, checked with Stripe | The account's requirements, checked with Stripe |
HOW EACH ONE WORKS
How each one works.
Stripe Connect lets a platform sign up other businesses as their own Stripe accounts. Before one of those accounts can take payments, Stripe has to verify the business and its owners. Stripe builds the forms for that; you choose where they appear.
Hosted onboarding is the simpler path. Your server creates an account link, a one-time address that expires within minutes, and sends the business owner there. Stripe asks for what it needs and sends them back to your return address when they finish or choose to save for later. If the link has expired or was already opened, Stripe sends them to your refresh address instead, which should create a fresh link.
Embedded components keep the business on your platform. Your server creates an account session naming the components you want, and your page loads Stripe's Connect library with your publishable key and a function that fetches a fresh session whenever the old one expires. The same setup can later show payments, payouts, balances and notification banners, which is why platforms that want a dashboard usually start here.
Some steps still open a Stripe window on purpose. When Stripe is responsible for collecting a business's information, the owner may have to sign in to Stripe in a pop-up before the form continues. You can't design that away, so plan the page around it.
FIELD NOTES
What I've learned building this.
- This site's onboarding uses the embedded account onboarding component. A business enters its details, signs the Order Form, and then verifies with Stripe without leaving the page.
- I ask Stripe for everything it will eventually need, not just what's due today. It makes for one longer sitting instead of surprise requests later, when an unanswered request could pause payouts.
- When the owner closes the form, I don't take that as finished. My server asks Stripe how many requirements are still open, and the page tells them exactly how many are left.
- Stripe's guide says the refresh function should always create a new session, and mine does: the first session is used once, and every refresh asks my server for a new one.
- If your site uses a content security policy, add Stripe's Connect domains to it. Mine allows connect-js.stripe.com for both scripts and frames, as Stripe's guide lists.
HOW TO CHOOSE
How I'd choose.
- Choose embedded components when business owners should stay on your platform, or when you'll want to show them payments and payouts later.
- Choose hosted onboarding when you want the least to build and maintain, and a short trip to Stripe is fine.
- Either way, treat the return as "they left the form", not "they finished". Check the account's requirements with Stripe.
SOURCES
Where these facts come from.
Sources checked on . Stripe and the app stores change their products and rules, so the linked pages are the final word.