Setup Platform

 

After reviewing API Basics, you’re ready to start sending API calls. Beyond the basics, there are a few more items to set up for your platform which will enable you to flawlessly integrate with WePay and begin delivering integrated payments to your users.

At a minimum, your platform is required to send Risk Headers to WePay. Risk Headers help us protect your platform and merchants from financial loss due to fraudsters and other bad actors. You’ll integrate Risk Headers into your front-end by implementing the WePay Tokenization SDK. This SDK will also enable you to tokenize PCI and PII data, which will reduce your PCI and PII compliance scope by instead leveraging WePay’s compliance. Additionally, this section will cover the additional risk information that WePay can use to more effectively detect legitimate versus fraudulent behavior. The final step in platform setup is setting notification preferences. Since your platform will be responsible for communicating payment information to your users, WePay allows you to sign up for the payments notifications you need in order to effectively deliver automated, accurate, and timely communications to your customers.

By the end of this doc, you’ll configure WePay’s Tokenization Javascript, begin sending risk information to WePay along with each API call, tokenize the PCI and PII data that your platform does not want to handle, supply additional risk information, and configure your platform notifications to enable your ownership of end-user communications.

Be sure to review our Security Certification for PCI guidelines and security best practices.


Javascript Library

 

As you continue integrating the Clear product, you will need to utilize the WePay Javascript SDK. This SDK allows you to Tokenize sensitive information, and send us Risk headers.

Initialize the SDK on your platform’s pages where you will Tokenize information, and send Risk headers. Read more about required parameters of functions in the WePay Javascript SDK.

<script src="https://cdn.wepay.com/wepay.min.js"></script>
<script>
	var myAppId = "123456";
	var apiVersion = "3.0";
	var error = WePay.configure("stage", myAppId, apiVersion);
	if (error) {
		// An error is returned if any fields are missing or invalid.
		console.log(error);
	}
</script>

Risk Headers

 

There are two Risk Headers: the Risk Token, and the Client-IP.

The Risk Token allows us to capture attributes about a payer or merchant’s device, and have our algorithms identify any suspicious device pattern. If you use the Javascript SDK for tokenization, then you don’t need to explicitly call WePay.risk.get_risk_token() to capture a token, and send on API calls. If you are not tokenizing fields, then you will call that field, and send it to your server, where you will make calls to the WePay API.

In addition, Client-IP is something stored in the Token, which you can then pass to your server to make the call to WePay’s API.


Tokenization

 

Some of the data WePay API calls require is highly sensitive (e.g. credit card data, social security number, bank account number). If your platform collects this information to send to WePay, it could be subject to various compliance and regulatory requirements. Many of which will require your platform to implement additional (and complex) processes. Furthermore, handling sensitive data can make your platform susceptible to data breaches. For example, if your platform collects payment sensitive data like Primary Account Numbers (PAN), it must comply with strict Payment Card Industry Data Security Standard (PCI DSS) requirements, which could also involve costly, annual third-party PCI audits.

To help your platform avoid all this overhead and risk, WePay provides a tokenization process that allows your client application to send highly sensitive data directly to WePay, while giving your platform control over how that data is used.

In addition to reducing PCI compliance, you can use Tokens to collect personally identifiable information (PII), and not have to worry about processing or storing in your own systems.

You can add tokens for the following endpoints:

Endpoint Tokenizable Fields & Objects
legal_entities additional_representatives, address, controller, country, custom_data, description, entity_country_info, entity_name, phone, primary_url, rbits, terms_of_service
payment_methods credit_card, custom_data, payment_bank_us, rbits, type
payout_methods custom_data, nickname, payout_bank_ca, payout_bank_uk, payout_bank_us, rbits, type

Throughout the tutorial, we will mention calls that let you replace collecting sensitive data with Tokenization.

Your platform will need to utilize the WePay JavaScript library to create tokens. Tokenization occurs on the front-end, which means that, while you may collect sensitive information and feed it to our Javascript library, you still have to accept the token returned by the Javascript and pass it to the appropriate endpoint above.

Note

Tokens have a time-to-live (TTL) of 30 minutes.

If you choose to tokenize or not, there are certain values that you won’t be able to read in the Object’s response. For example, if you don’t tokenize the birthday field, and update a Legal Entity, it’ll be stored, but every call to retrieve or update the resource will show the value true instead of the Birthday itself. This behavior only applies to Birthday and Social Security Number of Legal Entities.

Tokenization Quickstart

 

  1. Configure the JavaScript library
  2. Create a token
  3. Use a token
  4. Tokenization Errors

Start creating and using tokens right away with the WePay JavaScript library.

Configure the JavaScript library

 

In the <head> section of your webpage, include a script tag with the source set to the WePay JavaScript library. This gives the library enough time to collect risk-related information.

<script src="https://cdn.wepay.com/wepay.min.js"></script>

Then, add your platform information to the WePay JavaScript library.

<script src="https://cdn.wepay.com/wepay.min.js"></script>
<script>
  var myAppId = "app-12345";
  var apiVersion = "3.0";
  var error = WePay.configure("stage", myAppId, apiVersion);
  if (error) {
    // An error is returned if any fields are missing or invalid.
  console.log(error);
  }
</script>

Note

Function requirements: Two of the SDK functions have required parameters: WePay.configure and WePay.tokens.create. Find the specifics of those requirements here:

WePay.configure

Required Parameter Description
environment An enumeration (expected values are stage or production) indicating the environment where the JavaScript will make requests.
app_id Your application’s ID, which is used to manage ownership of tokens created by the JavaScript (found in the partner dashboard).
api-version The API Version being used for the calls running through the WePay Javascript SDK.


WePay.tokens.create

Required Parameter Description
body The body of the tokenization request. Must be a JSON object with two fields:

* Field 1 must include the key resource and the value should be the resource where you intend to pass tokenized data.
* Field 2 must include the key name matching the value for resource in field 1. The value is the JSON data your platform wants to tokenize. You can tokenize any of the fields in a resource’s schema. For example, your platform can tokenize any data it would normally send to the legal_entities or legal_entities/{id} endpoints when tokenizing for the legal entities resource.
headers Any additional headers to send to the WePay server with your tokenization request.
callback A function called when the request is completed. If this field is not provided, the tokenization request will happen synchronously - blocking further JavaScript execution until the request finishes (not recommended). The single argument provided to the callback function will be a JSON response.


Example of the body parameter:

   "resource": "legal_entities"
   "legal_entities": {
   "country_info": {
      "US": {
        "social_security_number": "012-34-5678"
          }
             }

Create a token

 

For this example, we’ll look at tokenizing Legal Entity information. More information on creating Legal Entities can be found in our Onboard Merchants article. Walk throughs of tokenizing payment method information can be found in our Process Payments article, and walk throughs of tokenizing payout method information can be found in our Payout Merchants article.

Construct your request using the legal entity information provided by your merchant.

<script>
  document.getElementById("submit-button").addEventListener('click', function() {
    WePay.tokens.create({
      "resource": "legal_entities",
      "legal_entities": {
        "controller": {
          "date_of_birth": {
            "year": 1975,
            "month": 1,
            "day": 1
          },
          "personal_country_info": {
            "US": {
              "social_security_number": "012-34-5678"
            }
          }
        }
      }
    }, {}, function(response) {
      // Handle the response by passing the token to your webserver
      // and using it in a POST /legal_entities request.
      console.log(response);
    });
  });
</script>

Note

Tokenization request validation: Because a request to create a token will be validated against WePay schemas, any schema validation failures that can occur from the resource being tokenized can also occur during token creation. The exception to this is that a tokenization request does not validate required fields, as your server may provide the required fields with the token later on (like country in our previous example).


Use a token

 

Your platform’s servers will pass the token and other parameters to WePay’s servers in a request. WePay then takes the data used to create the token and combines it with other parameters provided in the request.

For example, using the token we created above for a legal entity, your platform server will make a request passing a token and the country parameter.

curl -X POST \
  https://stage-api.wepay.com/legal_entities \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "US",
  "token": {
    "id": "legal_entities-91af0e49-000e-4684-a7b9-a2deba006971"
  }
}'

Note

Token Permissioned Fields: Since the token is created entirely on the web client, your platform’s ability to guarantee what is in the token would normally be limited. However, for platforms that need control over what data was provided, you can provide the permissioned_fields list in the token structure in addition to the id.

Permissioned fields are a list of dot-notated JSON paths that are allowed to set by this token. In our previous example, we expect our client to modify the date_of_birth fields and the social_security_number fields of the controller structure. We can make sure that the token does not modify other fields by providing permissioned_fields with the server request:

curl -X POST \
  https://stage-api.wepay.com/legal_entities \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "US",
  "token": {
    "id": "legal_entities-91af0e49-000e-4684-a7b9-a2deba006971",
    "permissioned_fields": [
      "controller.date_of_birth",
      "controller.country_info.US.social_security_number"
    ]
  }
}'

Tokenization Errors

 

When a token is expanded into your request, you may encounter a TOKEN_CONFLICT error code. This error is thrown if:

  • One of the fields in the token is also modified by the server request (reason code: TOKEN_FIELD_CONFLICTS_WITH_PROVIDED_FIELD).

  • The token modifies fields that are not supplied in the permissioned fields list. This will only happen if permissioned_fields is provided and the token modifies data that is not included in that list.

Visit our Errors page for more details.


Supply Risk Information

 

As a platform, it’s extremely important to make sure you’re providing WePay with Risk information on as many API calls as possible. That being said, you will need to work with your account manager to understand which Risk objects to send, as each integration is specialized to the vertical and available data.

WePay has a team of Risk Analysts, plus machine learning models to capture data and ensure fraud is handled correctly. By feeding more data to the system, your platform and merchants have a better chance of minimizing losses and continuing a smooth user experience. Conceptually, we think of Risk as structured metadata you can add to almost every endpoint on Clear except Transaction Records and Recoveries. You can pass risk bits (rBits) inline for all these API calls, or by calling the rBits endpoint directly, after creating these resources.

If required by the WePay team, you may need to send Items and Orders, in addition to rBits, to augment your risk data. By providing this data, you’ll provide the WePay Risk team with richer data to continue leveraging our sophisticated risk algorithms, and ultimately better protect you and your merchants.


Add Rbits

 

We’ll first walk through the inline flow. Let’s say you’re onboarding Merchants. All these calls accept an array of rBits, that you define inline.

For example, let’s say you want to attach the Business Description object to your Legal Entities. You’ve noticed a lot of Legal Entities signing up, of which, a bunch were spam. As such, you now add in Business Description as an rBit to get ahead of the problem.

{
  "country": "US",
  "rbits": [{
    "receive_time": 1367958263,
    "type": "business_description",
    "source": "user",
    "business_description": {
      "description": "A small mom and pop charity shop",
      "number_of_employees": 5,
      "sales_tax_liability_flag": false
    }
  }]
}

You’ll notice that at creation time of a new Legal Entity, an rBit array was included. If you choose to do so, you can pack more rBits into the array.

It’s also not necessary to do the inline flow, as you can first create a Legal Entity, and update it with rBits after creation.

View the Full API reference to see where you can add rBits. In general, the more you add to your Legal Entities, Accounts, Payments, and Payouts, the better overall experience and minimization of loss for your end merchants and payers.

rBits allow you to define business information (like name and description), details about the campaign (if it’s a fundraising transaction), the industry code, and more.


Define Items

 

Items are structurally tied to an Account, so you have two options of creating items. You can create Items and pass them inline when creating or updating an Account. Alternatively, you can create Items by sending a POST to the Items endpoint. If you use this method, you must pass the account_id, so first create an Account.

You can attach rBits to Items, as well.


Create Orders

 

Orders are another structured object to help you pass risk information to WePay. Conceptually, Orders are a superset of Items, and can also contain rBits.

Orders are roughly equivalent to metadata about a checkout, like a payment receipt.

Orders are flexible - they could refer to items in them. Same items could just be text. Orders could also be an invoice. This can be tied to the payment, but not necessary to be. They are top level items.

There’s an order of operations element to this - we’d like to get this first potentially before payment is processed.

On the other hand. Checkout happens and then payment happens - then there could be a separate order call and payment call, but you can also do it inline.


Notifications

 

Notifications are webhooks sent by the Clear API to deliver information about your merchants, payment processing, and payment operations. Every section in the integration guide will call out required notifications you must send to payees or merchants on your platform.

The lifecycle follows this general pattern:

  • Receive a notification from WePay about a payment, merchant, payout, or other operation.
  • Inspect content of the notification, and determine if communication is required with your merchants or payers.
  • If communication required, send an email to the required recipient.
  • If communication isn’t required, store notification.

If a Notification fails to reach your servers, we will attempt to retry, and they follow this pattern:

  • 1st retry will happen 15 minutes after the initial attempt.
  • 2nd retry will happen 30 minutes after the 1st retry.
  • 3rd retry will happen 1 hour after the 2nd retry.
  • 4th retry will happen 6 hours after the 3rd retry.
  • 5th retry will happen 12 hours after the 4th retry.
  • 6th retry will happen 24 hours after the 5th retry.

When you transition to the live instance on your dashboard, the WePay team will validate your Notifications implementation. Reference the Notifications specification here. You will notice the ability to retrieve sent Notifications, as well. Notifications are not stored permanently. If you haven’t subscribed to notifications, you won’t be able to retrieve older notifications once subscribed. However, once subscribed, Notifications are stored for 30 days.

Here’s a list of all Notification topics broken down by requirement. Relevant notifications will also be outlined as you go through the Basic Integration.

Required:

Topic Name Topic Description Required Platform Action
accounts.created A Merchant created an account on your platform. Notify merchants of remaining onboarding steps by using GET /accounts{id}/capabilities and GET /legal_entities/{id}/verifications calls.
accounts.capabilities.updated The capabilities of an account have been updated. Notify merchants of disabled capabilities when the payments.enabled and/or payouts.enabled parameters on a GET /accounts{id}/capabilities call return as false when the value was previously true.
accounts.capabilities.updated The capabilities of an account have been updated. Notify merchants that their payout method has been disabled when the payouts.enabled parameter on a GET /accounts{id}/capabilities call return as false when the value was previously true.
disputes.created A dispute was created by a payer. Notify the merchant of the dispute and how to either challenge or concede it through your UI.
disputes.resolved A dispute was closed. Notify the merchant of the dispute resolution using the resolution.type and resolution.time parameters on the GET /disputes/{id} response.
legal_entities.verifications.updated A Legal Entity’s verification information was updated. May contain information that requires a Legal Entity to be re-verified. Notify merchants that updated information or documentation must be submitted when any parameters on the GET /legal_entities/{id}/verifications call return with a value of rejected.
legal_entities.verifications.updated A Legal Entity’s verification information was updated. May contain information that requires a Legal Entity to be re-verified. Notify merchants that supporting documentation must be submitted when any issue_type returns with the additional_documents_required value.
payments.created A payment was created. Send the payer a receipt.
payments.canceled A payment was canceled. Notify the merchant and the payer that the payment was canceled.
payments.failed A payment failed to process. Notify the merchant that the payment failed.
payouts.failed A payout was failed. Notify the merchant that a payout failed.
Topic Name Topic Description Recommended Platform Action
accounts.updated An account was updated. Notify a merchant that their active payout method has been updated when the payout.currencies.X.payout_method_id value on a GET /accounts/{id} changes.
adjustments.created An adjustment was created for a transaction between payer and merchant. Notify the merchant of the adjustment to their account.
legal_entities.verifications.updated A legal entity’s verification information was updated. Notify the merchant that their information has been verified when all is_verified parameters on a GET /legal_entities/{id}/verifications call return with a true value.
legal_entities.verifications.updated A legal entity’s verification information was updated. Notify the merchant that their information has been updated.
payment_methods.verified A payment method was verified. Notify the payer that micro-deposits have been verified when this notification is received and the value for the type parameter on a GET /payment_methods/{id} call is payment_bank_us.
payouts.in_review A payout is under review. Notify the merchant that their payout is under review.
payments.failed A payment has failed. Notify the payer that their payment has failed.
recoveries.created A recovery was created. Notify the merchant that a debit from their attached payout method has started as a result of a negative balance.
recoveries.failed A recovery failed. Notify the merchant that the debit from their payout method failed, and that their account will need to be made whole.
refunds.created A refund was created. Notify the merchant and payer that a refund has started processing.
refunds.failed A refund has failed. Notify the merchant and payer that the refund failed to process.

 

Additional notifications that WePay recommends subscribing to include:

Topic Name Topic Description
legal_entities.created A Legal Entity was created on your platform.
legal_entities.updated A Legal Entity was updated on your platform.
payment_methods.created A payment method was created by a payer on your platform.
payment_methods.deleted A payment method was deleted.
payment_methods.updated A payment method was updated.
payment_methods.microdeposit_sent Micro-deposits were sent to this payment method.
payouts.created A payout was created.
payouts.completed A payout was completed successfully.
payout_methods.created A payout method was created.
recoveries.completed A recovery was completed successfully.
refunds.completed A refund was completed successfully.

 

While we recommend subscribing to all notifications, we will walk through the Basic Integration and make note of the mandatory notifications to receive and act upon.


Now that your platform is set up, we’ll Onboard Merchants. Questions? Need help? Visit our support page!