Fraud

Add device-fingerprinting data to every Recurly.js token so Recurly Fraud Management, Kount, or Braintree can score the transaction before it reaches your gateway.

Recurly.js can automatically embed the browser/device data required by common fraud-screening tools:

  • Recurly Fraud Management (built on Kount)
  • Standalone Kount accounts—including Enterprise plans with custom UDFs
  • Braintree Advanced Fraud Tools

Enable the relevant collector once, and every token returned by Recurly.js includes the proper payload for the gateway or provider. No extra API calls or client libraries are needed, except for Braintree’s own device-data snippet.

Prerequisites and limitations

  • Fraud protection must be enabled on your Recurly site and—if applicable—your Kount or Braintree credentials must be configured in the Recurly admin UI.
  • Kount / Recurly Fraud Management
    • Set fraud.kount.dataCollector: true in recurly.configure; pass the checkout form element.
    • Enterprise customers may add or mutate fraud.kount.udf (User Defined Fields) before tokenization.
  • Braintree
    • You must first call braintree.dataCollector in your page to obtain the deviceData string, then supply it via fraud.braintree.deviceData.
  • Device collection runs once per page load; ensure the configuration executes before the first call to tokenize.
  • Collected data is attached only to newly-generated tokens; reusing a previously created token will not refresh fraud data.
  • Fraud payload size is controlled by the provider; very large custom UDF objects may be truncated.

Key details

Recurly.js provides a fraud protection suite with support for our Fraud Management toolkit, Kount integration, and Braintree gateway integration.

With fraud protection enabled, tokens created with Recurly.js will include device data we use to analyze fraud risk and flag subsequent transactions accordingly. Configuration is simple.

Configuring Fraud Protection

Once you have enabled fraud protection on your site, modify your Recurly.js configuration call according to your fraud protection setup.

Recurly Fraud Management & Kount Integration

If you are using Recurly Fraud Management or Kount, Recurly.js will handle all device data collection when configured as follows. Recurly Fraud Managment uses Kount's device data collector under the hood. The form parameter should be your checkout form.

recurly.configure({
  // ...
  fraud: {
    kount: {
      dataCollector: true,
      form: document.querySelector('.my-checkout-form-selector')
    }
  }
  // ..
});

This will enable device data collection and automatically apply it to your tokens.

When using a Kount Enterprise Fraud Management plan you can provide your own User Defined Fields with the udf option.

recurly.configure({
  // ...
  fraud: {
    kount: {
      dataCollector: true,
      form: document.querySelector('.my-checkout-form-selector'),
      udf: {
        FREQUENCY: 107,
        COUPON: 'BUY11',
      }
    }
  }
  // ..
});

In order to add or remove User Defined Fields after configuring Recurly, you can assign a reference to an object that you can modify later.

Braintree Gateway Fraud Integration

First, you will need to collect device data using the Braintree JavaScript client. This is required by Braintree.

Once you have obtained deviceData, you'll provide it to recurly.configure as follows. Note that we're passing the complete deviceData string as exposed by the Braintree library.

// Collect device data using the Braintree client
// ...

const { deviceData } = braintreeInstance;

recurly.configure({
  // ...
  fraud: {
    braintree: { deviceData }
  }
  // ...
});

This will apply Braintree fraud data to your tokens generated by Recurly.js. Transactions created with those tokens will pass the fraud data to Braintree for fraud analysis.