Enable Merchants

At this point we have created a Legal Entity and an Account to represent your user with enough information to begin processing Payments. The remaining required information can be submitted in a progressive fashion, allowing your users time to collect the details. To complete progressive onboarding, Account capabilities will be enabled by fulfilling Legal Entity verifications.

If you selected pre-built components to onboard merchants, then your users will complete this process through the WePay-hosted merchant center. If you selected custom components to onboard merchants, then you can choose between the KYC iFrame and custom components.

Required information to enable merchants depends on the type of business (sole proprietor vs LLC vs corporation) and country, so we've provided an endpoint which allows you to look up exactly what is needed for each resource:

• GET /accounts/{id}/capabilities
• GET /legal_entities/{id}/verifications

As part of the integration, you'll be required to certify both the legal and KYC aspects of onboarding merchants. Once you're finished building, read through the following docs to ensure compliance:

• Legal Certification
• CIP & KYC Certification

Interface with Capabilities and Verifications

Capabilities

Today, we support two capabilities that you must enable for merchants: accepting Payments and receiving Payouts of funds to their bank account. Note that there is also a Terminals capability, only applicable to platforms leveraging the Card Present solution.

• enabled: A boolean indication of whether the capability is enabled. Note that a true response does not mean the account is permanently enabled, or that other information will not become a requirement in the future.
• upcoming_issues: A UNIX epoch timestamp of when upcoming issues must be fulfilled to avoid enablement becoming false.
• current_issues: If applicable, this 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.

• 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:

{
  "payments": {
    "enabled": true
  },
  "payouts": {
    "enabled": false
  },
  "terminals": {
    "enabled": false
  },
  "id": null,
  "resource": "capabilities",
  "path": "/accounts/{id}/capabilities",
  "owner": {
    "id": "id",
    "resource": "accounts",
    "path": "/accounts/{id}"
  },
  "api_version": "3.0"
}

Provide Required Details for Enablement

The scope of required details to enable merchants involves three areas of the API:

1. Enable payments on the capabilities endpoint
2. Enable payouts on the capabilities endpoint
3. Verify merchants on the verifications endpoint

If merchants do not provide any given piece required information by the deadline (outlined below), then capabilities will be disabled. If merchants still do not provide the missing required information by the second deadline, then any balance will be refunded to payers and the account will be closed.

Enable Payments

To enable the Payment capability for merchants, you'll need to provide certain information about the Legal Entity and Account in a timely manner (specific deadlines are defined below). The API is designed to accept this information as you go, and it isn't necessary to provide this information all at once.

Upfront Underwriting

Upfront underwriting is the process by which WePay evaluates the potential risk exposure of a business by gathering additional information from the merchant to calculate and predict the chargeback rate, refund rate, and non-delivery risk of goods and services in addition to calculating our dollar value of credit exposure. This is an upfront assessment of our risk exposure before enabling payment and payout capabilities. Underwriting only occurs once. After a merchant is underwritten, any updates will not result in another underwriting. Payment processing capabilities will default to disabled until upfront underwriting is complete.

To learn more, please contact your integration team or technical account manager for more information.

Enable Payouts

The Payouts capability allows merchants to send funds they have collected over to their linked bank account Payout Method.

Just like the Payments capability, there is required information which must be submitted to enable the Payouts capability for an Account. Some of these requirements are immediate, and some allow progressive submission with a deadline.

Once all requirements for the Payouts capability are met, a Payout will automatically be sent out to the Payout Method. Future Payouts will follow the defined Payout frequency.

Verify Merchants

The following verification flows should be built out in order to satisfy any additional requests for information, but they will not be applicable to all merchants. If/when one of these flows does become applicable to a merchant, deadlines for completing requested action items will be applicable, and will result in the Account being refunded if not completed on time. Be sure to code for the following flows:

1. Resubmit Information
2. Upload Verifications and Outreaches
3. Verify High Volume NGOs and Charities
4. Update Personal Information

Resubmit Information

Verifications Errant Field Current Issue Reasons

Upload Verifications and Outreaches

• complete Legal Entity Verifications
• enhance Account fraud protection

To get specifics on what type(s) of documents are required, work with your integration team or technical account manager who can configure your WePay app to use the method described below:

• issue_type.identity_verification (Legal Entity Verifications)
• issue_type.risk_outreach (Account fraud protection)

Example payload:

{
  "id": "{notification-id}",
  "resource": "notifications",
  "path": "/notifications/{id}",
  "owner": {
    "id": "{app-id}",
    "resource": "applications",
    "path": null
  },
  "topic": "legal_entities.verifications.updated",
  "event_time": 1601937976,
  "payload": {
    "entity_verification": {
      "verified": false,
      "current_issues": [
        {
          "target": {
            "resource": "verifications",
            "id": null,
            "path": "/legal_entities/{id}/verifications"
          },
          "issue_type": "identity_verification",
          "identity_verification": {
            "message": "We need to verify your name.",
            "requested_documents": [
              "certified_copy_of_court_order"
              ],
            "path": "entity_verification.documents"
          }
        }
      ],
      "documents": []
    },
    "controller": {
      "personal_verification": {
        "verified": false,
        "current_issues": [
          {
            "target": {
              "resource": "legal_entities",
              "id": "{legal_entities-id}",
              "path": "/legal_entities/{id}"
            },
            "issue_type": "risk_outreach",
            "risk_outreach": {
              "message": null,
              "requested_documents": [
                "passport"
                ],
              "path": "controller.personal_verification.documents"
            }
          }
        ],
        "documents": []
      }
    },
    "additional_representatives": {
      "representative_0": {
        "personal_verification": {
          "verified": true
        }
      }
    },
    "id": null,
    "resource": "verifications",
    "path": "/legal_entities/{id}/verifications",
    "owner": {
      "id": "{legal_entities-id}",
      "resource": "legal_entities",
      "path": "/legal_entities/{id}"
    },
    "api_version": "3.0"
  },
  "api_version": "3.0"
}

Note that it is possible for Legal Entity Verifications and Account fraud protection documentation to be required simultaneously from a merchant. Additionally, it is possible for multiple documents to be required from the controller, the entity, or an additional representative.

The code for your UI could function something like this:

<body>
  <h2 style="font-family: Arial; color: slategray">KYC Document Upload</h2>
  <select style="color: #4B4746" id="ddlContType">
    <option style="color: #4B4746">-- Select --</option>
    <option style="color: #4B4746" id="input1" value="affiliation">affiliation</option>
    <option style="color: #4B4746" id="input2" value="bankruptcy_trustee">bankruptcy_trustee</option>
    <option style="color: #4B4746" id="input3" value="certificate_of_association">certificate_of_association</option>
    <option style="color: #4B4746" id="input4" value="companies_house">companies_house</option>
    <option style="color: #4B4746" id="input5" value="current_local_tax_bill">current_local_tax_bill</option>
    <option style="color: #4B4746" id="input6" value="electoral_register_entry">electoral_register_entry</option>
    <option style="color: #4B4746" id="input7" value="evidence_of_authority">evidence_of_authority</option>
    <option style="color: #4B4746" id="input8" value="evidence_of_name_change">evidence_of_name_change</option>
    <option style="color: #4B4746" id="input9" value="filed_audited_accounts">filed_audited_accounts</option>
    <option style="color: #4B4746" id="input10" value="insurance_bill">insurance_bill</option>
    <option style="color: #4B4746" id="input11" value="marriage_certificate">marriage_certificate</option>
    <option style="color: #4B4746" id="input12" value="partnership_agreement">partnership_agreement</option>
    <option style="color: #4B4746" id="input13" value="secretary_of_state">secretary_of_state</option>
    <option style="color: #4B4746" id="input14" value="vehicle_registration">vehicle_registration</option>
  </select>
  <input style="color: #4B4746" type="file" id="filegoeshere">
  <br><br>
  <button style="color: #4B4746" onclick="submit()">Submit</button>
  <div id="token"></div>
  <script src="https://cdn.wepay.com/wepay.min.js"></script>
</body>

var app_id = "{your-app-id}"; // your platform's app ID
var legal_entity_id = "{legal-entity-id}"; // Get this from user's login
var environment = "stage";
var api_version = "3.0";
WePay.configure(environment, app_id, api_version);
var error = WePay.configure("stage", app_id, api_version);
if (error) {
  console.log(error);
}

function submit() {
  var inputs = document.getElementById("filegoeshere");
  if (inputs.files !== undefined && inputs.files.length > 0) {
    var file = inputs.files[0];
  }

  var options = document.getElementById("ddlContType");
  {
    var type = options.value;
  }

  var body = {
    type: type,
    legal_entity_id: legal_entity_id,
    file: file
  };

  var headers = {};

  var node = document.createElement("div");
  var resp = WePay.documents.create(body, headers, function (response) {
    node.innerHTML = JSON.stringify(response);
    document.getElementById("token").appendChild(node);
  });
}

curl -X POST \
  --url 'https://api.wepay.com/legal_entities/{id}/verifications' \
  -H 'Accept: application/json'\
  -H 'App-Id: {app-id}'\
  -H 'App-Token: {app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "controller": {
    "personal_verification": {
      "documents": [
        "{document-id}"
      ]
    }
  }
}'

Building out the UI and back end to upload documents is vital to ensuring a seamless progressive onboarding experience for your merchants. If we require additional documentation in order to verify a merchant for continued processing, an easy-to-navigate method for merchants to provide the needed documents expedites the process.

Verify High Volume NGOs and Charities

1. first_trigger: Account has processed $500,000.00 in a rolling 12-month window. Platform to email merchant, providing context for additional verification, and allow them to submit information.
2. second_trigger: Account has processed $1,000,000.00 in a rolling 12-month window. Platform to email merchant, reiterating the required verification & that they are approaching the threshold, and allow them to submit information.
3. third_trigger: Account has processed $1,200,000.00 in a rolling 12-month window for the first time. Platform to email merchant, indicating that additional verification is now required, and direct them to your platform for submission.

The information is all provided to the Legal Entity resource. Note that once the additional information is provided once, it will not need to be provided again.

Here is a preview of how your platform can use the API endpoints above to collect information from high volume NGO's and Charities:

An example of how WePay has implemented the TPV questions for high volume entities.

An example of how WePay has implemented the TPV questions for high volume entities.

An example of how WePay has implemented the upfront questions for high volume entities

An example of how WePay has implemented the upfront questions for high volume entities

Update Personal Information

The individuals associated with a Legal Entity and Account (controllers & additional representatives) may experience a change in their personal information (i.e. phone number, email, address, etc.). Additionally, individuals may leave or join the business, and their information should be removed or added via the API. Here are a few guidelines on how to handle these changes:

• Personal information can be updated at any time, so long as attestation is presented to the user before the update is submitted. See the legal certification for implementation requirements related to these kinds of information updates.
• Updates will trigger re-verification on our end. Re-triggering verification will put an Account's Payout capability in "enabled": "false" until verification is complete, and we may require supporting documentation.
  • Important: If a merchant is actively processing and needs to update information, we encourage you to notify them that payouts will be paused until the updated information is verified on our end.

Block Account Capabilities

This feature provides a layer of control to you, the platform. Use cases may arise where you want to block a merchant from processing payments or receiving payouts, and the Account Block feature allows you to do this. For instance, if a merchant is delinquent in paying their fees to your platform, their processing can be disabled without completely shutting down their account with us.

It is the platform's responsibility to monitor these blocks and notify merchants as needed. If an account is blocked and reaches a deadline listed above, we will attempt to refund and close the account.