Onboard Merchants

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.

Create A Legal Entity

{
  "country": "US",
  "controller": {
    "email": "test@test.com"
  }
}

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());
  }

{
  "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

{
  "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"
  }
}

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());
  }

Invite The Controller

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

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.

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

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

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.

{
  "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": []
}

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

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

Handle Recoveries

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:

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