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

WePay does not currently support iTINs (any value in a social security number field starting with a 9).

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

Use your own unique ID that already exists your data to represent this sub-merchant as a reference ID when creating their WePay Account.

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”,
    “reference_id”: {“your-merchant-id}”,
    "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": []
}
### Certify Integration 

<table class="no-word-break">
  <thead>
    <tr>
      <th>Item</th>
      <th>Details</th>
    </tr>
  </thead>
  <body>
    <tr>
      <td><a href="#create-a-legal-entity">Legal Entity API</a></td>
      <td><ol><li>Submerchant data is passed successfully and received by WePay</li></ol></td>
    </tr>
    <tr>
      <td><a href="#onboard-sub-merchants-to-optblue">AmEx OptBlue onboarding</a></td>
      <td>
        <ol>
          <li>Amex OptBlue opt-in turned on in the POST /accounts API request</li>
          <li>Updated GSFM file on successful AmEx OptBlue onboarding</li>
        </ol>
      </td>
    </tr>
    <tr>
      <td><a href="#onboard-sub-merchants-to-optblue">AmEx OptBlue marketing opt-in</a></td>
      <td><ol><li>Opt submerchants in on the POST /accounts API request</li></ol></td>
    </tr>
    <tr>
      <td><a href="#use-seller-ids-and-numbers">AmEx OptBlue offboarding</a></td>
      <td>
        <ol>
          <li>Account API updated to turn off Amex OptBlue</li>
          <li>Updated GSFM file with Merchant/Seller ID removed on a success</li>
        </ol>
      </td>
    </tr>
    <tr>
      <td><a href="#handle-optblue-response-files">Amex OptBlue daily batch file</a></td>
      <td>
        <ol>
          <li>Provide SMTP address</li>
          <li>Successful delivery and receipt of batch file</li>
        </ol>
      </td>
    </tr>
    <tr>
      <td><a href="#handle-match-results">Manual MATCH process</a></td>
      <td>
        <ol>
          <li>Test email from WePay email alias to PayFac email alias mocking a MATCH positive hit on a submerchant</li>
          <li>Email response from PayFac email alias to WePay email alias indicating that the merchant is closed on the PayFac system</li>
        </ol>
      </td>
    </tr>
  </body>
</table>

Certify Integration

ItemDetails
Legal Entity API
  1. Submerchant data is passed successfully and received by WePay
AmEx OptBlue onboarding
  1. Amex OptBlue opt-in turned on in the POST /accounts API request
  2. Updated GSFM file on successful AmEx OptBlue onboarding
AmEx OptBlue marketing opt-in
  1. Opt submerchants in on the POST /accounts API request
AmEx OptBlue offboarding
  1. Account API updated to turn off Amex OptBlue
  2. Updated GSFM file with Merchant/Seller ID removed on a success
Amex OptBlue daily batch file
  1. Provide SMTP address
  2. Successful delivery and receipt of batch file
Manual MATCH process
  1. Test email from WePay email alias to PayFac email alias mocking a MATCH positive hit on a submerchant
  2. Email response from PayFac email alias to WePay email alias indicating that the merchant is closed on the PayFac system