Submit W-8BEN-E tax form

post

https://{environment}.masspay.io/{VERSION}/payout/{user_token}/tax/interview/w8bene

This POST endpoint is used to submit a W-8BEN-E tax form for a specific user identified by their user_token. The W-8BEN-E form is used by foreign entities to certify their foreign status, chapter 3 status, chapter 4 (FATCA) status, and claim tax treaty benefits (if applicable). Basic information (name, address, phone) is retrieved from the user's existing profile.
To use this endpoint, you need to provide the user_token as a parameter in the URL Path and the W-8BEN-E form data in the request body.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

user_token

string

required

Body Params

organization_name

string

required

length ≤ 40

Name of the organization

country_of_organization

string

required

length between 2 and 2

Two-letter country code of organization

disregarded_entity_name

string

length ≤ 80

Disregarded entity name (if applicable)

chapter_3_status

string

enum

required

Chapter 3 status. FOREIGN CONTROLLED ENTITY and FOREIGN INTERGRAL PART are the IRS 'Foreign government - controlled entity' and 'Foreign government - integral part' statuses. DISREGARDED ENTITY requires disregarded_entity_branch.

chapter_4_status

string

enum

required

Chapter 4 (FATCA) status. The certification part the IRS form requires for the selected status is filled automatically; statuses that certify extra facts take them from chapter_4_certification: SPONSORED FFI (sponsoring_entity_name, sponsored_ffi_type), OWNER DOCUMENTED FFI (certification_line 24b-24d), RESTRICTED DISTRIBUTOR (certification_line 25b-25c), NONREPORTING IGA FFI (iga_country, iga_model, iga_treated_as), INTERNATIONAL ORGANIZATION (certification_line 28a-28b), EXEMPT RETIREMENT PLANS (certification_line 29a-29f), EXCEPTED NONFINANCIAL STARTUP (formed_on), 501C ORGANIZATION (irs_determination_letter_date), PUBLICLY TRADED NFFE (securities_market_name, or affiliate_entity_name + affiliate_securities_market_name), SPONSORED DIRECT REPORTING FFI (sponsoring_entity_name). DIRECT REPORTING NFFE and the participating / reporting / registered / sponsored FFI statuses require giin. The tax provider currently rejects NONREPORTING IGA FFI, NONREGISTERING LOCALBANK, FFI LOWVALUE ACCOUNT, SPONSORED INVESTMENT VEHICLE, LIMITED LIFEDEBT INVESTMENT, NO FINANCIAL ACCOUNT, FOREIGN GOVERNMENT and EXCEPTED NONFINANCIAL LIQUIDATION BANKRUPTCY; submissions with those values return 400 before reaching the provider.

us_tin_type

string

enum

Type of US TIN (if applicable)

Allowed:

us_tin

string

US Taxpayer Identification Number (if applicable)

giin

string

length ≤ 19

^[A-Z0-9]{6}\.[A-Z0-9]{5}\.[A-Z]{2}\.[0-9]{3}$

Global Intermediary Identification Number in the IRS format XXXXXX.XXXXX.XX.XXX: 6 alphanumerics (FATCA ID), 5 alphanumerics (financial institution type), a 2-letter category code (LE, SL, ME, BR, SP, SD, SF, SS or SB) and the 3-digit ISO numeric country code. Required for DIRECT REPORTING NFFE and the participating / reporting / registered / sponsored FFI statuses.

foreign_tin

string

length ≤ 25

Foreign Tax Identification Number

is_ftin_not_legally_required

boolean

Defaults to false

Check if FTIN is not legally required

reference_number

string

length ≤ 50

Reference number for your records

is_hybrid_entity_treaty_claim

boolean

Defaults to false

Is entity a hybrid making a treaty claim

tax_treaty_benefits

object

limitation_on_benefits

string

enum

Limitation on benefits provision (Part III line 14b). Accepted here or inside tax_treaty_benefits. OTHER requires limitation_on_benefits_other_detail.

limitation_on_benefits_other_detail

string

length ≤ 35

Article and paragraph relied on when limitation_on_benefits is OTHER

disregarded_entity_branch

object

chapter_4_certification

object

Facts certified in the W-8BEN-E Part IV-XXVIII that matches chapter_4_status. Only the fields for the selected status are read.

substantial_us_owners

array of objects

List of substantial US owners (for passive NFFE)

substantial_us_owners

certification

object

required

Responses

404

Not Found

200OK

400Bad request.

401Unauthorized.

403Forbidden.

405Method Not Allowed.

500Internal server error.

504Gateway Time-out.