The WePay API accepts HTTP headers on every request that provides WePay with risk-related information associated with that request. These headers are optional but should be provided when possible to improve WePay’s risk decision making process.

Caution

You must include risk-related headers in your requests if using the server to server model to collect credit card information.

There are two risk-related request headers:


Client-IP

This HTTP header value should be the public IP address of the client whom the API call is made on behalf of. For example, if you are making an /account/create call, this would be the IP address of the user who triggered the API request on your system.

Use the following form when passing in the Client-IP HTTP header, where 100.166.99.123 is the public IP address of the client:

Client-IP: 100.166.99.123


WePay-Risk-Token

This HTTP header value should be the risk token UUID generated by the Risk JavaScript library on the webpage of the user who triggered the API request on your system.

Use the following form when passing in the WePay-Risk-Token HTTP header, where 123e4567-e89b-12d3-a456-426655440000 is the risk token generated by the Risk JavaScript library:

WePay-Risk-Token: 123e4567-e89b-12d3-a456-426655440000


Risk JavaScript library

The WePay Risk JavaScript library (Risk.js) is responsible for generating a risk token for use with the WePay-Risk-Token HTTP header. It collects risk-related information from the client that loads the JavaScript and associates it with the risk token.

Usage

To use the JavaScript library, add a script HTML element to your webpage using https://static.wepay.com/min/js/risk.js as the source.

<script type="text/javascript" src="https://static.wepay.com/min/js/risk.js"></script>

When your webpage finishes loading, Risk.js waits 5 seconds and then generates a risk token. This delay ensures that the token generation process does not impact your page load performance. You can also choose to manually generate the token when you are ready.

Documentation

Risk.js has two methods for generating and receiving the risk token:

WePay.risk.get_risk_token()

  • Returns a UUID token that is associated with the client machine on which Risk.js is loaded. If called before the token has been generated it returns 0.

WePay.risk.generate_risk_token()

  • Immediately generates the risk token. If called after the risk token has been generated, it will have no effect. The best time to use this method is after your page has fully finished rendering so as not to impact page load performance.

Best Practices

To get the most out of Risk.js, follow these recommended best practices:

  • Load the Risk JavaScript library on the webpage that triggers your API calls to WePay.
  • WePay risk tokens are only valid for 48 hours, so try to generate new ones when possible.
  • When your webpage has fully finished rendering, call WePay.risk.generate_risk_token() to ensure that the risk token is available when you call WePay.risk.get_risk_token().