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` object Only 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:

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.

Questions? Need help? Visit our support page!