Create A Legal Entity
Onboard submerchants to Chase Merchant Services using WePay's Onboarding as a Service APIs. Learn about Onboarding as a Service order of operations and API schemas in this article.
Note
WePay does not currently support ITINs (any value in a social security number field starting with a 9).
A: Create a Legal Entity
In this section, you will learn how to make a POST /legal_entities
API request, handle the id
in the API response, and how to differentiate API errors from errant fields.
The Legal Entity that you'll create here represents a submerchant's business, controller, and beneficial owner information. Note that there is already a Legal Entity associated with your API credentials, but you'll create a unique Legal Entity through an API request for each submerchant that you onboard.
Note
Either 3.0.rc.1.1
or 3.0
can be used in the Version
header for this step. Your request will be based on the 3.0 API specification.
To create a Legal Entity, you'll first need to collect all the required data from the submerchant. WePay recommends providing a form which submerchant can access repeatedly so that they can provide details as they find the documentation on their end. On your back end, you should collect the data they submit and only construct and send the POST /legal_entities
request once all data requirements are met.
Note
The following legal_form
entities are not currently supported via our API for FLS onboarding, and must be onboaded using your existing flow for the time being:
- Individuals
- Nonprofit Corporations
- Unincorporated Associations
- Personal Trust
- Statutory Trust
Required Legal Entity Fields
Click to view all required Legal Entity fields
Field | Sole Prop | LLC | Partnership | Corp | Gov Entity |
---|---|---|---|---|---|
country | Required | Required | Required | Required | Required |
controller_type This field will specify Controller Vs Account Controller. An account controller is an authorized representative who controls the merchant account and can call in for support. The account_controller replaces the controller object for government entities and publicly traded companies (including subsidiaries). | Required | Required | Required | Required | Required |
Fields in the controller object | |||||
name.first_name | Required | Required | Required | Required | Required |
name.last_name | Required | Required | Required | Required | Required |
name.middle | Required | Required | Required | Required | Required |
name.suffix | Optional | Optional | Optional | Optional | Optional |
name.prefix | Optional | Optional | Optional | Optional | Optional |
address.* This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional | Required | Required | Required | Required | Required |
date_of_birth.* This applies to all date of birth fields (day, month, year) | Required | Required | Required | Required | Required |
personal_country_ info.US.social_ security_number | Required | Required | Required | Required | Required |
phone.* This applies to both phone fields (country code, phone number) | Required | Required | Required | Required | Required |
job_title | Required | Required | Required | Required | Required |
email | Required | Required | Required | Required | Required |
email_is_verified | Required | Required | Required | Required | Required |
Fields in the account_controller object | |||||
name.first_name | N/A | Required | Required | Required | Required |
name.last_name | N/A | Required | Required | Required | Required |
name.middle | N/A | Optional | Optional | Optional | Optional |
name.suffix | N/A | Optional | Optional | Optional | Optional |
name.prefix | N/A | Optional | Optional | Optional | Optional |
address.* This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional | N/A | Required | Required | Required | Required |
phone.* This applies to both phone fields (country code, phone number) | N/A | Required | Required | Required | Required |
job_title | N/A | Required | Required | Required | Required |
email | N/A | Required | Required | Required | Required |
email_is_verified | N/A | Required | Required | Required | Required |
Fields in the additional_representatives.representative_X object(s)An additional representative is any beneficial owner with 25% or more of the merchant’s equity | |||||
is_auxiliary_ controller | N/A | Optional | Optional | Optional | N/A |
is_beneficial_ owner | N/A | Optional | Optional | Optional | N/A |
address.* This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional | N/A | Required | Required | Required | N/A |
date_of_birth.* This applies to all date of birth fields (day, month, year) | N/A | Required | Required | Required | N/A |
email | N/A | Required | Required | Required | N/A |
email_is_verified | N/A | Required | Required | Required | N/A |
name.first_name | N/A | Required | Required | Required | Required |
name.last_name | N/A | Required | Required | Required | Required |
name.middle | N/A | Optional | Optional | Optional | N/A |
name.suffix | N/A | Optional | Optional | Optional | N/A |
name.prefix | N/A | Optional | Optional | Optional | N/A |
personal_country_ info.US.social_ security_number | N/A | Required | Required | Required | N/A |
phone.* This applies to both phone fields (country code, phone number) | N/A | Required | Required | Required | N/A |
job_title | N/A | Optional | Optional | Optional | N/A |
Entity information (top-level parameters in the Legal Entity object) | |||||
address.* This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional | Optional | Required | Required | Required | Required |
description Business description | Required | Required | Required | Required | Required |
email Business email | Optional | Optional | Optional | Optional | Optional |
entity_name | Required | Required | Required | Required | Required |
phone.* This applies to both phone fields (country code, phone number) | Required | Required | Required | Required | Required |
primary_url If the merchant has a website, provide it here | Optional | Optional | Optional | Optional | Optional |
Fields in the entity_country_info object | |||||
US.employer_ identification_ number | Optional | Required | Required | Required | Required |
US.legal_form | Required | Required | Required | Required | Required |
country_of_formation | Required | Required | Required | Required | Required |
operates_in_ sanctioned_countries | Required | Required | Required | Required | Required |
year_of_formation | Required | Required | Required | Required | Required |
Fields in the public_ownership objectOnly applicable when public_ownership.is_publicly_traded is set to true | |||||
is_publicly_traded | N/A | Required | Required | Required | N/A |
is_subsidiary | N/A | Required | Required | Required | N/A |
parent_company_name | N/A | Required | Required | Required | N/A |
traded_exchanges. X.symbol Provide the ticker symbol for each exchange the merchant is traded on | N/A | Required | Required | Required | N/A |
Fields in the terms_of_service object | |||||
acceptance_time | Required | Required | Required | Required | Required |
original_ip | Required | Required | Required | Required | Required |
terms_of_service_ version | Optional | Optional | Optional | Optional | Optional |
Fields in the attestation object | |||||
attester_type | Required | Required | Required | Required | Required |
Fields in one of: attestation.additional_representative , attestation.controller , or attestation.other_representative objects | |||||
attester_time | Required | Required | Required | Required | Required |
original_ip | Required | Required | Required | Required | Required |
representative_id Only applicable to the additional representative option | Required | Required | Required | Required | Required |
name.* Only applicable to the other representative option | Required | Required | Required | Required | Required |
job_title Only applicable to the other representative option | Required | Required | Required | Required | Required |
Fields in the token object | |||||
id This should be the token ID returned by the WePay JS when the token is created | Required | Required | Required | Required | Required |
WePay-Risk-Token This is a param sent in the request header, not in the JSON body, and is required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS |
Client-IP This is a param sent in the request header, not in the JSON body, and is required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS | Conditionally required when tokenizing without the WePay JS |
The POST /legal_entities
request should look something like this:
curl -X POST \
--url 'https://stage-api.wepay.com/legal_entities' \
-H 'App-Id: {App-Id}'\
-H 'App-Token: {App-Token}'\
-H 'Accept: application/json'\
-H 'Api-Version: {3.0 or 3.0.rc.1.1}'\
-H 'Content-Type: application/json' \
--data-raw '{
"country": "US",
"description": "{des}",
"primary_url": "",
"entity_name": "",
"phone": {
"country_code": "",
"phone_number": ""
},
"address": {
"city": "",
"country": "{country-code}",
"line1": "{street-address}",
"postal_code": "{zip}",
"region": "{state}"
},
"terms_of_service": {
"acceptance_time": {unix-timestamp},
"original_ip": "{user-ip-address}"
},
"controller": { //publicly traded companies & gov. entities use account_controller
"email": "{email-address}",
"email_is_verified": true,
"is_beneficial_owner": {true/false}, //not applicable to account_controllers
"job_title": "",
"name": {
"first": "",
"last": ""
},
"address": {
"city": "",
"country": "{country-code}",
"line1": "{street-address}",
"postal_code": "{zip}",
"region": "{state}"
},
"phone": {
"country_code": "",
"phone_number": ""
},
"date_of_birth": { //must NOT be collected from account_controllers
"day": 01,
"month": 01,
"year": 1990
},
"personal_country_info": { //must NOT be collected from account controllers
"US": {
"social_security_number"
}
}
},
"entity_country_info": {
"US": {
"employer_identification_number": "123211230"
},
"country_of_formation": "CA",
"operates_in_sanctioned_countries": [ //only for SMB type platforms (entity onboarding the merchant to CMS)
"CU",
"SY"
],
"year_of_formation": 1991
},
"significant_beneficiaries": {
"non_domestic_location_beneficiaries": [ //only for fundraising type platforms (entity onboarding the merchant to CMS)
"CA"
]
},
"additional_representatives": { //not applicable to account_controllers
"representative_{X}": {
"name": {
"first": "",
"last": ""
},
"address": {
"city": "",
"country": "{country-code}",
"line1": "{street-address}",
"postal_code": "{zip}",
"region": "{state}"
},
"phone": {
"country_code": "",
"phone_number": ""
},
"date_of_birth": {
"day": 01,
"month": 01,
"year": 1990
},
"personal_country_info": {
"US": {
"social_security_number"
}
}
}
},
"public_ownership": {
"is_publicly_traded": {bool}, //only applicable to publicly traded companies (subsidiaries pass false)
"is_subsidiary": {bool},
"parent_company_name": "", //only applicable to subsidiaries
"traded_exchanges": {
"{NYSE/AMEX/NASDAQ}": {
"symbol": "" //subsidiaries should pass the ticker symbol of their parent company
}
}
}
}'
The API response will contain a Legal Entity ID on the id
parameter, which is the ID for the Legal Entity. This ID will be used to create the submerchant's Payout Method and Account in the next steps.
Note that any API errors thrown on this step (before creation of the Legal Entity and returning of the ID) are not considered errant fields, but are API level validations. API error handling guidance can be found here.