Onboarding Widget

This widget shows users marketing information about the embedded account, and kicks off the onboarding flow. It pulls in your logo, bank account name and marketing text from Tesouro’s database. The marketing text will be defined by you, Tesouro, and the bank, and it must be approved by the bank. After the user sees marketing information in a modal pop-up, it will transition to the onboarding flow below:

This onboarding flow lets new business users sign up for an embedded account and submit their information for a KYC/KYB validation with the bank. You can pre-fill as many data fields as you have, so there’s less for the applicant to fill in.

Authentication and application lifecycle

The onboarding widget authenticates against a single bank account application using a short-lived application client secret, not a backend bearer token. Your backend creates the application server-to-server, receives the secret in the create response, and passes it to the widget: the rest of the flow (edits, verification, submission) runs in the browser. If the applicant returns after the secret has expired, your backend re-issues one through the resume endpoint and the new secret is delivered to the applicant by email. For the full sequence of states, transitions, and which auth method each step requires, see the application lifecycle guide. There are 3 entities we need information on:

Business entity - The legal information on the business itself.
Business controller - An individual with the power to direct a business’s financial activities or policies, even if they aren’t the legal owner (e.g. the CEO, CFO or a VP).
Beneficial owners - A person who owns 25% or more of the company’s ownership interests (directly or indirectly).

A business may have between zero and 4 beneficial owners.

Pre-filling data fields in the onboarding form

The following data fields are required for onboarding. If you already store any of these fields, you can pass them in to the flow in your code that invokes the onboarding widget and they will be pre-filled in the UI. Users can always edit any pre-filled fields. See the code snippet below for details on the structure of these objects in your HTML.

Onboarding Field	Pre-fill Parameter	Example
Company legal name	`companyLegalName`	`Nail It Technology, Inc.`
Company DBA name	`companyDbaName`	`Nail It`
Company address	`businessAddress`	`123 Main St.`
Company city	`city`	`Phoenix`
Company state	`state`	`Arizona`
Company ZIP code	`zipCode`	`85001`
Company phone number	`companyPhoneNumber`	`555-345-3434`
Company business structure	`companyStructure`	`llc`
Company website	`website`	`https://www.website.com`
Company EIN or Tax ID	`taxId`	`123456789`
Company industry NAICS code	`industryCode`	`111331`
Controller first name	`firstName`	`Jack`
Controller last name	`lastName`	`Smith`
Controller date of birth	`dateOfBirth`	`01-01-1999`
Controller SSN	`ssn`	`213-45-6789`
Controller home address	`homeAddress`	`234 Main St.`
Controller city	`city`	`Chicago`
Controller state	`state`	`IL`
Controller ZIP code	`zipCode`	`22313`
Controller work email	`workEmail`	`jack.smith@example.com`
Controller phone number	`mobilePhoneNumber`	`555-345-2343`
Controller is also owner	`ownsOver25Percent`	`yes`
Controller ownership percent	`ownershipPercentage`	`50`
Beneficial owner first name	`firstName`	`Jane`
Beneficial owner last name	`lastName`	`Doe`
Beneficial owner date of birth	`dateOfBirth`	`02-15-1990`
Beneficial owner SSN	`ssn`	`123456789`
Beneficial owner address	`homeAddress`	`123 Main St.`
Beneficial owner city	`city`	`New York`
Beneficial owner state	`state`	`New York`
Beneficial owner ZIP code	`zipCode`	`99999`
Beneficial owner phone number	`phoneNumber`	`5552344456`
Beneficial owner percent	`ownershipPercentage`	`46`

Returning your user to the right place after onboarding

At the end of the onboarding flow, our modal can present the user a button to navigate to the banking section of your dashboard. You can pass in the location of the banking section of your dashboard using the data-banking-dashboard-href parameter.

Onboarding statuses

There are three potential outcomes of the application submission:

Instant Approval - The user can immediately view the banking dashboard and start using the account.
Manual Review - Some applications need more time for the bank to review the information for accuracy. The bank emails the user when the review is complete.
Denied - An application can be denied if it appears fraudulent or too risky for the bank to take on.

Paste this code snippet to place the widget in your site:

<embedded-onboarding-widget
  data-banking-dashboard-href="/banking"
  data-business-details-form='{
    "companyLegalName": "Test Company Legal Name",
    "companyDbaName": "Test Company DBA Name",
    "businessAddress": "123 Main St",
    "city": "Phoenix",
    "state": "Arizona",
    "zipCode": "85001",
    "companyPhoneNumber": "360-921-8800",
    "companyStructure": "llc",
    "website": "https://www.google.com",
    "taxId": "123456789",
    "industryCode": "111331"
    }'
  data-personal-details-form='{
    "firstName": "Jack",
    "lastName": "Smith",
    "dateOfBirth": "03-01-1997",
    "ssn": "123-45-6789",
    "homeAddress": "123 Main St",
    "city": "Phoenix",
    "state": "Arizona",
    "zipCode": "85001",
    "workEmail": "jack.smith@example.com",
    "isAuthorized": false,
    "mobilePhoneNumber": "123-456-7890",
    "ownsOver25Percent": "yes",
    "ownershipPercentage": "50"
    }'
  data-additional-business-owners='[
      {
        "id": "1",
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "02-15-1990",
        "ssn": "123456789",
        "homeAddress": "123 Main St",
        "city": "Phoenix",
        "state": "Arizona",
        "zipCode": "85001",
        "phoneNumber": "5551234567",
        "ownershipPercentage": "25"
      },
      {
        "id": "2",
        "firstName": "Aaron",
        "lastName": "Jones",
        "dateOfBirth": "06-01-1985",
        "ssn": "987654321",
        "homeAddress": "456 Oak Ave",
        "city": "Phoenix",
        "state": "Arizona",
        "zipCode": "85001",
        "phoneNumber": "5559876543",
        "ownershipPercentage": "25"
      }
    ]'
></embedded-onboarding-widget>

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

Embedded components

White-label

Onboarding Widget

Authentication and application lifecycle

Pre-filling data fields in the onboarding form

Returning your user to the right place after onboarding

Onboarding statuses

​Authentication and application lifecycle

​Pre-filling data fields in the onboarding form

​Returning your user to the right place after onboarding

​Onboarding statuses

Authentication and application lifecycle

Pre-filling data fields in the onboarding form

Returning your user to the right place after onboarding

Onboarding statuses