Skip to main content

Automating Form W-9 Using RequestByUrl (Payee-Initiated) Method - A Complete Workflow

· 7 min read
TaxBandits Tech

Form W-9 holds high significance among all the intricate facets of tax compliance, especially for businesses that deal with independent contractors.

TaxBandits API offers a seamless solution to automate the W-9 collection process right from your software or portal. By integrating TaxBandits API, you can automate the W-9 process in two different ways – RequestByURL (Payee-initiated) and RequestByEmail (Payer-Initiated).

In this blog, we’ll guide you on how to automate Form W-9 using the RequestByUrl Method.

1. Preliminary Steps

Before initiating the W-9 automation, you must complete a few preliminary procedures.

  • Webhook Configuration - As you may know, TaxBandits API employs webhooks to provide you with status updates regarding your filings. You can enable webhook notifications for different types of events. To receive updates related to W-9, you must configure the ‘Form W-9 Status Change’ webhook. This webhook payload will also contain the TIN matching status if it is opted as part of a W-9 request. If you prefer to opt for TIN Matching separately, then you must configure the ‘TIN Matching Status Change’ webhook as well.
note

In addition to webhook, TaxBandits also offers Web Messaging to receive W-9-related status notifications. Learn More

  • OAuth 2.0 Authentication - This is a common step for every endpoint. Before using any endpoint, you must get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. For detailed information, click here.

Header:-

{
"alg": "HS256", /*Algorithm = HS256*/
"typ": "JWT" /*Type = JSON Web Token (JWT)*/
}

Payload:-

{
"iss": "968a9c78dae29a29",  /*Issuer: Client ID retrieved from the console site*/
"sub": "968a9c78dae29a29",  /*Subject: Client ID retrieved from the console site*/
"aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token retrieved from the console site*/
"iat": 1516239022 /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
}

Signature:-

 HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg  /*Client Secret retrieved from the console site*/

 )

Sample JWS:-

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

OAuth server will receive the JWS & will validate to provide the JWT (Access token) in the following response format:

{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3Rlc3RvYXV0aC5leHByZXNzYXV0aC5uZXQvdjIvIiwic3ViIjoiOWYzZTQwM2RlMWQ5YTNkMiIsImF1ZCI6ImNhNjRkNzMyMzBhNDRkMjY4MjkzN2I2ODQ0ZmJjNTI4IiwiaWF0IjoxNjk0NTg1NDU4LCJleHAiOjE2OTQ1ODkwNTh9.WPOCs-lxo3GXz7_zGGmQovWZy4WD0smW7n-U-InuoXE",
"TokenType": "Bearer",
"ExpiresIn": 3600,
"Errors": null
}
  • Business Creation - Using the Business/Create endpoint, you can create the business for which you need to collect W-9.

Request:

   {
    "BusinessNm": "Snowdaze LLC",
    "PayerRef": "Snow123",
    "TradeNm": "Iceberg Icecreams",
    "IsEIN": true,
    "EINorSSN": "003313330",
    "Email": "james@sample.com",
    "ContactNm": "John",
    "Phone": "1234567890",
    "PhoneExtn": "12345",
    "Fax": "1234567890",
    "BusinessType": "ESTE",
    "SigningAuthority": {
        "Name": "James Smith",
        "Phone": "1234567890",
        "BusinessMemberType": "ADMINISTRATOR"
    },
    "KindOfEmployer": "FEDERALGOVT",
    "KindOfPayer": "REGULAR941",
    "IsBusinessTerminated": false,
    "IsForeign": true,
    "USAddress": {
        "Address1": null,
        "Address2": null,
        "City": null,
        "State": null,
        "ZipCd": null
    },
    "ForeignAddress": {
        "Address1": "22 St",
        "Address2": "Clair Ave E",
        "City": "Toronto",
        "ProvinceOrStateNm": "Ontario",
        "Country": "CA",
        "PostalCd": "M1R 0E9"
    }
}

Response:

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "BusinessId": "bfe7ee55-835c-4fe1-a2b7-1e7c3027598b",
    "PayerRef": "Snow123",
    "IsEIN": true,
    "EINorSSN": "XX-XXX3330",
    "BusinessNm": "Snowdaze LLC",
    "Errors": null
}

2. Using RequestByUrl Endpoint

Here comes the crucial part of W-9 automation!

Once the OAuth 2.0 process is complete, you can use [POST] FormW9/RequestByUrl endpoint. You can include the following parameters in your API request.

  • Access Token - As described earlier, you must include the JWT you obtained through the OAuth 2.0 process in the header of any API request.

  • Payee Reference (PayeeRef) - This can be a vendor ID, contractor number, payee’s email address, or any other value that uniquely identifies the corresponding recipient (payee) for whom you need a URL for W-9 completion.

  • Payee Name and Address (Optional) - In addition to the PayeeRef, your request may also include the payee’s name and address.

  • Business Identifier - When you created the business earlier, TaxBandits would have generated a Business ID in the response. You can either provide that or TIN in this request. If you fail to provide the business ID in this request, the W-9 collected from the payee will be stored under the default business, i.e., the first business added to your account.

  • Payee Name and Address (Optional) - In addition to the PayeeRef, your request may also include the payee’s name and address.

  • DBA Reference (Optional) - If the business has multiple DBA names, you can mention the DBA name you want to use as the Requester Name on W-9 Forms.

In addition to these, you can opt for TIN Matching in the same API request. All you need to do is set the ‘IsTINMatching’ to True.

3. Customization Options

TaxBandits API provides you with a wide range of options to showcase your brand identity wherever applicable.

Here, when requesting a W-9 using the RequestByUrl method, you will have the option to customize the W-9 completion page with your branding elements. To do so, you can provide the following parameters in the API request.

  • Business Logo - Provide the logo you want to be displayed on the page. Also, mention its position.
  • Color Theme - Provide the primary and secondary colors of the page to align with your branding.
  • Interview-Style - As an alternative to the traditional way of entering the information directly on the form, you can opt for interview-style W-9 completion.
  • ShowDownloadPage - If you prefer, you can opt to provide your payees with the option to download their W-9 form on a separate landing page. If you do not opt for this option, then the user will be redirected to the desired URL once they fill out and sign the form.
  • RedirectUrls - Once the payees complete or cancel their W-9 submission, you can redirect them to a specific URL of your preference.

Request :

{
    "Requester": {
        "PayerRef": "Snow123",
        "BusinessId": null,
        "TIN": null,
        "DBAId": null,
        "DBARef": null
    },
    "Recipient": {
        "PayeeRef": "12345",
        "Name": "Shawn Willams",
        "Address": {
            "Address1": "2603 Kinsey Road",
            "Address2": "Main Street",
            "City": "Dothan",
            "State": "AL",
            "ZipCd": "36303"
        },
        "IsTINMatching": true
    },
    "Customization": {
        "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
        "LogoPosition": "CENTER",
        "InterviewFlow": true,
        "PrimaryColor": "#E61A1A",
        "SecondaryColor": "#18F244",
        "ShowDownloadPage": true
    },
    "RedirectUrls": {
        "ReturnUrl": null,
        "CancelUrl": "https://example.com"
    }
}

Response :

{
    "SubmissionId": "abfdca28-0196-4157-b0a1-500d82a9d1ec",
    "PayeeRef": "12345",
    "W9Url": "https://testlinks.taxbandits.io?uId=90a20cbd-8a8c-479a-8e2d-f633b3ab54f3",
    "Errors": null
}

4. URL Generation and Embedding

Upon receiving your API request, TaxBandits will generate a unique secure URL for the payee and share it with you in the API response.

You can embed this URL as an iFrame in your software or portal that the payee will access. Typically, most businesses embed this URL in the onboarding page for the payees.

5. W-9 Completion and TIN Matching

Upon clicking this URL, the payee will be provided with a page where they can fill out their W-9 form. Once they complete, you’ll receive a webhook notification (if configured as described in preliminary steps) regarding the completion. The notification will also include a link to access the completed W-9.

Webhook Sample:

{
  "SubmissionId": "3b483eac-a102-4bad-8cbf-37cb09e94047",
  "Requester": {
    "BusinessId": "b7a03275-bb2a-4eb4-a745-65a1f50c9b5c",
    "PayerRef": "E3722",
    "BusinessNm": "Snowdaze LLC",
    "TINType": "EIN",
    "TIN": "XX-XXX2593",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "1236",
  "RecipientId": "734dfd22-5ce7-4112-b047-9f45cae73e12",
  "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
  "StatusTs": "2024-06-26 06:10:28 -04:00",
  "TINMatching": {
    "Status": "ORDER_CREATED",
    "StatusTs": "2024-06-26 06:10:29 -04:00",
    "StatusMsg": null,
    "Errors": null
  },
  "FormW9RequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/b09365b4-cf77-419f-a3bb-a1a78840b775.Pdf",
  "Email": null,
  "FormData": {
    "Line1Nm": "William",
    "Line2Nm": "Dairy Delights LLC",
    "TINType": "EIN",
    "TIN": "XX-XXX3752",
    "Address": {
      "Address1": "71 SAINT NICHOLAS DR",
      "Address2": null,
      "City": "NORTH POLE",
      "State": "AK",
      "ZipCd": "99705-7752"
    },
    "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
    "IsLine3b": false,
    "ExemptPayeeCd": null,
    "ExemptFromFATCA": null,
    "IsBackUpWH": false
  },
  "Errors": null
}

If you have opted for Web Messaging, you will receive a notification as shown in the below sample.

{
"uid": "a465421b-c878-471a-8d0e-3b6912336b65",
"iat": "1516239022",
"Status": "Signed",
"PayeeRef": "TMG108687",
"FormType": "FORMW9"
}

If you have opted for TIN Matching, you’ll receive that status in the subsequent webhook notifications. If TIN Matching fails, you may have to request a new W-9 from the payee again.

This is how you can automate the W-9 process using the RequestByUrl method. You can use the same procedure to automate Form W-8BEN using the FormW8Ben/RequestByUrl endpoint. If you want the recipients to choose and fill either W-9, W-8BEN, or W-8BEN-E based on their citizenship status, you can use the WhCertificate/RequestByUrl endpoint.

For more detailed information, you can refer to our comprehensive documentation.