On This Page
On This Page

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. Please be sure to review our Risk Certification guide for more information on WePay’s risk management.

Caution

You must include risk-related headers in your requests if you are tokenizing credit card or KYC information from your server. This is also referred to as a “server to server” model.

On the payments side, you must include these headers on /credit_card/create. For KYC, these headers must be included on both /account/kyc/create and /settlement_bank/create.

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 a /credit_card/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 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.1.latest.js as the source.

<script type="text/javascript" src="https://static.wepay.com/min/js/risk.1.latest.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. Note: this method does not return the risk token.

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.
  • Load the Risk JavaScript library as soon as possible on the webpage. This gives the library time to collect and tokenize risk related information.
  • 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().
  • If you are choosing not to load the Risk JavaScript library immediately on page view, make sure to call WePay.risk.generate_risk_token() immediately after loading the script.
<script type="text/javascript" src="https://static.wepay.com/min/js/risk.1.latest.js"></script>
<script type="text/javascript">
	WePay.risk.generate_risk_token()
</script>