API Reference

Submit W-8BEN-E tax form

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

This POST endpoint is used to submit a W-8BEN-E tax form (for foreign entities) for a specific user identified by their user_token. Basic information (name, address, phone) is retrieved from the user's existing profile.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
Body Params
string
required
length ≤ 40

Name of the organization

string
required
length between 2 and 2

Two-letter country code of organization

string
length ≤ 80

Disregarded entity name (if applicable)

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.

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.

string
enum

Type of US TIN (if applicable)

Allowed:
string

US Taxpayer Identification Number (if applicable)

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.

string
length ≤ 25

Foreign Tax Identification Number

boolean
Defaults to false

Check if FTIN is not legally required

string
length ≤ 50

Reference number for your records

boolean
Defaults to false

Is entity a hybrid making a treaty claim

tax_treaty_benefits
object
string
enum

Limitation on benefits provision (Part III line 14b). Accepted here or inside tax_treaty_benefits. OTHER requires 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

Updated 13 days ago

Did this page help you?
Language
Credentials
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 13 days ago

Did this page help you?