Onboard Sub-Merchants

When you use Onboarding as a Service, you'll not only be able to register your sub-merchant's with Chase Merchant Services, but you'll also:

Allow your sub-merchants to onboard to the Amex OptBlue program
Receive MATCH screening results for each sub-merchant

Note

We now support ITINs (Individual Taxpayer Identification Number) in the social_security_number field.

Create A Legal Entity

The first step is to create a Legal Entity. A Legal Entity represents a single person (like a sole proprietor), business, or a non-profit. Think of a Legal Entity as the business itself, where various business and contact information is stored.

Remember:

The parameters listed here are the required parameters to onboard submerchants as a Payment Facilitator (PayFac). The API reference may indicate different requirements, but those requirements are the default, whereas PayFac requirements are enhanced.

To start, send a POST /legal_entities request to WePay like so:

Copy

Copied

curl -X POST \
  --url 'https://stage-api.wepay.com/legal_entities' \
  -H 'App-Id: {Your-App-Id}'\
  -H 'App-Token: {Your-App-Token}'\
  -H 'Accept: application/json'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
    "country": "US",
    "address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "123 Fake Street",
        "postal_code": "94101",
        "region": "CA"
    },
    "entity_name": "my business, LLC",
    "primary_url": "",
    "entity_country_info": {
      "country_of_formation": "US",
      "operates_in_sanctioned_countries": [],
      "year_of_formation": 1999,
      "US": {
        "employer_identification_number": "{EIN}",
        "legal_form": "limited_liability_company"
      }
    },
    "controller": { //provide either controller or account_controller depending on the entity type
        "address": {
            "city": "Beverly Hills",
            "country": "US",
            "line1": "456 Nocturn Alley",
            "postal_code": "90210",
            "region": "CA"
        },
        "date_of_birth": {
          "day": 1,
          "month": 1,
          "year": 1991
        },
        "email": "",
        "email_is_verified": true,
        "name": {
            "first": "Foo",
            "last": "Bar"
        },
        "personal_country_info": {
          "US": {
            "social_security_number": "{collect-controller-SSN}"
          }
        },
        "phone": {
          "country_code": "+1",
          "phone_number": "555 555 5555"
        },
        "job_title": "OWNER",
        "is_beneficial_owner": {bool}

    },
    "additional_representatives": { //provide up to 4 individuals who own 25% or more of the entity
      "representative_{X}": {

      }
    }
}'

The API response will contain a Legal Entity ID in the id parameter. Use that Legal Entity ID in calls to the /accounts* endpoint, described next. Here is an example of what the API response for POST /legal_entities may look like:

Copy

Copied

{
  "terms_of_service": {
    "acceptance_time": null,
    "original_ip": "{submitted-user-ip}"
    },
  "controller": {
    "is_beneficial_owner": true,
    "name": {
      "first": "Lorem",
      "last": "Ipsum"
      },
    "phone": {
      "country_code": "+1",
      "phone_number": "555 555 5555"
      },
    "address": {
      "city": "Paris",
      "country": "US",
      "line1": "456 Fake St",
      "postal_code": "90210",
      "region": "CA"
      },
    "email": "me@example.com",
    "email_is_verified": true,
    "personal_country_info": {
      "US": {
        "social_security_number_last_four_is_present": true,
        "social_security_number_is_present": true
        }
      },
    "job_title": "OWNER",
    "reference_id": "{custom-user-identifier-from-you}",
    "date_of_birth_is_present": true
    },
  "entity_name": "Lorem Ipsum",
  "phone": {
    "country_code": "+1",
    "phone_number": "555 555 5555"
    },
  "primary_url": "https://example.com",
  "description": null,
  "address": {
    "city": "Paradise",
    "country": "US",
    "line1": "123 Fake St",
    "postal_code": "90210",
    "region": "CA"
    },
  "entity_country_info": {
    "US": {
      "legal_form": "limited_liability_company",
      "employer_identification_number": "{EIN}"
      },
    "country_of_formation": "US",
    "operates_in_sanctioned_countries": null,
    "year_of_formation": 1871
    },
  "additional_representatives": null,
  "custom_data": null,
  "significant_donors": null,
  "significant_beneficiaries": {
    "entities": null,
    "geographies": null,
    "affiliations": null,
    "non_domestic_location_beneficiaries": null
    },
  "public_ownership": {
    "is_publicly_traded": false,
    "is_subsidiary": false,
    "parent_company_name": null,
    "primary_exchange": null,
    "traded_exchanges": {}
    },
  "email": "example@example.com",
  "reference_id": "{custom-reference-number}",
  "country": "US",
  "create_time": 1234567890,
  "id": "{WePay-generated-UUID}",
  "resource": "legal_entities",
  "path": "/legal_entities/{WePay-generated-UUID}",
  "owner": {
    "id": "{app-id}",
    "resource": "applications",
    "path": null
    },
  "api_version": "3.0"
}

Create A Merchant Account

Once you have a Legal Entity ID, you can move to the second step of creating an Account.

Think of the Accounts you'll be creating for your sub-merchants as an approximate representation of what your platform considers a normal Merchant Account. As a point of clarification, this step is creating an Account in the WePay system, not a Merchant Account with a bank. The Legal Entity is the API parent to the Account, and an Account can only have one parent Legal Entity.

Remember:

The parameters listed here are the required parameters to onboard submerchants as a PayFac. The API reference may indicate different requirements, but those requirements are the default, whereas PayFac requirements are enhanced.

Send a POST /accounts request to WePay like so:

Copy

Copied

curl -X POST \
  --url 'https://stage-api.wepay.com/accounts' \
  -H 'App-Id: {Your-App-Id}'\
  -H 'App-Token: {Your-App-Token}'\
  -H 'Accept: application/json'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
    “legal_entity_id”: “{ID-from-step-1}”,
    “name”: “Merchant-Name”,
    “description”: “Merchant Name's business”,
    "industry": {
		  "merchant_category_code": "Example MCC",
		  "category_detail": "Example Category"
	    },
    "statement_description": "Example Statement Description",
}'

The response will contain an Account ID in the id parameter.

Here is an example of what the API response may look like:

Copy

Copied

{
	"name": "Merchant-Name",
	"description": "Merchant Name's business",
	"industry": {
		"merchant_category_code": "Example MCC",
		"category_detail": "Example Category"
	},
	"reference_id": "Custom reference number",
	"statement_description": "Example Statement Description",
	"projected_monthly_transaction_volume": null,
	"incoming_payments": {
		"accepted_methods": ["payment_bank", "visa", "mastercard", "american_express", "discover", "jcb", "diners_club"]
	},
	"payout": {
		"default_currency": "USD",
		"currencies": {
			"USD": null
		}
	},
	"custom_data": null,
	"create_time": 1234567890,
	"balances": {
		"currencies": {}
	},
	"pricing": {
		"currencies": {
			"USD": {
				"credit_card": null,
				"payment_bank": null,
				"recurring_fee": null,
				"other_fees": {
					"debit_failure_fee": null
				}
			}
		}
	},
	"id": "{WePay-generated-UUID}",
	"resource": "accounts",
	"path": "/accounts/{WePay-generated-UUID}",
	"owner": {
		"id": "{WePay-generated-Legal-Entity-UUID}",
		"resource": "legal_entities",
		"path": "/legal_entities/{WePay-generated-Legal-Entity-UUID}"
	},
	"api_version": "3.0",
	"platform_onboarding_time": null,
	"beneficiary": {
		"id": "{WePay-generated-UUID}",
		"resource": "legal_entities",
		"path": "/legal_entities/{WePay-generated-UUID}"
	},
	"documents": []
}

Next to Connect Sub-Merchants to OptBlue

Questions? Need help? Visit our support page!