Stripe Connect: handle account.updated and verification requirements

TL;DR

The signal is the account.updated webhook and the requirements hash on the Account object. Not blocking today, but it becomes blocking. - requirements.disabled\reason: why the account is disabled, when it is. - capabilities: each capability (for example card\payments, transfers) has a status of active, pending, or inactive. Listen for account.updated.

When to use

You are seeing this: A connected account that cannot accept payouts is a silent failure until someone complains. Use this skill when you run into "Stripe Connect: handle account.updated and verification requirements".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe Connect: watch account.updated or accounts go dark

A connected account that cannot accept payouts is a silent failure until someone complains. The signal is the account.updated webhook and the requirements hash on the Account object. Build the watcher before you need it.

The fields that matter

• requirements.currently_due: information needed right now. If non-empty, the account is restricted.
• requirements.eventually_due: information that will be needed later. Not blocking today, but it becomes blocking.
• requirements.disabled_reason: why the account is disabled, when it is.
• capabilities: each capability (for example card_payments, transfers) has a status of active, pending, or inactive. Request the capabilities the account needs at creation; do not assume defaults.

The loop

1. At onboarding, request the capabilities the account will actually use.
2. Listen for account.updated. On every event, read requirements.currently_due.
3. If currently_due is non-empty, route the account holder back through onboarding (account link or embedded component) to supply the missing information.
4. Treat eventually_due as a to-do list with a deadline, not background noise. As of the Dahlia API version, Stripe surfaces errors for eventually-due requirements, so code that ignored them will now fail loudly.

Agent-specific notes

• Never hardcode a "requirements are fine" assumption after onboarding completes. Requirements change as regulations change and as the account's volume grows.
• In test mode, you can simulate requirement states, but the shape of the requirements hash is what your code must handle, not specific test values.
• Log every account.updated with the account ID and the due lists. When an operator asks "why can't this seller get paid," that log is the answer.

Stripe's Connect docs describe requirements.currentlydue and eventuallydue on the Account object and the account.updated event as the change signal. The Dahlia changelog lists 'Shows errors for eventually due requirements' as a breaking Connect change. Verified against live docs 2026-09-26.