How to handle incomplete stripe connected account onboarding?

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:

1. figure out if the connected user needs to be notified of something (i.e. that they need to give more info), and
2. 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).