Write logic for payments/account-setup to send state to its child components

[joshsmith]

Problem

EDIT

This is being broken into tasks and is just being used for reference right now.

We need to be able to send state to child components in the payments/account-setup component in order to determine whether we should be displaying the forms or instead some success components if the data was valid and we're done with that step.

This is probably the most complex here and the logic here still needs to be figured out.

We'll want to add some tasks like:

• create success component for bank-account
• create success component for identity

etc.

[begedin]

I've been trying to destructure this as well as I could and got some ideas on how to deal with it.

Here's my proposal on how to do it:

Implementation

• We split up the payments route into

  • payments.index - auto-redirected to from payments
  • payments.contact-info
  • payments.funds-recipient
  • payments.upload-document
  • payments.bank-account

• payments.index loads the stripeConnectAccount in model(). In afterModel(), it takes the stripe-connect-account model and uses some way to figure out the proper current subroute and redirects to it. This "some-way" can be a service, a dedicated object, or even just a virtual field rendered by the API view.

Figuring out the state

This can be done by a service/dedicated object on the client side, or it can be done on the API side and rendered by a view. I'm leaning slightly towards API myself.

The function that computes the state returns some sort of string indicating the current state. It's not yet clear to me how much we want to skip for now, so I'm not sure what the list of possible state is. However, the overall list of major states would be

• contact.required - Really means the account has not been created yet, so if the API is what renders the property, then this is not a state, and just means the passed in stripeConnectAccount model is null, assuming we're skipping email verification for now. Once we add email verification, we can handle the logic on that specific subroute, but as far as I can tell, this is not really tied to stripe itself. Do we need to handle email verification? In any case, we can later add in contact.pending to show that while the email has been provided, it has not been verified yet.
• recipient.required - contact info is OK, we need funds recipient information. If stripe differentiates between "information provided but not verified" and just "information provided" here, then we might need recipient.pending as well.
• document.required - funds recipient information was provided but a document is needed for further verification. As with emails, we can add document.pending if a document was provided, but it's still processing.
• bank_account.required - recipient information was fully verified, we need bank account information. Might need bank_account.pending here as well. Depending on how we want to handle it in the future, external_account.required might make more sense.

Based on the state, payments.index redirects to one of the other routes.

Each subroute, in afterModel() can check one more time if the current state is ok and redirect to payments.index if the state is not valid for the route (in case the user hits the route directly).

Advantages

This behaviour allows us to centralize the state management and greatly simplify the individual templates.

Templates are simpler

payments.contact-info would look like:

{{! called contact info right now}}
{{payments/contact-info-form onContactInfoSubmitted=(action 'createStripeAccount')}}
{{! just the square thingy that looks like a closed accordion, not interactive}}
{{payments/next-step stepName='Funds recipient'}}
{{payments/next-step stepName='Bank account'}}

The contact-info form looks like:

{{input type="email" value=email}}
<button {{action onContactInfoSubmitted email}}>Create Stripe Account</button>

payments.funds-recipient looks like:

{{! a box with the checked status, displaying the email, not interactive}}
{{payments/contact-info-done email=stripeAccount.email}}
{{! the funds recipient form, still the most complex part in the process, but less so}}
{{
  payments/funds-recipient-form 
  onFundsRecipientSubmitted=(action 'updateStripeAccount' stripeConnectAccount)
}}
{{payments/next-step stepName='Bank account'}}

payments.upload-document looks like:

{{! a box with the checked status, displaying the email, not interactive}}
{{payments/contact-info-done email=stripeAccount.email}}
{{! the document upload form, still the most complex part in the process, but less so}}
{{
  payments/document-upload-form
  onUploadSubmitted=(action 'uploadDocument' stripeConnectAccount)
}}
{{payments/next-step stepName='Bank account'}}

payments.bank-account looks like:

{{! a box with the checked status, displaying the email, not interactive}}
{{payments/contact-info-done email=stripeAccount.email}}
{{! 
  a component indicating the funds recipient is fully verified. 
  depending on what it looks like, we could reuse the same one for all steps,
  but I'm not sure. Non-interactive.
}}
{{payments/funds-recipient-done}}
{{
  payments/bank-account-form
  onBankAccountSubmitted=(action 'updateStripeAccount stripeConnectAccount')
}}

We can paralelize

If we split up the interface in the way described above, we can define the following tasks:

• Create/finalize the contact-info-form component.

  • Has an email field.
  • Has a submit action which sends the email out
  • Looks like the provided design (can be a separate task)

• Create/finalize the payments.contact-info route

  • Renders the provided template.
  • createStripeAccount action takes email as parameter and creates a stripe account. Redirects to payments.index

• Create/finalize the funds-recipient-form component

  • Has a radio button that toggles between one set of input fields and the other
  • Has a common set of input fields
  • Submit action figures out state of input fields, collects properties and sends them out
  • Match the provided design (can be separate issue).

• Create/finalize the payments.funds-recipient route

  • Renders provided template
  • updateStripeAccount action takes stripeConnectAccount model and a hash as parameters, then updates model and redirects to payments.index

• Create/finalize the document-upload-form component

  • Renders a fire upload input
  • Submit action sends upload properties outward. Depending on the library we use, this might not be possible. We may have to upload from component directly, in which case, it sends out response at the end of the action.
  • Matches provided design (can be separate issue)

• Create/finalize the payments.document-upload route.

  • render the document upload component
  • onUploadSubmitted action takes stripeConnectAccount model and upload properties. It uploads to stripe directly. When done, it receives back a file upload id, uses that and connect account model to create a new file upload record. Redirects to payments.index when done.

• Create/finalize the bank-account-form component

  • Renders account fields
  • Submit action collects account properties and sends outwards
  • Match the provided design(can be separate issue)

• Create/finalize the payments.bank-account route

  • Renders provided template
  • updateStripeAccount action takes stripeConnectAccountmodel and hash containing bank account info. Updates model with the info.

• OPTIONAL: Implement account-status service/object - Receives a stripeConnectAccount object (or null) and returns a value indicating the status, based on values of various properties. There is potential to put this API side completely. The API view can figure out a simplified status, which would reduce the amount of properties the client needs to be aware of. In that case, we don't really need a service/object. Instead, payments.index can just check the value of a single field on the stripeConnectAccount model. Instead, we need an API issue.

• OPTIONAL (API): ** Add virtual field to stripe account which returns the inferred account verification status. One of - contact-info-needed, funds-recipient-needed, document-upload-needed, etc.

• Integrate payments.index redirecting with other routes.

  • Use afterModel hook with service (or field on stripeAccountModel) to figure out and redirect to proper routes.
  • Use afterModel hooks of other routes to redirect to payments.index if the user should not be able to access that route.

[begedin]

More info on figuring out status:

• organization.stripeConnectAccount is null - status is at the contact.required state. Need to provide an email and create the account.
• account.verification.fields_needed array is not empty
  • only contains external_account - means recipient info was provided and verified. we need bank_account info. state is bank_account.required
  • only contains one of legal_entity.verification.document or legal_entity.additional_owners.[0,1,2,3].verification.document - a document upload is needed to finalize identity verification
  • contains other strings, but none of the strings from the two sets above - means we need to provide funding recipient information
  • contains other strings, including any of the strings from the two sets above - should not be happening. our funding recipient form should require all fields other than documents or external accounts. otherwise, we need to get to a point of handling account information at a field level, which, while implementable, is way more complex than is necessary.

[begedin]

Handling a "verification pending" state

After each step, the legal entity can be in the pending status. This is indicated by the account.legal_entity.verification.status having a value of "pending". Note that this is account.legal_entity.verification, not account.verification.

I think the simplest way to approach this is for the payments.index to either not redirect, or redirect to payments.pending. Either case, the route that ends up being rendered should show something like "Your most recently provided information is being verified by Stripe. This can take a while.", with a button that reloads the route.

[begedin]

Simplifying the API

Our StripeConnectAccountController.update can match against the parameters and call a proper StripeService.StripeConnectAccountService method (update_funds_recipient, attach_document, or update_bank_account), or the StripeConnectAccountService.update function can do that and call the proper private method.

[joshsmith]

@begedin correct me if I'm wrong, but it looks like you can get many of the same benefits of the simplifications/logic you proposed without necessarily redirecting to subroutes, and instead having a component that's the manager for these components have subcomponents that are passed their specific state and their required data from the parent. Do you have anything against that approach?

I understand some of the reasoning here is based on wanting to parallelize and parcel work out to contributors, but don't think we lose that with the alternative.

Think the all-on-one-page approach is the better UX, personally.

[joshsmith]

This is especially true when you consider that states can change even when an individual/legal entity is already taking payments. It might be confusing to jump back to some step rather than seeing it as things on a page that are okay or not okay.

[joshsmith]

I'm also leaning towards the API having a read-only view that computes the high-level state of what's needed, or even having it as attributes on StripeConnectAccount itself.

The idea here would be that you would have key/value pairs like:

• contact_status: "required" | "verifying" | "verified"
• recipient: "pending_requirement" | "required" | "verifying" | "verified"
  • verification_document: "pending_requirement" | "required" | "verifying" | "verified" | "errored"
  • personal_id_number: "pending_requirement" | "required" | "verifying" | "verified" | "errored"
• bank_account: "pending_requirement" | | "required" | "verifying" | "verified"

In every case here:

• "pending_requirement" means not yet needed - can be used to render or not render a given state, e.g. top-level objects like the "recipient information" or "bank account" should be rendered when "pending_requirement", but "verification_document" should not be. Could use a better word for this status.
• "required" means we need this now
• "verifying" means that Stripe is currently processing and verifying the information
• "verified" means the information is verified and we should show a success state with the proper information on top-level components; lower-level components like verification_document will not show anything because that's the top-level responsibility
• "errored" means the information is still required, but needs resubmitted with a generic error

[begedin]

If we go with a manager component approach, then the structure would be rewritten as:

Single route, template renders the manager component. Something like

{{!payments.hbs}}

{{!this is a computed, one "global" pending state for when a part of the information was submitted}}
{{#if verificationPending
  {{payments/account-verification-form  
    account=project.organization.stripeConnectAccount
    onContactInfoSubmitted=(action 'contactInfoSubmtited')
    onRecipientSubmitted=(action 'recipientSubmitted')
    onDocumentSubmitted=(action 'documentSubmitted')
  onBankAccountSubmitted=(action 'bankAccountSubmitted')}}
{{else}}
  {{payments/verification-pending}}
{{/if}}

{{!payments/account-verification-form.hbs}}

{{!can't really have `contact.required` status, since we create an account when providing the email}}
{{#if (eq account null)}} 
  {{payments/contact-status-form onSubmit=onContactInfoSubmitted}}
{{/if}}
{{#if (eq account.verificationStatus 'recipient.required')}}
  {{payments/contact-info-done email=account.email}}
  {{payments/funding-recipient-form onSubmit=onRecipientInfoSubmitted}}
{{/if}}
{{#if (eq account.verificationStatus 'document.required')}}
  {{payments/contact-info-done email=account.email}}
  {{payments/document-upload-form onSubmit=onDocumentSubmitted}}
{{/if}}
{{#if (eq account.verificationStatus 'bank_account.required')}}
  {{payments/contact-info-done email=account.email}}
  {{payments/funds-recipient-done}}
  {{payments/bank-account-form onSubmit=onBankAccountSubmitted}}
{{/if}}

There are other approaches to, especially with the verification status, but this is the quickest and "as MVP" as I can think of. I have nothing against this approach, but splitting it into routes does make the whole integration a bit more "collaboratable".

Additionally, this approach moves the testing of which UI is rendered away from an acceptance tests into component integration tests, which is an advantage at run time (faster tests), but slightly disadvantageous during implementation (acceptance would have allowed us to just use mirage, integration will likely require a bit more mocking. I'm splitting hairs here, though. It should not make much difference either way.

Just keep in mind, we cannot have a contact_status.x state. The contact we provide is the email, and we provide it in the create payload.

The sets of issues for individual subcomponents that I have defined above are the same. The sets of issues for individual routes go away and there's one big issue for the single payments route, in which all actions need to be implemented.

The basic approach is

• subcomponents render proper forms, send out required properties on submit.
• manager component decided which subcomponent to render, passed actions to the outside and also attaches the account parameter to them (where applicable).
• Route renders manager component and handles the actions by creating/updating the project.organization.stripeConnectAccount

[joshsmith]

• contact_status
  • required - show the form field for entering your information
  • verifiying - we're verifying your email; refresh or edit your information
  • verified - your email has been verified
• recipient_status
  • pending_requirement - show just "Funds recipient" box with no other information, no fields, nothing; only the title
  • required - show the form fields
    • individual - show the personal information fields
    • legal_entity - show the personal and legal entity fields (with legal entity fields shown first)
  • verifying - we're verifying your information now
  • requires_verification_document - reference verification_document below
  • requires_personal_id_number - reference personal_id_number below
  • errored - show the fields with any relevant errors as to what's missing; can come from the fields_needed hash and used to match to those fields
  • verified - show the verified name of the individual, last 4 of the SSN, and the legal entity name if there is one
• verification_document_status - inside the "Funds recipient box", we'll show:
  • pending_requirement - nothing
  • required - we need you to upload a scan of your ID (form + submit)
  • verifying - we're verifying your id scan
  • verified - nothing, parent responsible now
• personal_id_number_status - inside the "Funds recipient box", we'll show:
  • pending_requirement - nothing
  • required - we need your full personal ID number (form + submit)
  • verifying - we're verifying your id number
  • verified - nothing, parent responsible now
• bank_account_status - inside the "Bank account" box we'll show
  • pending_requirement - the "Bank account" box with no other information, no fields, nothing; only the title
  • required - we need your bank account info w/ form and submit
  • verifying - we're verifying your bank account information
  • verified - show the success state with the bank account last 4 number and the full routing number

[joshsmith]

Also, let's not go down the rabbit hole of contact_status too much now, because we don't need it. I know my email is accurate, and this will be our only account right now.

[joshsmith]

The advantage of doing most of the status information as fields in the API (possibly even by updating the StripeConnectAccount model itself) is that we can even look at an admin dashboard to see where things stand for customer accounts and flag them for customer support early.

[begedin]

Agreed. I proposed the step.step_status format due to the potential extensibility, as you pretty much demonstrate in the list of possible statuses you posted, but I don't think we need most of those in the MVP.

I think

• account == null
• account.status == 'recipient.required'
• account.status == 'document.required'
• account.status == 'bank_acount.required'

with the potential addition of

• account.status == 'personal_id_number.required'

is what we need, though I think that last one can be circumvented with the ssn_last4 field on the recipient form, unless I'm not understanding that part correctly.

Also, it seems like you maybe want to make the status a nested object of boolean flags, instead of just a string? I'm not sure we need to go that way, at least not yet.

[joshsmith]

@begedin keep in mind that subcomponents can bypass the parents to send actions with https://github.com/DockYard/ember-route-action-helper