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.

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.