Onboard Merchants

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

Identify the Controller

When onboarding a merchant to your platform, ask them to verify 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. We will ask for the controller's personal information, as well as details about the business, in order to understand and underwrite the merchant.

Learn more about the definition and KYC requirements for a controller here.
Note

Confirm that the defined controller is the actual controller of the organization since they will be required to provide their own personal KYC as the controller during onboarding.

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 request will return null, false or {} in the response
Copy
Copied
{
  "terms_of_service": {
    "acceptance_time": null,
    "original_ip": null
  },
  "controller": {
    "is_beneficial_owner": null,
    "name": null,
    "phone": null,
    "address": null,
    "email": "person@place.com",
    "email_is_verified": false,
    "personal_country_info": {
      "US": {
        "social_security_number_last_four_is_present": false,
        "social_security_number_is_present": false
      }
    },
    "job_title": null,
    "date_of_birth_is_present": false
  },
  "entity_name": null,
  "phone": null,
  "primary_url": null,
  "preferred_locale": null,
  "description": null,
  "address": null,
  "entity_country_info": {
    "US": {
      "legal_form": null,
      "employer_identification_number": null
    },
    "country_of_formation": null,
    "operates_in_sanctioned_countries": null,
    "year_of_formation": null
  },
  "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": {}
  },
  "country": "US",
  "create_time": 1657056408,
  "id": "250953e7-3475-477a-8294-b4e533b43b3d",
  "resource": "legal_entities",
  "path": "/legal_entities/250953e7-3475-477a-8294-b4e533b43b3d",
  "owner": {
    "id": "544926",
    "resource": "applications",
    "path": null
  },
  "api_version": "3.0"
}

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.

object

To help your merchants avoid the current issue with KYC forms being required to begin processing payments, you can collect and send their Merchant Category Code (MCC) via the API.

merchant_category_code
string

Keep in mind that this value must be accurate to the best of your and your user's knowledge.

JSONJava SDK
Copy
Copied
{
  "legal_entity_id": "id-from-step-above",
  "name": "Test Merchant Account Name",
  "description": "This is the account name description",
  "industry": {
    "merchant_category_code": "This is the category code associated with the merchant's industry"
  }
}
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.
Note

There is currently a soft limit of 6 accounts per Legal Entity.


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 legal_entity_id of the merchant being added to the Merchant Center.This will send an email to the controller via our 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 to accept our Privacy Policy & Terms of Service. This email will also contain a link to verify their email, which merchants will need to do before their payments are enabled. 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 we close the Account and issue refunds for any and all payments made up to that point.

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

Submit KYC and Settlement

In the WePay Merchant Center, merchants must complete Know Your Customer (KYC) and submit their Merchant Category Code (MCC) in order to begin processing payments.

After submitting the KYC, merchants should provide a Settlement bank account in the Merchant Center.

Check out the How Payouts Work Payments 101 article for more information about how your merchant will receive their funds.
Note
The Merchant Category Code (MCC) is immediately required to process payments.

We will soon decouple the MCC field from the KYC form so that the merchant does not need to complete the KYC before providing the MCC.

Invite Other Users

After the KYC & settlement are completed, 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

Connect Merchant Center to Your User Interface

To make it easy for users to access the WePay Merchant Center from the partner-owned merchant dashboard, you can embed an easy button into your user interface (UI). To implement, be sure to reference the URL https://www.wepay.com/login on your equivalent to the Transaction element below.

The UI could look something like this in your navigation bar:

You can adjust the color and design of this button based on the existing design of your dashboard.



Offboard Merchants

Prerequisites
  • Access to the DELETE /accounts/id endpoint from our 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 us a DELETE /accounts/id request.
  3. Build logic checks in to your system which will stop any Payment API requests to deleted Accounts.
For deleting accounts with terminals, partners will need to first offboard terminals associated with the merchant after which they can delete the account. An ACCOUNT_CANNOT_BE_DELETED error is shown when a delete is attempted on an ineligible account (i.e. a merchant with a non-zero balance). An account without balances or pending transactions look like this:
Copy
Copied
{
  "name": null,
  "description": null,
  "industry": {
    "merchant_category_code": null,
    "category_detail": null
  },
  "reference_id": null,
  "statement_description": null,
  "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": 1643046427,
  "pricing": {
    "currencies": {
      "USD": {
        "credit_card": null,
        "payment_bank": null,
        "recurring_fee": null,
        "other_fees": {
          "debit_failure_fee": null
        }
      }
    }
  },
  "balances": {
    "currencies": {
      "CAD": {
        "balance": 0,
        "incoming_pending": 0,
        "outgoing_pending": 0,
        "reserve": 0
      },
      "USD": {
        "balance": 0,
        "incoming_pending": 0,
        "outgoing_pending": 0,
        "reserve": 0
      }
    }
  },
  "id": "44a84-aa80-436e-8ef3-25808cdf3a00",
  "resource": "accounts",
  "path": "/accounts/44a84-aa80-436e-8ef3-25808cdf3a00",
  "owner": {
    "id": "dab2-4cda-48a9-b63c-6961d1488d15",
    "resource": "legal_entities",
    "path": "/legal_entities/dab2-4cda-48a9-b63c-6961d1488d15"
  },
  "api_version": "3.0",
  "platform_onboarding_time": null,
  "beneficiary": {
    "id": "dab2-4cda-48a9-b63c-6961d1488d15",
    "resource": "legal_entities",
    "path": "/legal_entities/dab2-4cda-48a9-b63c-6961d1488d15"
  },
  "documents": []
}
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 our 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 us 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, we may be unable to deliver Payouts to an Account's Payout Method. When this edge case comes up, we will send a payout_methods.deleted API Notification, so be sure to subscribe to that event 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 keep merchants' WePay Account balances whole.

When a negative balance occurs (e.g., due to a refund) 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, we will need to make an Adjustment to a merchant's Account. Common scenarios which call for Adjustments include:

  • Resolve a negative balance by payment from merchant
  • 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 our records. Since Adjustments originate on our end, be sure to subscribe to the adjustments.created Notification topic.