The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Fraud Management

Recurly’s Fraud Management is an anti-fraud solution powered by Kount, available to Professional or Enterprise customers.

How do I enable Fraud Management?

  • Contact our Technical Support Team to enable the feature (must be on Recurly Professional or Enterprise Plans).
  • Configure your fraud rules in the Fraud Management section of the Configuration menu. Your fraud rules can be customized based on factors including; Risk Scores, Fraud Velocity Checks, and Country.
  • Once you choose your fraud values, you will need to toggle the status to “Enable” and then “Save Changes” on the fraud configuration page to complete the set-up.

What fraud rules are included?

  • Decline Threshold Rules
    • Decline based on High-Risk Rule
    • Decline based on Risk Score
  • Fraud Velocity Rules
    • Decline based on velocity for the same credit card within an hour
    • Decline based on velocity for the same device IP address within an hour
    • Decline based on velocity for the same email address within 24 hours
    • Decline based on velocity for the same device within an hour
  • Decline blacklisted payment countries based on BIN number (Please note: only VISA and MasterCard BIN countries are provided. Discover and AmEx will always return “US”)

How does it work?

Once Fraud Management has been configured and enabled, Recurly will invoke our risk check service (sending IP address, email address, card details, billing info, and transaction details) for each new card prior to contacting the payment gateway for verification.

If the risk decision is to decline the transaction based on your settings, then Recurly will terminate the transaction and it will not be submitted to the payment gateway. Otherwise, Recurly will continue with the transaction processing by submitting the details to the payment gateway. It’s important to note, the more aggressive your fraud settings are, the higher the transaction decline rate will be. The more relaxed your fraud settings are, the lower the transaction decline rate will be. Thus, it is essential to find the right balance in your configuration.


Device Fingerprinting Technology and IP Address

To get the best results from Fraud Management, you must send Recurly either device fingerprint info or IP address for your end-customer. Failure to include device fingerprint info will drive inaccurate risk score calculations and create false positives, potentially blocking otherwise valid purchase attempts.

  • Device fingerprint info is required if you have enabled score-based rules.
  • An IP address is required if you enable the rule to decline transactions based on velocity for the same device IP address.
  • Make sure that you are using the latest version of Recurly.js
  • Update the Recurly.js dataCollector value from “false” to “true” (see example in GitHub)
  • If you use Recurly's hosted pages, then the device fingerprint information will automatically be passed.

Accessing Fraud Management Data


If an API request to create or update an account’s billing info is declined due to a risk check, the response for the declined transaction will have an error code set to "fraud_risk_check", and the details for the declined transactions in the response will contain a new fraud block that can contain the following three fields: score, decision and an optional rules_triggered.

Recurly Admin Console

Transactions that were declined based on your fraud rules can be easily viewed within the Recurly Admin Console Transactions section using the “Fraudulent” filter on the left side.

The Error Details section in the Transaction Details page will contain additional information about the decline. Note that there is no gateway error since this transaction was decline via Fraud Management, it was never sent to the payment gateway for processing.

The transaction details will provide additional insight into the reason for the decline. When a transaction is declined due to Fraud Management checks, you will see the “Fraudulent” failure type.


The Transactions export will include three new columns to provide the results of your Fraud Management risk checks.

These columns will be populated only for the transactions for which risk check was performed; other transactions will not contain any values. These columns will be blank for merchants who have not signed up for Recurly's Fraud Management.

Please note:

  1. When fraud monitoring is enabled, Recurly will perform risk checks on new cards. Existing accounts with a credit or debit card on file will not undergo risk checks unless they update their billing information.
  2. Based on merchant studies, Recurly’s Fraud Velocity Checks are a critical first line of defense in a fraudulent attack. Fraud Management will provide an additional customizable layer of fraud protection.
  3. Recurly charges $0.10 for every risk check performed. Risk checks are performed on non-recurring transactions and account billing information updates.

Kount Enterprise Fraud Management

Merchants subscribed to Recurly's Enterprise plan have the option of Integrating directly with Kount, giving them additional risk inquiry functionality as well as the ability to set custom rules.

Please contact Recurly's Enablement Team for more information.

Fraud Management

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.