Onboard Merchants

 

Prerequisites
  • WePay API keys for the stage environment (find these in the test section of the Partner Center)
  • API Notification subsriptions:
    • legal_entities.created
    • accounts_created

Identify the Controller

When onboarding a merchant to your platform, ask them to understand who a controller is in their business. A controller is defined as an individual with significant responsibility to control or manage the Legal Entity (VP type roles, or above, so you can use C-Suite roles and founders).

Once a merchant has an idea of who is responsible for filling out such information, they will need that person's email address handy. WePay will ask for the Controller's personal information, as well as details about the business, in order to understand and underwrite the merchant.

Create A Legal Entity

After a controller has been identified, you'll create a Legal Entity by making a POST /legal_entities request. The minimum required information to get a successful API response is simply the country parameter. That said, the minimum required information to onboard a merchant is as follows:

*/}
jsonJava SDK
Copy
Copied
{
  "country": "US",
  "controller": {
    "email": "test@test.com"
  }
}
Copy
Copied
try {
  LegalEntitiesCreateData createData = new LegalEntitiesCreateData();
  createData.setCountryCode(CountryEnum.US);
  ControllerReq controllerReq = new ControllerReq();
  controllerReq.setEmailNullable("example@example.com");
  createData.setControllerReq(controllerReq);
  LegalEntity createResult = LegalEntitiesApi.create(createData);
  LOGGER.log(Level.INFO, String.format("Successfully created a legal entity."));
  }
catch (Exception e) {
  LOGGER.log(Level.WARNING, e.getMessage());
  }
Canadian Merchants

To onboard merchants based in Canada, be sure to review the Merchant Location and Currency Payments 101 article.

The API response will, at minimum, contain a Legal Entity ID on the id parameter. For any properties which were left as null in your


Create An Account

Prerequisites

Use the Legal Entity ID from the previous step to create an Account resource by sending a POST /accounts request. The Account will contain some business details, but will mostly serve as the owner resource for the transactions of this merchant. The minimum required information to create an Account is simply the legal_entity_id parameter. That said, the minimum required information to onboard a merchant is as follows:

legal_entity_id
required
string

The id returned by the API from the POST /legal_entities endpoint.

name
required
string

A human-readable name for the Account. The merchant should be able to define this.

description
required
string

A human-readable description of the Account. The merchant should be able to define this.

JSONJava SDK
Copy
Copied
{
  "legal_entity_id": "id-from-step-above",
  "name": "Test Merchant Account Name",
  "description": "This is the account name description"
}
Copy
Copied
try {
  AccountsCreateData accountsCreateData = new AccountsCreateData();
  accountsCreateData.setLegalEntityId(<Legal Entity ID>);
  accountsCreateData.setDescription(<Description>);
  accountsCreateData.setName(<Name>);
  Account createResult = AccountsApi.create(accountsCreateData);
  LOGGER.log(Level.INFO, String.format("Successfully create an account %s"));
  } 

catch (Exception var4) {
  LOGGER.log(Level.WARNING, var4.getMessage());
  }

The Account ID will be returned on the id parameter.


Invite The Controller

Prerequisites

Now that your merchant is represented in the API, you can invite the controller to the WePay Merchant Center by sending a POST /legal_entities/id/set_controller_password request.

The request does not take any body parameters, so your request will only contain the following details:

Loading...

The {id} parameter is the id of the merchant being added to the Merchant Center.

This will send an email to the controller via WePay's email system. The email will contain the branding and colors that you've set via the Partner Center, and will provide a link to for the merchant to the WePay Merchant Center. Have the controller click the call-to-action in the email to set a password and accept the WePay Privacy Policy & Terms of Service.

Users should bookmark the URL in the email to return to the WePay Merchant Center.

Submit KYC and Settlement

In the WePay Merchant Center, the controller must submit Know Your Customer (KYC) and payout (i.e. bank account) information. The recommendation is for KYC and payout details to be submitted and in a verified state prior to processing payments. That said, this information is not required from the merchant until the first payment has been processed, at which point the merchant will have 14 calendar days to submit information before they will be disabled from accepting payments. After disablement, the merchant will have 30 days to submit the information before WePay closes the Account and issues refunds for any and all payments made up to that point.

Check out the How Payouts Work Payments 101 article for more information about how your merchant will receive their funds.

Invite Other Users

After KYC & settlement are finished, the controller will likely want to invite various users to the Merchant Center. The following functions can be achieved through Merchant Center, so instruct controllers to send invites to others in the controller's organization for the following roles:

  • Reporting & Reconciliation for the organization
  • Tier 1 Merchant Support
  • Tier 1 Payer Support

Offboard Merchants

Prerequisites
  • Access to the DELETE /accounts/id endpoint from your WePay team

Merchants may want to close their account on your platform, which should be accomplished through a self-serve, merchant-facing UI. When a merchant's account is closed on your platform, you must also ensure that the associated WePay Account is deleted.

To ensure that a WePay Account is deleted, you can do the following:

  1. Check that all balances are 0.
  2. Send a DELETE /accounts/id request to WePay.
  3. Build logic checks in to your system which will stop any Payment API requests to deleted Accounts.

Delete functionality is currently not supported for accounts with terminals, therefore this endpoint is not intended for use with our Card Present offerings.

An ACCOUNT_CANNOT_BE_DELETED error is thrown when delete is attempted on an ineligible account (i.e. a merchant who uses Card Present Terminals or with a non-zero balance). An account without balances or pending transactions look like this:

Once DELETE /accounts/id is called, all capabilities are disabled for that particular account and an accounts.deleted notification is published. Be sure to subscribe to the accounts.deleted notification topic.

If an account has been deleted in error, please contact WePay support.

Note

The lookup on a deleted account is the same as that on an active account. If trying to determine the status of the account, be sure to use issue_type: account_deleted on GET /accounts/id/capabilities.


Handle Payouts

Merchants will submit their bank account details and payout frequency preference directly to WePay from the Merchant Center. They will also manage their settings here, like adding a new bank account or updating their payout frequency. Additionally, merchants will be able to view their transaction and payout history.

Merchants can access the Merchant Center via the link in the invitation email, which they should have bookmarked.

Handle Invalid Payout Methods

Occasionally, WePay may be unable to deliver Payouts to an Account's Payout Method. When this edge case comes up, WePay will send a payout_methods.deleted API Notification, so be sure to subscribe to that even topic.

After an invalid Payout Method gets deleted, the Accounts payouts Capability will become disabled until they add a new Payout Method.


Handle Recoveries

Recoveries are the mechanism by which merchants' WePay Account balances are kept whole.

When a negative balance occurs (due to a refund, for example) and any incoming payments do not bring the balance to a minimum of $0.00, a Recovery will pull the amount needed to reach $0.00 from the merchant's active Payout Method.

Recoveries begin on the business day following the negative balance. This gives time for incoming payments to resolve the negative balance. For example, if a refund is issued on Monday, 10/22 and brings the balance negative, and if the balance is still negative on Tuesday, 10/23, then a Recovery will begin on 10/23.

Below are a few scenarios dealing with Recoveries:

Balance on Monday, 10/22Event(s) on 10/22New BalanceRecovery on Tuesday, 10/23
$0.00Refund for $25.00-$25.00$25.00
-$25.00Payment for $100.00$75.00N/A
$25.00
  • Dispute for $100.00
  • Payment for $25.00
-$25.00$25.00

Remember to subscribe to the recoveries.created Notification event topic in order to be notified when a Recovery occurs.


Handle Adjustments

On occasion, WePay will need to make an Adjustment to a merchant's Account. Common scenarios which call for Adjustments include:

  • Received payment from merchant to resolve a negative balance
  • Resolve miscalculation of fees
  • Resolve appeasements

We've listed Adjustment API reason codes to clearly identify each individual Adjustment.

Tracking Adjustments is important to keep your platform's account history consistent with WePay records. Since Adjustments originate on WePay's end, be sure to subscribe to the adjustments.created Notification topic.