How to handle incomplete stripe connected account onboarding? - stripe-payments

Question

I am after the best practice for handling incomplete stripe connected account onboarding.
When onboarding goes smoothly, everything is simple. But there are fiddly edgecases everywhere, which results in a lot of permutations of values for account requirements
These include
current_deadline
currently_due
disabled_reason
errors
eventually_due
past_due
pending_verification
This creates a lot of complexity.
I need a simple way to:
figure out if the connected user needs to be notified of something (i.e. that they need to give more info), and
what to tell them.
My current strategy is to check if errors is empty, and if not, simply display them along with a link to manage the user's stripe account so they can address the errors.
But I'm worried this strategy will miss things (perhaps minor things that could be addressed before they become errors).
TL;DR I suspect most users will onboard without any problem, but for the few who do have issues, I want to ensure the app notifies them that they need to address them. What is the best way to do this? (using the information in requirements or other info)

Answer 1

When handling identity verification manually using the API, a simple way to check whether your connected user might need to be notified to provide more info is to look at the charges_enabled and payouts_enabled properties on the user's account object. If either of these two properties are false then you might need to reach out to the connected user for more information.
In cases where the connected user's charges and payouts are disabled, you would use the disabled_reason property on the requirements hash to learn the reason why charges and/or payouts are disabled. The possible disabled reasons are all documented here, but I'll list them out nonetheless:
action_required.requested_capabilities You need to request
capabilities for the connected account. For details, see Request and
unrequest capabilities.
requirements.past_due Additional verification
information is required to enable payout or charge capabilities on
this account.
requirements.pending_verification Stripe is currently
verifying information on the connected account.
rejected.fraud Account is rejected due to suspected fraud or illegal activity.
rejected.terms_of_service Account is rejected due to suspected terms
of service violations.
rejected.listed Account is rejected because
it's on a third-party prohibited persons or companies list (such as
financial services provider or government).
rejected.other Account is rejected for another reason.
listed Account might be on a prohibited persons or companies list (Stripe will investigate and either reject or reinstate the account appropriately).
under_review Account is under review by Stripe.
other Account isn't rejected but is disabled for another reason while being reviewed.
Using the disabled_reason, you can assess whether the user needs to be notified with a request for more information (i.e., requirements.past_due), whether they need to be notified for another reason (e.g., rejected.listed), or whether you need to make programmatic changes to the user's Stripe account (e.g., action_required.requested_capabilities).