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
FieldSole PropLLCPartnershipCorpGov Entity
countryRequiredRequiredRequiredRequiredRequired
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).
RequiredRequiredRequiredRequiredRequired
Fields in the controller object
name.first_nameRequiredRequiredRequiredRequiredRequired
name.last_nameRequiredRequiredRequiredRequiredRequired
name.middleRequiredRequiredRequiredRequiredRequired
name.suffixOptionalOptionalOptionalOptionalOptional
name.prefixOptionalOptionalOptionalOptionalOptional
address.*
This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional
RequiredRequiredRequiredRequiredRequired
date_of_birth.*
This applies to all date of birth fields (day, month, year)
RequiredRequiredRequiredRequiredRequired
personal_country_
info.US.social_
security_number
RequiredRequiredRequiredRequiredRequired
phone.*
This applies to both phone fields (country code, phone number)
RequiredRequiredRequiredRequiredRequired
job_titleRequiredRequiredRequiredRequiredRequired
emailRequiredRequiredRequiredRequiredRequired
email_is_verifiedRequiredRequiredRequiredRequiredRequired
Fields in the account_controller object
name.first_nameN/ARequiredRequiredRequiredRequired
name.last_nameN/ARequiredRequiredRequiredRequired
name.middleN/AOptionalOptionalOptionalOptional
name.suffixN/AOptionalOptionalOptionalOptional
name.prefixN/AOptionalOptionalOptionalOptional
address.*
This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional
N/ARequiredRequiredRequiredRequired
phone.*
This applies to both phone fields (country code, phone number)
N/ARequiredRequiredRequiredRequired
job_titleN/ARequiredRequiredRequiredRequired
emailN/ARequiredRequiredRequiredRequired
email_is_verifiedN/ARequiredRequiredRequiredRequired
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/AOptionalOptionalOptionalN/A
is_beneficial_
owner
N/AOptionalOptionalOptionalN/A
address.*
This applies to all address fields (city, country, address line 1, region, postal code) except address line 2 which is optional
N/ARequiredRequiredRequiredN/A
date_of_birth.*
This applies to all date of birth fields (day, month, year)
N/ARequiredRequiredRequiredN/A
emailN/ARequiredRequiredRequiredN/A
email_is_verifiedN/ARequiredRequiredRequiredN/A
name.first_nameN/ARequiredRequiredRequiredRequired
name.last_nameN/ARequiredRequiredRequiredRequired
name.middleN/AOptionalOptionalOptionalN/A
name.suffixN/AOptionalOptionalOptionalN/A
name.prefixN/AOptionalOptionalOptionalN/A
personal_country_
info.US.social_
security_number
N/ARequiredRequiredRequiredN/A
phone.*
This applies to both phone fields (country code, phone number)
N/ARequiredRequiredRequiredN/A
job_titleN/AOptionalOptionalOptionalN/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
OptionalRequiredRequiredRequiredRequired
description
Business description
RequiredRequiredRequiredRequiredRequired
email
Business email
OptionalOptionalOptionalOptionalOptional
entity_nameRequiredRequiredRequiredRequiredRequired
phone.*
This applies to both phone fields (country code, phone number)
RequiredRequiredRequiredRequiredRequired
primary_url
If the merchant has a website, provide it here
OptionalOptionalOptionalOptionalOptional
Fields in the entity_country_info object
US.employer_
identification_
number
OptionalRequiredRequiredRequiredRequired
US.legal_formRequiredRequiredRequiredRequiredRequired
country_of_formationRequiredRequiredRequiredRequiredRequired
operates_in_
sanctioned_countries
RequiredRequiredRequiredRequiredRequired
year_of_formationRequiredRequiredRequiredRequiredRequired
Fields in the public_ownership object
Only applicable when public_ownership.is_publicly_traded is set to true
is_publicly_tradedN/ARequiredRequiredRequiredN/A
is_subsidiaryN/ARequiredRequiredRequiredN/A
parent_company_nameN/ARequiredRequiredRequiredN/A
traded_exchanges.
X.symbol
Provide the ticker symbol for each exchange the merchant is traded on
N/ARequiredRequiredRequiredN/A
Fields in the terms_of_service object
acceptance_timeRequiredRequiredRequiredRequiredRequired
original_ipRequiredRequiredRequiredRequiredRequired
terms_of_service_
version
OptionalOptionalOptionalOptionalOptional
Fields in the attestation object
attester_typeRequiredRequiredRequiredRequiredRequired
Fields in one of: attestation.additional_representative, attestation.controller, or attestation.other_representative objects
attester_timeRequiredRequiredRequiredRequiredRequired
original_ipRequiredRequiredRequiredRequiredRequired
representative_id
Only applicable to the additional representative option
RequiredRequiredRequiredRequiredRequired
name.*
Only applicable to the other representative option
RequiredRequiredRequiredRequiredRequired
job_title
Only applicable to the other representative option
RequiredRequiredRequiredRequiredRequired
Fields in the token object
id
This should be the token ID returned by the WePay JS when the token is created
RequiredRequiredRequiredRequiredRequired
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 JSConditionally required when tokenizing without the WePay JSConditionally required when tokenizing without the WePay JSConditionally required when tokenizing without the WePay JSConditionally 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 JSConditionally required when tokenizing without the WePay JSConditionally required when tokenizing without the WePay JSConditionally required when tokenizing without the WePay JSConditionally required when tokenizing without the WePay JS

The POST /legal_entities request should look something like this:

Copy
Copied
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.