Setup Platform

 

BETA

Link is currently available in stage only.


Contract

 

Contact WePay for contract options:

  • If you’re already working with our sales team, reach out to your contact.
  • If you’re looking to start the discussion, please reach out to sales@wepay.com.

Marketing

 

Use the standard Chase logo in any platform-hosted materials (i.e. marketing, knowledge base articles, onboarding):

Standard Chase Logo

Do NOT use the Chase Integrated Payments powered by WePay logo in any platform-hosted materials.

The term “Chase Integrated Payments, Powered by WePay” or “Chase Integrated Payments” can only exist in text form if mentioned in any of your platform’s product, marketing, or knowledge base content. Either term can be used at your discretion. The Chase Integrated Payments, Powered by WePay logo can ONLY exist inside WePay’s product experiences and system emails (if it comes from a wepay domain).


Javascript Library

 

As you continue integrating the Link 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 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, 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.

You can add tokens for the following endpoints:

Endpoint Tokenizable Fields & Objects
payment_methods credit_card, custom_data, payment_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 payment_methods/{id} endpoints when tokenizing for the payment methods 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": "payment_methods",
   "payment_methods": {
     "credit_card": {
        "card_holder": {
          "address": {
            "country": "US",
            "postal_code": "94025"
           },
          "email":"example@wepay.com",
          "holder_name": "Jon Snow"
         },
        "card_number": "4111111111111111",
        "expiration_month": 4,
        "expiration_year": 2020,
        "card_on_file": true,
        "recurring": false
    }
}             

Create a token

 

For this example, we’ll look at tokenizing Payment Method information. More information on creating Payment Methods can be found in our Process Payments article.

Construct your request using the payment method information provided by your merchant.

<script>
  document.getElementById("submit-button").addEventListener('click', function() {
    WePay.tokens.create({
     "resource": "payment_methods",
     "payment_methods": {
      "credit_card": {
        "card_holder": {
          "address": {
            "country": "US",
            "postal_code": "94025"
           },
          "email":"example@wepay.com",
          "holder_name": "Jon Snow"
         },
        "card_number": "4111111111111111",
        "expiration_month": 4,
        "expiration_year": 2020,
        "card_on_file": true,
        "recurring": false
        }
      }
    }, {}, 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 CVV 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 payment method, your platform server will make a request passing a token and the cvv parameter.

curl -X POST \
  https://stage-api.wepay.com/payment_methods \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "cvv": "123",
  "token": {
    "id": "payment_methods-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 might expect our client to modify the recurring fields and the card_on_file fields of the credit card 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/payment_methods \
  -H 'Api-Version: 3.0' \
  -H 'App-Id: app-12345' \
  -H 'App-Token: app-token-12345' \
  -H 'Content-Type: application/json' \
  -d '{
  "cvv": "123",
  "token": {
    "id": "payment_methods-91af0e49-000e-4684-a7b9-a2deba006971",
    "permissioned_fields": [
      "credit_card.card_on_file",
      "credit_card.recurring"
    ]
  }
}'

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.

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 Link 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 processing payments. All these calls accept an array of rBits, that you define inline.

For example, let’s say you want to attach the Transaction Details object to your Payments. You’ve noticed a significant increase in payments, of which a bunch were spam. As such, you now add in Transaction Details as an rBit to get ahead of the problem.

{
  "rbits": [{
    "receive_time": 1367958263,
    "type": "transaction_details",
    "source": "user",
    "transaction_details": {
      "itemized_receipt": [
    	{
    	"amount": 105,
    	"currency": "USD",
    	"description": "Premium lawn service package",
    	"item_price": "100",
    	"project_name": "Lawn service at 123 Fake St.",
    	"quantity": 1,
    	"service_billing_method": "hourly_billing_at_project_rate"
    	}],
      "note": "returning customer, new payment method"
    }
  }]
}

You’ll notice that at creation time of a new Payment, 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 Payment, 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 Accounts and Payments, the better overall experience and minimization of loss for your end merchants and payers.


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

 

WePay handles all payments-related communications to merchants and payers via the email address on file.

That said, the Notifications resource are webhooks and help your platform stay in-sync with WePay API states. Develop automated callback_uri generation in order to retrieve updates on WePay API objects through Notifications. This is paramount to keeping your platform database and functions in-sync with the status of payments, accounts, refunds, etc.

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.

You will notice the ability to retrieve sent Notifications in your WePay dashboard. 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.

Below are recommended Notification event topics to subscribe to:

Topic Name Topic Description Recommended Platform Action
accounts.created A Merchant created an account for your platform. Use the notification payload or a GET/accounts/{id} request to reflect the account in your own platform. Guide the merchant through any remaining onboarding requirements.
accounts.capabilities.updated The capabilities of an account have been updated. Reflect an account’s disabled capabilities in your own platform (i.e. prevent new payments) 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.
adjustments.created An adjustment was created for a transaction between payer and merchant. Reflect any adjustments for your own platform functions, as needed.
disputes.created A dispute was created by a payer. Reflect the dispute for your own platform functions (i.e. mark an invoice as disputed, do not ship items on a disputed payment, etc).
disputes.resolved A dispute was closed. Reflect the dispute resolution for your own platform functions using the resolution.type and resolution.time parameters on the GET /disputes/{id} response.
payments.created A payment was created. Reflect the payment for your own platform functions.
payments.canceled A payment was canceled. Reflect the canceled payment for your own platform functions (i.e. mark an invoice as unpaid, do not ship items on a canceled payment, etc).
payments.failed A payment failed to process. Reflect the failed payment for your own platform functions (i.e. mark an invoice as unpaid, do not ship items on a failed payment, etc).
payment_methods.created A payment method was created by a payer on your platform. Reflect the payment method for your own platform functions (i.e. payer login and management).
payment_methods.deleted A payment method was deleted. Reflect the deleted payment method for your own platform functions (i.e. payer login and management).
payment_methods.verified A payment method was verified. Since ACH payment methods must have verified micro deposits, use this notification to allow payment attempts with payment_bank_us type of payment methods.
refunds.created A refund was created. Reflect the new refund for your own platform functions (i.e. mark an invoice as refund processing).
refunds.completed A refund was completed successfully. Reflect the refund for your own platform functions (i.e. mark an invoice as refunded).
refunds.failed A refund has failed. Reflect the failed refund for your own platform functions (i.e. re-mark an invoice as paid).

For a full list of notifications that you can subscribe to, visit our Notification Preferences API reference.


Next up: Now that we’ve covered Platform Setup, you are ready to Onboard Merchants. Questions? Need help? Visit our support page!