Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Connect and Marketplaces

Onboarding Connected Accounts

Walk through Connect onboarding with account links, the requirements object, verification statuses and the account.updated webhook, and learn to gate payouts on real account state.

Creating an acct_ id takes one API call. Turning it into an account that can legally accept money takes onboarding: the seller proves who they are, supplies a business description and adds a bank account. Rules vary by country and by what the seller does, so Stripe collects exactly what is required for that case, and your integration must not hard-code the list.

The usual approach is to send the seller to a Stripe-hosted form. You never touch passport numbers or bank details, which keeps your own compliance scope small.

The onboarding flow

sequenceDiagram
  participant S as Seller
  participant P as Platform
  participant ST as Stripe
  S->>P: Click "Start selling"
  P->>ST: Create account (acct_)
  P->>ST: Create account link
  ST-->>P: One-time URL
  P-->>S: Redirect to URL
  S->>ST: Fills hosted form
  ST-->>P: Redirect to return_url
  ST-->>P: Webhook account.updated

Always trust the webhook, not the return redirect.

An account link is a short-lived, single-use URL. It has a return_url (where the seller lands when they finish or leave) and a refresh_url (where you send them if the link expired or was used). Landing on return_url does not mean onboarding is complete; the seller may have closed the form early.

JavaScript
// Read-only: needs the "stripe" npm package
const link = await stripe.accountLinks.create({
  account: 'acct_123',
  refresh_url: 'https://example.com/onboarding/refresh',
  return_url: 'https://example.com/onboarding/done',
  type: 'account_onboarding',
});
// redirect the seller to link.url

Reading account state

The Account object tells you how far along the seller is:

  • details_submitted: the seller finished the form.
  • charges_enabled: the account may accept payments.
  • payouts_enabled: Stripe may pay out to their bank.
  • requirements.currently_due: fields needed now to keep or enable capabilities.
  • requirements.eventually_due: fields that will be needed later (for example once volume grows).
  • requirements.past_due: overdue; the account is usually restricted.
  • requirements.disabled_reason: why the account is disabled, if it is.
Node.js Turning requirements into a status

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reacting to account.updated

Stripe sends an account.updated event whenever verification progresses. Use it to update the seller's status in your database and to email them if they need to act. Connect events arrive at a separate Connect endpoint, and each event carries an account field with the acct_ id it belongs to.

Node.js Handling account.updated events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Design tips

  • Do not block the whole product until onboarding is finished. Let sellers list items, and delay publishing or payouts until charges_enabled is true.
  • Show requirements in plain language. Map currently_due keys to friendly messages and offer a fresh account link when action is needed.
  • Never store sensitive identity data yourself unless you chose Custom accounts and understand the obligations.
  • Use test data in test mode. Stripe documents special test values (for example test identity numbers and bank accounts) that trigger verified, pending or failed states. Look them up in the current docs rather than guessing.
  • Handle the deadline. current_deadline in requirements says when missing information leads to restrictions.

Never treat return_url as proof of success. People close tabs, and verification can still be pending after the form is submitted. Gate selling and payouts on charges_enabled and payouts_enabled.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an account link?

    Account links are temporary and single use. Create a fresh one whenever you need to send the seller back.
  2. 2. The seller lands on your return_url. Is onboarding complete?

    The seller may have left early or verification may be pending, so check the real account state.
  3. 3. Which requirements list means the account is already overdue?

    past_due fields are overdue and usually restrict the account.
  4. 4. Why avoid hard-coding the list of onboarding fields?

    Stripe reports what is needed per account, so read requirements instead of assuming a fixed form.

Summary

  • Onboarding uses a Stripe-hosted form reached through an account link.
  • charges_enabled, payouts_enabled and requirements describe the true state.
  • React to account.updated events delivered to your Connect endpoint.
  • Never rely on the return redirect as proof of completion.

Next: Destination Charges and Fees