Collecting Tax Documentation
This page is marked as deprecated, but Taxbit will continue supporting customers currently using these solutions. If you’d like to learn more about upgrading to our new React SDK with enhanced Digital W8/W9 support, reach out to our team today.
You can use the tax form we provide in the TaxBit SDK to collect tax documentation from your customers. We will securely store this tax information on our servers and use it to generate the necessary documents for tax compliance.
You can load the collection form using the code sample below.
Loading the tax documentation form
taxBit.ui.taxDocumentation.collect({
hostElement: document.querySelector("#tax-info-container")
});
This code will create an iframe and append it to the DOM element you specified in the hostElement
option. The host element must be able to contain nested elements. Typically, customers use a <div></div>
block as the host element. Regardless of your HTML, we recommend giving your container element an attribute ID, like <div id="taxbit-container"></div>
, making it easier to customize later.
The iframe will then display a form to collect tax documentation. We host this form on a TaxBit content delivery network (CDN). The iframe will use the entire width of the <div id="taxbit-container"></div>
block and will automatically resize its height to match the content inside the iframe.
If you'd like to restrain the height of the tax collection form, You can use CSS to set the height of the <div id="taxbit-container"></div>
block. You will also want to enable vertical scrolling. For example, <div id="taxbit-container" style="height: 3rem; overflow-y: scroll;"></div>
. Otherwise, people may only see the top part of your form. See the documentation for overflow-y for more information.
Receiving notification of critical events
The collect
function will return a promise, which the system will resolve once the collection form is fully loaded. We use an object to resolve this promise, which contains another promise that we resolve once the user completes the tax documentation form successfully.
After the form is submitted successfully, a link to download the PDF file is displayed for the end user.
Receiving notification of events
const collectResult = await taxBit.ui.taxDocumentation.collect({
hostElement: document.querySelector("#tax-info-container")
});
// At this point, the form has been loaded in the iframe.
await collectResult.formCompletion;
// At this point, the user has successfully completed the tax documentation form.
After successfully submitting Tax Documentation
Confirmation is shown and the user is given access to the PDF of the W-9, W-8BEN, or W-8BEN-E.
Handling errors
If errors occur while the form loads or while the user completes the form, the system will reject the promise. The SDK will do its best to display a friendly error message to the user.
You should also handle these errors and provide a graceful user experience tailored to your application. For example, you could navigate the user to another part of your program.
let collectResult;
try {
collectResult = await taxBit.ui.taxDocumentation.collect({
hostElement: document.querySelector("#tax-info-container")
});
} catch (error) {
// Handle the error that occurred while loading the form.
}
try {
await collectResult.formCompletion;
} catch (error) {
// Handle the error that occurred while the user was completing the form.
}
Specifying a document type
By default, the collection form will ask your customer for information to determine whether they need a W-8BEN, W-8BEN-E, or W-9 tax form. However, if you know which document the customer qualifies for, you can pass that information into the form when you create it using the documentType
key. Setting documentType
will prevent the form from generating tax-form-related fields.
taxBit.ui.taxDocumentation.collect({
hostElement: document.querySelector("#tax-info-container"),
});
Supported document types
- W-9
- W-8BEN
- W-8BEN-E
If you are unsure whether the user will need a W-8BEN, W-8BEN-E, or W-9, leave the documentType
blank. The SDK will ask questions to determine the appropriate document type for the account.
Providing pre-collected data
Your system likely already has some basic information about your customer, like a name and address. By providing this data to the SDK, the SDK can auto-populate related form fields or skip questions altogether, resulting in a more streamlined experience for your customer. You can use this functionality by providing a data object that includes your existing data.
taxBit.ui.taxDocumentation.collect({
hostElement: document.querySelector("#tax-info-container"),
data: {
documentType: "W-9"
name: "Anthony Michael Pearson",
address: {
firstLine: "123 Lenny St.",
secondLine: "Apt 204",
city: "Seattle",
stateOrProvince: "WA",
postalCode: "98101",
country: "US",
},
taxClassification: "INDIVIDUAL"
}
});
The pieces of data you are allowed to provide depend on the value you have specified for documentType
. If documentType
is left blank, you may provide data in any W-8BEN, W-8BEN-E, and W-9 forms.
Note: The SDK intentionally provides leniency for provided values. For example, if you pass an invalid value of foo for taxClassification
, the SDK will discard the value rather than throw an error. The collection form will then ask your customer any questions necessary to arrive at accurate and complete data. Rules for when field values will be discarded are detailed below.
Undetermined documentType
documentType
We support all fields found in the W-8BEN, W-8BEN-E, or W-9. The SDK will do its best to fill in the fields when possible, leading the user to a completed form.
name: string
(optional)
For individuals, the value of this key is the first and last name of the account owner, not the name of their company—for example, Phil Myman.
For businesses, this is the name of the business that owns the account. For example, Company ABC Inc.
The system will discard this value if you set the taxClassification
field to SMLLC.
address.firstLine: string (optional)
The value of this key is the first line of the customer's address.
The system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it from address.stateOrProvince. - You've set the
taxClassification
field to SMLLC.
address.secondLine: string
(optional)
The value of this key is the second line of the customer's address.
This system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
address.city: string
(optional)
The value of this key is the customer's city.
The system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
address.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions is true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
address.postalCode: string
(optional)
The value of this key is the postal code of the customer's address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
address.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
address.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using address.stateOrProvince
.
tin: string
(optional)
The value of this key is the customer's Taxpayer Identification Number (TIN).
The Taxpayer ID Number (TIN) can be in one of the following formats:
- NN-NNNNNNN
- NN-NNN-NNNN
- NNNNNNNNN
The system will discard this field if any of the following conditions are true:
- The value is not a nine-digit string.
- The
tinType
field is empty. - You've set the
taxClassification
field to SMLLC.
tinType: string
(optional)
The value of this key is the customer's TIN type.
Supported values:
- SSN
- EIN
The system will discard this field if any of the following conditions are true:
- The value is not supported.
- You have already entered a valid value in the
taxClassification
field. In this case, the system will automatically set the value oftinType
to the appropriate Tax ID type. - You've set the
taxClassification
field to SMLLC.
taxClassification: string
(optional)
The value of this key is the tax classification of the customer.
The supported values are:
- INDIVIDUAL
- SOLE_PROPRIETOR
- SMLLC
- C_CORPORATION
- S_CORPORATION
- PARTNERSHIP
- TRUST_ESTATE
- LLC_C
- LLC_S
- LLC_P
- OTHER
- CORPORATION
- SIMPLE_TRUST
- COMPLEX_TRUST
- GRANTOR_TRUST
- ESTATE
- CENTRAL_BANK_OF_ISSUE
- FOREIGN_GOVERNMENT_CONTROLLED_ENTITY
- FOREIGN_GOVERNMENT_INTEGRAL_PART
- TAX_EXEMPT_ORGANIZATION
- PRIVATE_FOUNDATION
- INTERNATIONAL_ORGANIZATION
- DISREGARDED_ENTITY
The system will discard this field if its value isn't one of the enumerated values above.
referenceNumbers: string
(optional)
The legal name of the account's beneficial owner or the US or foreign Disregarded Entity (DRE) owner.
country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's country of citizenship or country of incorporation or organization.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
address.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's permanent residence address.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.secondLine: string (optional)
The value of this key is the second line of the customer's permanent residence address.
This system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.city: string
(optional)
The value of this key is the customer's permanent residence city.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
permanentAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's permanent residence address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
permanentAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty or invalid, or the system cannot derive it from
permanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince
.
mailingAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's mailing address.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.secondLine: string
(optional)
The value of this key is the second line of the customer's mailing address.
This system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.city: string
(optional)
The value of this key is the customer's mailing city.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
mailingAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's mailing address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
mailingAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
mailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince
.
dateOfBirth: string
(optional)
For individuals, this key's value is the account owner's date of birth. It must be entered in the format MM/DD/YYYY.
The system will discard this field if any of the following conditions are true:
- If the provided string is not a valid date in this format.
- You've set the
taxClassification
field to SMLLC.
ftin: string
(optional)
The value of this key is the customer's foreign tax identification number (FTIN). There are no validations on foreign tax identification numbers.
It will be discarded if the taxClassification
is set to SMLLC.
ftinNotLegallyRequired: boolean
(optional)
The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.
dbaName: string
(optional)
The value of this field is the Doing Business As (DBA) name, trade name, or the disregarded entity name of the account owner. It is different from the name property listed above. For example, the name
field might be Pat Smith, whereas dbaName
might be Pat's Plumbing LLC.
exemptPayeeCode: string
(optional)
The exempt payee code applies to specific types of businesses and government entities generally exempt from backup withholding and information reporting requirements. These exempt codes generally do not apply to individuals.
There are thirteen codes, with values from 1 to 13, with each number representing a qualifying entity type. For example, payee code 7 means a futures commission merchant registered with the Commodity Futures Trading Commission. You can find all the exempt payee codes in the instructions on Form W-9.
The system will discard this field if any of the following conditions are true:
- The value is not a string representation of any number between 1 and 13.
- You've set the
taxClassification
field to SMLLC.
exemptionFatcaCode:string
(optional)
The Foreign Account Tax Compliance Act (FATCA) reporting exempt code is similar to the exempt payee code but relates to those businesses and government entities exempt from FATCA reporting. FATCA is a global tax regime directed at U.S. tax residents who maintain accounts with foreign financial institutions. These exempt codes generally do not apply to individuals.
There are thirteen codes, with values of A to M, with each letter representing a qualifying entity type. For example, FATCA exempt code D means a corporation whose stock is regularly traded on one or more established securities markets as described in Regulations section 1.1472-1(c)(1)(i). You can find all the exempt payee codes in the instructions on Form W-9.
The system will discard this field if any of the following conditions are true:
- The value is not a character between A and M.
- You've set the
taxClassification
field to SMLLC.
otherTaxClassification: string
(optional)
If the customer falls into another tax classification, provide the tax classification of that entity. Any string is acceptable.
W-9 documentType
documentType
The following are W-9 properties.
dbaName: string
(optional)
The value of this field is the Doing Business As (DBA) name, trade name, or the disregarded entity name of the account owner. It is different from the name property listed above. For example, the name field might be Pat Smith, whereas dbaName
might be Pat's Plumbing LLC.
taxClassification: string
(optional)
The value of this key is the tax classification of the customer.
The supported values are:
- INDIVIDUAL
- SOLE_PROPRIETOR
- SMLLC
- C_CORPORATION
- S_CORPORATION
- PARTNERSHIP
- TRUST_ESTATE
- LLC_C
- LLC_S
- LLC_P
- OTHER
- DISREGARDED_ENTITY
The system will discard this field if its value isn't one of the enumerated values above.
otherTaxClassification: string
(optional)
If the customer falls into another tax classification, provide the tax classification of that entity. Any string is acceptable.
The system will discard this field unless you set the taxClassification
field to OTHER.
exemptPayeeCode: string
(optional)
The exempt payee code applies to specific types of businesses and government entities generally exempt from backup withholding and information reporting requirements. These exempt codes generally do not apply to individuals.
There are thirteen codes, with values from 1 to 13, with each number representing a qualifying entity type. For example, payee code 7 means a futures commission merchant registered with the Commodity Futures Trading Commission. You can find all the exempt payee codes in the instructions on Form W-9.
The system will discard this field if any of the following conditions are true:
- The value is not a string representation of any number between 1 and 13.
- You've set the
taxClassification
field to SMLLC.
exemptionFatcaCode:string
(optional)
The Foreign Account Tax Compliance Act (FATCA) reporting exempt code is similar to the exempt payee code but relates to those businesses and government entities exempt from FATCA reporting. FATCA is a global tax regime directed at U.S. tax residents who maintain accounts with foreign financial institutions. These exempt codes generally do not apply to individuals.
There are thirteen codes, with values of A to M, with each letter representing a qualifying entity type. For example, FATCA exempt code D means a corporation whose stock is regularly traded on one or more established securities markets as described in Regulations section 1.1472-1(c)(1)(i). You can find all the exempt payee codes in the instructions on Form W-9.
The system will discard this field if any of the following conditions are true:
- The value is not a character between A and M.
- You've set the
taxClassification
field to SMLLC.
address.firstLine: string
(optional)
The value of this key is the first line of the customer's address.
The system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
address.secondLine: string
(optional)
The value of this key is the second line of the customer's address.
This system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
address.city: string
(optional)
The value of this key is the customer's city.
The system will discard this field if any of the following conditions are true:
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
address.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
address.postalCode: string
(optional)
The value of this key is the postal code of the customer's address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
address.country
field is empty, invalid, or the system cannot derive it fromaddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
address.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
address.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using address.stateOrProvince.
tinType: string
(optional)
The value of this key is the customer's TIN type.
Supported values:
- SSN
- EIN
The system will discard this field if any of the following conditions are true:
- The value is not supported.
- You have already entered a valid value in the
taxClassification
field. In this case, the system will automatically set the value oftinType
to the appropriate Tax ID type. - You've set the
taxClassification
field to SMLLC.
W-8BEN documentType
documentType
The following are W-8BEN properties.
referenceNumbers: string
(optional)
The legal name of the beneficial owner of the account.
country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's country of citizenship.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
address.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
taxClassification: string
(optional)
The value of this key is the tax classification of the customer.
The supported value is:
- INDIVIDUAL
The system will discard this field if its value isn't one of the enumerated values above.
permanentAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's permanent residence address.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.secondLine: string
(optional)
The value of this key is the second line of the customer's permanent residence address.
This system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.city: string
(optional)
The value of this key is the customer's permanent residence city.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions is true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field.
permanentAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's permanent residence address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
permanentAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
permanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince
.
mailingAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's mailing address.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.secondLine: string
(optional)
The value of this key is the second line of the customer's mailing address.
This system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.city: string
(optional)
The value of this key is the customer's mailing city.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
mailingAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's mailing address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
mailingAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
mailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince
.
dateOfBirth: string
(optional)
For individuals, this key's value is the account owner's date of birth. It must be entered in the format MM/DD/YYYY.
The system will discard this value if you set the taxClassification
field to SMLLC.
ftin: string
(optional)
The value of this key is the customer's foreign tax identification number (FTIN).
ftinNotLegallyRequired: boolean
(optional)
The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.
W-8BEN-E documentType
documentType
The following are W-8BEN-E properties.
referenceNumbers: string
(optional)
The legal name of the US or foreign Disregarded Entity (DRE) owner.
The system will discard this value if you set the taxClassification
field to SMLLC.
country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the country of incorporation or organization of the customer.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
address.stateOrProvince
.
taxClassification: string
(optional)
The value of this key is the tax classification of the customer.
The supported value is:
- CORPORATION
- PARTNERSHIP
- SIMPLE_TRUST
- COMPLEX_TRUST
- GRANTOR_TRUST
- ESTATE
- CENTRAL_BANK_OF_ISSUE
- FOREIGN_GOVERNMENT_CONTROLLED_ENTITY
- FOREIGN_GOVERNMENT_INTEGRAL_PART
- TAX_EXEMPT_ORGANIZATION
- PRIVATE_FOUNDATION
- INTERNATIONAL_ORGANIZATION
- DISREGARDED_ENTITY
The system will discard this field if its value isn't one of the enumerated values above.
permanentAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's permanent residence address.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.secondLine: string
(optional)
The value of this key is the second line of the customer's permanent residence address.
This system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.city: string
(optional)
The value of this key is the customer's permanent residence city.
The system will discard this field if any of the following conditions are true:
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
permanentAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field.
permanentAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's permanent residence address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
permanentAddress.country
field is empty or invalid, or the system cannot derive it frompermanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
permanentAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's permanent residence country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
permanentAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using permanentAddress.stateOrProvince.
mailingAddress.firstLine: string
(optional)
The value of this key is the first line of the customer's mailing address.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.secondLine: string
(optional)
The value of this key is the second line of the customer's mailing address.
This system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.city: string
(optional)
The value of this key is the customer's mailing city.
The system will discard this field if any of the following conditions are true:
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
mailingAddress.stateOrProvince: string
(optional)
If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is within Canada, this must be the ISO 3166-2:CA two-letter state code, otherwise, if it’s outside the U.S., this is a free-form string.
The system will discard this field if any of the following conditions are true:
- The state code is invalid for the country. For example, if you set the
address.country
to US and the state to ZZ, the system would discard this field. - You've set the
taxClassification
field to SMLLC.
mailingAddress.postalCode: string
(optional)
The value of this key is the postal code of the customer's mailing address.
U.S. Postal Codes can be in one of the following formats:
- NNNNN
- NNNNNNNNN
- NNNNN-NNNN
The system will discard this field if any of the following conditions are true:
- If the address is within the U.S., but the postal code is not a five or nine-digit string.
- The
mailingAddress.country
field is empty or invalid, or the system cannot derive it frommailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If the system discards this field, it will ask the customer to enter a valid postal code.
mailingAddress.country: string
(optional)
The value of this key is the ISO 3166-2 two-letter country code for the customer's mailing country.
The system will discard this field if any of the following conditions are true:
- The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derive it from
mailingAddress.stateOrProvince
. - You've set the
taxClassification
field to SMLLC.
Note: If you don't provide a value for this field, the system will try to derive the country code using mailingAddress.stateOrProvince
.
ftin: string
(optional)
The value of this key is the customer's foreign tax identification number (FTIN).
ftinNotLegallyRequired: boolean
(optional)
The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.
Updated 26 days ago