Avoid costly engineering time by using our pre-built flows.

Wingspan offers two embeddable experiences:

• Contractor Onboarding The contractor onboarding embed enables your contractors to enter their W-9 information, accept electronic 1099 filing, complete any Signature requirements, configure their payout settings and more from within your app.
• Contractor Payout Settings The contractor payout settings embed allows your contractors to change their payout method over time. Once the user has successfully completed the onboarding flow, you can provide future editing of the payout settings by embedding payout settings.
• Would any other embed be valuable? Reach out to [email protected]

Setup and Authentication

Once access to the embeddable application has been configured for your organization’s access, you can use an iframe to load the onboarder app. Loading the app requires properly setting the iframe src and including a valid organization member token.

Embed Wingspan

To embed Wingspan, render an iFrame with the embed URL and pass the token as a query parameter.

<iframe src="<embedUrl>?token=<token>"></iframe>

📘

Maintaining onboarding progress

The contractor onboarding flow will always load the last incomplete step. If your contractor abandons the page and then returns, the rendered iFrame will be routed to the correct step.

Token Authentication

Single Token: Admin Access

• URL format: https://my.wingspan.app/dashboard?token=USER_TOKEN
• When only a token is provided, the system grants full admin access.
• The dashboard displays all sections without restrictions.

Dual Token: Team Member Access

• URL format: https://my.wingspan.app/dashboard?token=ACCOUNT_TOKEN&requestingToken=TEAM_MEMBER_TOKEN
• Using both token and requestingToken enables granular access control for team members.

Understanding Team Member Access

Team member access is based on Wingspan's Role-Based Access Control (RBAC) model, which uses a system of authorizations to determine what actions a user can perform:

1. Authorizations: These define the relationship between the requesting user (team member) and the principal user or resource being accessed. Each authorization specifies:

   • The requesting user's ID
   • The ID of the user or resource being accessed
   • The allowed scope or scope group
   • The allowed action (Read or Write)

2. Scope Groups: These are predefined sets of permissions that can be assigned to team members. For example:

   • "Finances" scope group allows access to bookkeeping and payment-related features
   • "Documents" scope group grants access to file management features
   • "Payments" scope group provides access to invoice and payment-related functionalities

When a team member accesses the dashboard using dual token authentication:

1. The system identifies the team member using the requestingToken.
2. It then checks the authorizations associated with this team member.
3. Based on these authorizations, the UI adapts to show only the sections and features the team member has permission to access.

Events

The embedded application utilizes window.parent.postMessage to send events to its parent container. You can handle these events using the following code snippet.

// Example message handler

window.addEventListener("message", function(message) {
	// You can change this origin value depending on environment
  if (
    message.origin === "https://onboarder.wingspan.app" ||
    message.origin === "https://staging-onboarder.wingspan.app"
  ) {
    try {
      const data = JSON.parse(message.data);
      if (data.source === "ws-embedded") {
        console.log('ws-embedded message', data);
      }
    } catch {}
  }
});

Events

Examples:

// Error loading session
//
// Can occur for multiple reasons, check response data for actionable item

{
    "source": "ws-embedded",
    "payload": {
        "event": "errorLoadingSession",
        "data": {
            "error": {
                "axiosError": {}, // axios error obj
                "response": {} // obj containing raw server response
            }
        }
    }
}

// Session loaded successfully
//
// The iframe was able to authenticate with the backend services

{
    "source": "ws-embedded",
    "payload": {
        "event": "sessionLoaded",
        "data": {}
    }
}

// Error loading member data
//
// This occurs when one or more of the requests we need to make to init the app
// fail to load, check response data for actionable items

{
    "source": "ws-embedded",
    "payload": {
        "event": "errorLoadingMemberData",
        "data": {
            "errors": [
                {}, // Axios error
                {} // Axios error
            ]
        }
    }
}

// Member completed onboarding
//
// The member completed all steps of onboarding

{
    "source": "ws-embedded",
    "payload": {
        "event": "onboardingComplete",
        "data": {}
    }
}

Additional Configuration Options

In this section, we will discuss additional configuration options available for the Wingspan onboarder. These options can help you tailor the onboarding experience for your users.

Excluding W-9 & TIN Verification

By default, the onboarding flow for US persons contractors includes the collection and verification of W-9 information. If you prefer not to collect W-9 information during onboarding, you can disable TIN verification by appending tin=0 as a query parameter to the iFrame URL.

Example:

https://onboarder.wingspan.app/onboarding?token=<TOKEN>&tin=0

Configuring Allowed Payout Methods

The Wingspan onboarder allows you to configure the payout methods available to your collaborators. You can do this by passing a comma-separated list of payout methods as a query parameter using enabled_payout_methods. If no enabled payout methods are specified, all payout methods excluding gift cards will be available by default.

Example:

https://onboarder.wingspan.app/onboarding?token=<TOKEN>&enabled_payout_methods=instant,ach,giftcard

The following table lists the supported payout methods and their corresponding query parameter values:

*Note that gift card payouts are invisible by default and must be explicitly enabled.

By implementing these additional configuration options, you can create a more streamlined and customized onboarding experience for your users.