RequestByUrl

RequestByUrl

This is a payee-initiated method wherein the secure URL provided by the TaxBandits API will be embedded in the client’s software or portal, enabling the payees/vendors to start the W-8BEN completion process on their own.

To complete Form W-8BEN, TaxBandits will provide a secure URL that can be opened on its own or embedded as an Iframe into a web page or native app. To get this URL, you will have to send a request to our API with a unique Payee Reference such as vendor id, contractor number or a random number, or even an email address (This will be used for the future references of the payee) and a business identifier (Business Id or TIN).

If you have a portal for your vendors, you can use this method to embed a secure URL and collect the W-8BEN information during the vendor onboarding process. Each vendor who logs in will get a unique URL-embedded page to complete their W8-BEN.

How does this work?

1. Call the [GET] FormW8Ben/RequestByUrl endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page. Supply the following parameters:

   • Access Token in the header as Bearer Token (generated using TaxBandits OAuth authentication API).
   • Payee Reference (unique information that identifies the Recipient). Can be the Vendor id, contractor number, recipient email address, or a random number. Will be used to identify the recipient for future references.
   • PayerRef (Optional), Business Id (Business Identifier) or TIN - To identify and save the W9/W-8BEN under a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits. If you don’t supply one in the request, it will be associated with the default business (first business created in your account).
   • Recipient Name and Address (optional) - The recipient information will be pre-filled on the form when passed in the request.
   • Business Logo and Callback URLs (optional) - Customize the business logo on the form W8-BEN. Set callback redirection URLs upon submission or cancelation. 

2. TaxBandits API will generate a unique URL and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the recipients to click. When clicked, the recipient will be provided with the form W-8BEN with built-in validations. An electronic signature pad that allows the recipient to sign electronically and submit the form is available.

3. Once the recipient completes and signs the form, you will be notified via webhook. The webhook payload will have the recipient data such as Name, Citizenship country, address, and reduced tax rate for W-8BEN.

Refer to the Form W-8BEN webhook to know more about webhook set up and sample payload.

Note:

The default business details will be considered as the requester's details.

GET FormW8Ben/RequestByUrl 

Run in Postman

Request Params

Field	Type	Description
PayeeRef	String	A unique identifier for each recipient completing the Form W-8BEN. This identifier will be used in future references of the recipient in the API Size Range: 1-50
BusinessId	Guid	Optional TaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint. If you do not supply the BusinessId in the request, then the URL will be generated using the default business (First business created in your account).
TIN	String	Optional Taxpayer Identification Number. Use this as an alternative for BusinessId. Values: EIN, SSN Note : You need to supply one of these values - TIN or TBS Business Id. If neither is supplied, the default Business will be assumed. Size Range: 9-11(Including hyphen)

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
PayeeRef	String	Unique identifier of the recipient.
W8BenUrl	String	URL that can be accessed on its own or embedded on the client's website using Iframe or other means.
Errors	object[]	Collection of errors for the Recipient
Id	string	Error ID number. This ID is assigned by TaxBandits and it is unique for each error.
Name	string	Name of the errored node.
Message	string	Shows the error message

Request Json

Sample 1

Request W-8BEN URL using Payee Reference and BusinessId. Make sure to configure the W-8BEN Webhook console.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522&BusinessId=314ddb71-a6ac-4312-ab09-7ad9a2b3507d

Sample 2

Request W-8BEN URL using Payee Reference and TIN.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522&TIN=123456789

Sample 3

Request W-8BEN URL using Payee Reference.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522

Response JSON

Response 1

Distinctive URL is generated for specific PayeeRef and Business ID. The completed Form W-8BEN will save against a specific business. When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
"SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
"PayeeRef":"Pe464522",  
"W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
"Errors":null
}

Response 2

A unique URL is generated for specific PayeeRef and TIN. The completed form will be saved against a specific Business TIN. When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
"SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
"PayeeRef":"Pe464522", 
"W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
"Errors":null
}

Response 3

A unique URL will be generated for specific PayeeRef. Since the business id is not specified, the completed Form W-8BEN will save against a default Business."  When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
"SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
"PayeeRef":"Pe464522", 
"W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
"Errors":null
}