Onboard Merchants

 

Now that we’ve signed up for a platform account, can craft the skeleton of API requests, can use the Javascript to send risk information and create tokens, and have configured notification settings, it’s time to make your first API call. If you haven’t done these steps already, be sure to sign up, learn the basics, and set up your platform.

By completing this guide, you will have created a Legal Entity and an Account. These are crucial resources that allow you to define the merchant themselves, and details about their business. These resources form the foundation of all money movement, and lets WePay properly underwrite your Merchants.

Be sure to consider our Legal Certification guide to ensure that your onboarding flow is in compliance.


 

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.

Legal Entity API objects also store the personal verification information for the controller and additional representatives of the business/organization. A controller is an individual with significant responsibility to control or manage the Legal Entity (VP type role, or above, so you can use C-Suite roles). Additional representatives include:

  • Beneficial owners (individuals who own 25% or more of the business)
  • Auxiliary controllers

If a business/organization has beneficial owners, their personal verification is required.

Since some Legal Entity information can be considered PII, we recommend creating Legal Entities using Tokenization. Tokenization lets you avoid having to handle and process information like name, address, phone number, social security number in your own systems. In case you need a refresher, read about Tokenization here.

When creating a Legal Entity, it’s important to remember that you can collect this information as you go. To demonstrate this powerful use case, start by sending a POST to /legal_entities with just the country the legal entity is located in.

POST /legal_entities
{
    "country": "US"
}

This will return a legal_entity_id (be sure to keep this handy–you’ll likely want to store these IDs to your own user tables), as well as other information about that still needs filling. As you can see, we’ll need to fill out quite a bit of information. Let’s now capture this information using tokenization.

Note

Each time KYC information for Controller(s) or Beneficial Owner(s) is submitted to or edited in your platform, the following disclaimer must be displayed to the user:

By clicking “Submit,” you hereby certify, to the best of your knowledge, that the information provided above is complete and correct.

Note that variations of the text above can be used, so long as the variance does not significantly change the meaning.

Your UI must also provide the controller with a review of the details submitted by other entity beneficial owners. The date_of_brith and either social_security_number for US or social_insurance_number for Canada, should not be displayed. Instead use a GET /legal_entities/{id} call to retrieve the boolean values for date_of_birth_is_present and either social_security_number_is_present or social_insurance_number_is_present.

Invoke the Javascript SDK in your platform’s front-end after you’ve collected this information:

Note

If you are approved for a Server to Server Integration, please see our Server to Server version of Create a Legal Entity and then skip ahead to the next section in this article.

WePay.tokens.create({
	"resource": "legal_entities",
	"legal_entities": {
		"controller": {
			"email": "test1@test.com",
			"name": {
				"first": "foo",
				"middle": "t",
				"last": "bar"
			},
			"is_beneficial_owner": true,
			"email_is_verified": true
		},
		"terms_of_service": {
			"acceptance_time": 1551980186,   // Send real merchant TOS acceptance time
			"original_ip": "8.8.8.8"          // Send real merchant original IP
		}
	}
})

The above call showcases the minimum amount of information needed to enable payments for a Legal Entity. The call also assumes you’ve verified the merchant’s email on your platform. If you haven’t, it is your responsibility to do so, so mark email_is_verified as false until it’s completed.

The terms_of_service object represents when your merchant accepted the shared Terms of Service between your platform and WePay. The timestamp is represented as a Unix timestamp in seconds. The IP is the IP of the merchant when they agreed to the TOS. Note - you can pass the token object, which contains the IP address of the merchant, via the Javascript SDK. Read more here.

If the controller is not a beneficial owner, you would need to set is_beneficial_owner to false and define Additional Representatives. See the structure here, and be sure to identify a beneficial owner.

As a reminder, it is not necessary to collect all this information in one go. You can modify the structure above as you see fit, but this is the minimum required data to process payments for the merchant.

Executing this call with return a token, which will look something like this:

legal_entities-660420e3-ad2b-4ebe-914c-4a7b55d01dd4.

At this point, you can pass this token to your backend, and make a POST to the Legal Entity to finish filling it out.

POST /legal_entities/{id}
{
    "token": {
        "id": "legal_entities-660420e3-ad2b-4ebe-914c-4a7b55d01dd4"
    }
}

Now that you have a Legal Entity, you’ll need to create a merchant account in order to begin processing payments.


Create a Merchant Account

 

Now that we’ve created a Legal Entity, the next logical step is to create an Account, which ties back to a Legal Entity. Think of an Account as an approximate representation to what your platform would consider a merchant account. As a point of clarification, this is creating Merchant Account in the WePay system, not a Merchant Account with a bank. Logically, a Legal Entity is the parent of the Account, and an Account can have at most one Legal Entity.

First, let’s start by creating an Account using the Legal Entity ID from earlier.

POST /accounts
{
    "legal_entity_id": "98e4134b-b148-41ad-8079-71232a773d70"
}

Like the Legal Entities object, you’ll receive an Account with a little bit of information populated. There is, of course, more to populate. You’ll also notice payout and incoming_payments –let’s leave them blank for now, we’ll fill them out in the Payout Merchants section.

Let’s populate some important Account information. Start out by sending a POST similar to the one below:

POST /accounts/{id}
{
    "name": "Foo Account",
    "description": "This is Foo’s personal fundraising account",
    "statement_description": "Thanks for your donation to Foo's personal fundraising account"
}

Note

Be sure to include a useful value for the statement_description parameter. This value is what will show up on payer’s card/bank statements, and setting a clear, brief description will help them identify charges. When payers are able to identify charges on their statements, chargeback rates are reduced.

You’ll also want to be descriptive with the name and description of the Merchant’s account, as it’s possible for a single Legal Entity to be linked to multiple Accounts.


Fulfill Capabilities and Verifications

 

At this point, we have created a Legal Entity, an Account, and linked the two, and now Account capabilities and Legal Entity verifications must be fulfilled with the required information. Required information can vary depending on type of business (sole proprietor vs LLC vs corporation) and country, so we’ve provided an endpoint which tells you exactly what is needed for each resource:

Fulfilled capabilities and verifications are the gateways to merchants receiving Payments and Payouts, and the above endpoints are great sanity checks on WePay’s requirements for any given merchant.

Note

As you develop a UI for merchants to submit required legal entity and account information, reference our CIP and KYC Certification to ensure regulatory compliance.

Today, we support two capabilities that you must enable for Merchants: accepting payments from payers, and receiving payouts. This page will be updated with new capabilities rolled out in the future; refer back to it as necessary.

If you’ve followed this guide so far, you’ll notice certain information is still required when you send a GET /accounts/{id}/capabilities request. The response will show that payments are enabled, but payouts are not via the following parameters:

  • enabled: Indicates if the capability (payments or payouts) is enabled. This does not mean the account is permanently enabled, or that other information will not become a requirement in the future.
  • errant_fields: Shows a list of elements needed (or conditions that need to be met) to enable this capability, or to continue its enablement. This is not a list of everything that might ever be required; instead, the list shows missing elements required to immediately enable.
  • upcoming_issues: A date of upcoming issues, in a UNIX epoch timestamp.
  • current_issues: If applicable, this term provides further explanation of why a capability is not enabled.

Use this endpoint to identify the information that still needs to be provided by your merchants. In addition, make a call to the equivalent for Legal Entities: GET /legal_entities/{id}/verifications. This request will identify any additional documentation that WePay needs in order to properly verify a Legal Entity.

You must utilize the above endpoints to validate a Merchant collecting payment and receiving payouts. Depending on type of business and amount of payment collected, you will need to provide certain information about your Legal Entities and Accounts. If this information isn’t provided by the due date, WePay will return funds back to payers. We’ve outlined the requirements and deadlines for capabilities and verifications in the sections below:

Note: if you’d like to do a quick check of capabilities and verifications, you can use the query parameter is_expanded, and set it to false.

  • GET /accounts/{id}/capabilities?is_expanded=false
  • GET /legal_entities/{id}/verifications?is_expanded=false

This will return a response that simply shows verification and capability status, without the full details.

Enable Payments

 

To enable the payment capability for Merchants (a combination of Legal Entities + Accounts), you’ll need to provide certain information in a timely manner. As mentioned earlier, the API is designed to accept this information as you go, and it isn’t necessary to provide this information all at once. Find the required information to enable payments, categorized by deadline:

Click for immediate requirements to enable payments
Details Parameters
Controller's email address legal_entity.controller.email
Controller's name legal_entity.controller.name
Entity's country legal_entity.country
Merchant's TOS acceptance time legal_entity.terms_of_service.acceptance_time
The IP address from which the merchant accepted TOS legal_entity.terms_of_service.original_ip
The account name account.name
The account description account.description

If requirements are not met, your Legal Entity and Account will not be able to accept payments at all, and you will receive errors through the API.


Click for requirements due 14 days after 1st payment, or $100,000 USD, whichever comes first
To continue accepting payments, you must provide the following information, regardless of Entity Type:
Details Parameters
The controller must verify their email address. legal_entity.controller.email_is_verified
Note: it is your responsibility, as the platform, to verify the email address provided to you from the Legal Entity.

Deadline

If requirements are not met by 14 days after first payment, or $100,000 USD, WePay will disable incoming payments for the Legal Entity and Account. After 30 days total (16 days after the original 14 days), WePay will refund payments to payers and close the account.


Click for requirements due 30 days after 1st payment
The merchant will need to provide additional information (if not already provided) depending on the type of Legal Entity in order to keep payments enabled:
Individual
Details Parameters
Country-specific legal entity type
  • legal_entity.entity_country_info.us.legal_form
  • legal_entity.entity_country_info.ca.legal_form

NOTE: The value here should be individual
The controller's personal address legal_entity.controller.address
The controller's personal phone number legal_entity.controller.phone
The controller's date of birth legal_entity.controller.date_of_birth
The individual's country-specific identification number
  • legal_entity.controller.personal_country_info.us.social_security_number
  • legal_entity.controller.personal_country_info.ca.social_insurance_number
Whether the controller is a beneficial owner (owns 25% or more of the entity) legal_entity.controller.is_beneficial_owner

NOTE: The value here should be true, and there should not be other beneficial owners.

Sole Proprietor
Details Parameters
Country-specific legal entity type
  • legal_entity.entity_country_info.us.legal_form
  • legal_entity.entity_country_info.ca.legal_form
NOTE: The value here should be sole_proprietor
Country-specific entity identification number
  • legal_entity.entity_country_info.us.employer_identification_number
  • legal_entity.entity_country_info.ca.business_number
The entity description legal_entity.description
The entity's phone number legal_entity.phone
The entity's primary web-presence legal_entity.primary_url
The entity name legal_entity.entity_name
The controller's personal address legal_entity.controller.address
The controller's personal phone number legal_entity.controller.phone
The controller's date of birth legal_entity.controller.date_of_birth
The controller's country-specific identification number
  • legal_entity.controller.personal_country_info.us.social_security_number
  • legal_entity.controller.personal_country_info.ca.social_insurance_number
Whether the controller is a beneficial owner (owns 25% or more of the entity) legal_entity.controller.is_beneficial_owner
Additional representatives who are beneficial owners (own 25% or more of the entity)
  • legal_entity.additional_representatives.representative_X.name
  • legal_entity.additional_representatives.representative_X.address
  • legal_entity.additional_representatives.representative_X.phone
  • legal_entity.additional_representatives.representative_X.date_of_birth
  • legal_entity.additional_representatives.representative_X.personal_country_info.US.social_security_number
  • legal_entity.additional_representatives.representative_X.personal_country_info.CA.social_insurance_number

Corporation, Limited Liability Company, Non-Profit, or Partnership
Details Parameters
Country-specific legal entity type
  • legal_entity.entity_country_info.us.legal_form
  • legal_entity.entity_country_info.ca.legal_form
Country-specific entity identification number
  • legal_entity.country_info.us.employer_identification_number
  • legal_entity.country_info.ca.business number
The entity description legal_entity.description
The entity's phone number legal_entity.phone
The entity's primary web-presence legal_entity.primary_url
The entity name legal_entity.entity_name
The controller's personal physical address legal_entity.controller.address
The controller's personal phone number legal_entity.controller.phone
The controller's date of birth legal_entity.controller.date_of_birth
The controller's country-specific identification number
  • legal_entity.controller.country_info.us.social_security_number
  • legal_entity.controller.country_info.ca.social_insurance_number
Whether the controller is a beneficial owner (owns 25% or more of the entity) legal_entity.controller.is_beneficial_owner
Additional representatives who are beneficial owners (own 25% or more of the entity)

*Not required for Non-Profits upon status verification
  • legal_entity.additional_representatives.representative_X.name
  • legal_entity.additional_representatives.representative_X.address
  • legal_entity.additional_representatives.representative_X.phone
  • legal_entity.additional_representatives.representative_X.date_of_birth
  • legal_entity.additional_representatives.representative_X.personal_country_info.US.social_security_number
  • legal_entity.additional_representatives.representative_X.personal_country_info.CA.social_insurance_number

Deadline

If the necessary information has not been provided 30 days after first payment, Payments will become disabled on the account. If the information has still not been provided 60 days after first payment (30 days after payments are disabled), then WePay will refund payments to payers and close the account.


Enable Payouts

 

To enable the payouts capability for an account, required information must be provided at the time you wish to enable payouts. Requirements to enable payouts are:

1. All enabled payment requirements

All required information for enabled payments must be provided to enable payouts. There isn’t a trailing time component as with enabling payments, so any missing information must be submitted at the time you want payouts enabled, even if the deadline has not been reached.

2. Payout requirements

In addition to meeting all requirements for enabled payments, merchants must submit the following information:

Click for requirements to enable payouts
Details Parameters
Legal entity address legal_entity.address
Controller's job title legal_entity.controller.job_title
Set a payout method
  • account.payout.currencies.usd.payout_method_id
  • account.payout.currencies.cad.payout_method_id
Define a payout frequency
  • account.payout.currencies.usd.period
  • account.payout.currencies.cad.period

Find walk-throughs for creating and attaching payout methods in the Payout Merchants article.

Deadline

If payouts have not been enabled 30 days after first payment, then incoming payments will be disabled on the account. If payouts have still not been enabled 60 days after first payment (30 days after disabled payments), then WePay will issue refunds to the payers and close the account.


Upload Verifications

 

If WePay is unable to verify the merchant based on the information supplied, the merchant must provide supporting documentation. To find out which documents must be provided, subscribe to the legal_entities.verifications.updated notifications event topic. Then you’ll call GET /legal_entities/{id}/verifications if you receive a notification and examine the following parameters:

  • additional_representatives.representative_X.current_issues.additional_documents_required
  • controller.personal_verification.current_issues.additional_documents_required
  • entity_verification.current_issues.additional_documents_required

Please also see the list of acceptable documentation to inform the user interface you provide for your merchants.

Once the merchant has supplied the required documentation, use the WePay document upload JavaScript to generate document IDs. Submit the document IDs in a POST /legal_entities/{id}/verifications in the appropriate parameter to upload the documents for WePay to review.

Deadline

If documents have not been submitted 30 days after WePay requested, then incoming payments will be disabled on the account. If documents have still not been provided 60 days after they were requested (30 days after disabled payments), then WePay will issue refunds to the payers and close the account.


Set Notifications for Merchant Onboarding

 

Notifications are WePay’s way of communicating important status information with your platform in real time. The table below shows use cases where you must send communication to your merchants, once you receive a notification from WePay.

Use Case Topic What To Do
A merchant begins onboarding, but additional steps are required for them to finish onboardung. accounts.created Send automated onboarding reminders to the merchant according to required onboarding items per GET /accounts{id}/capabilities and GET /legal_entities/{id}/verifications API responses.
A merchant’s account capabilities have been disabled because of risk, fraud, or compliance violations. accounts.capabilities.updated Send a GET to the accounts/{id}/capabilities endpoint.
Legal entity information must be updated legal_entities.verifications.updated WePay / Platform has raised an issue with the Legal Entity information. Merchant must provide new KYC information.
A merchant’s payout method has been invalidated due to excessive failed payout attempts. accounts.capabilities.updated When the payouts.enabled parameter on a GET /accounts{id}/capabilities call returns as false and the value was previously true, notify the merchant.
Documents Required legal_entities.verifications.updated Merchant must provide documentation for the entity, controller, or additional representatives.
A beneficial owner of the account updated some of their personal verification details, requiring verification again. legal_entities.verifications.updated Notify the merchant that information has been updated.

 

For a full list of notifications to set for your platform and users, please visit the Platform Setup article.


We’ve set up the groundwork for merchant onboarding. Now, let’s create and execute our first payment. Questions? Need help? Visit our support page!