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?

  1. Contact our Support Team to confirm eligibility and enable feature flag.
  2. Located under the Configuration navigation within Recurly admin console, you can find the Fraud Settings configuration. This is where you will configure your Recurly fraud rules, which determine what types of transactions will be declined.
  3. Once you choose your fraud values, you will need to select status “Enable” and select “Save Changes” on the fraud configuration page to start sending live non-recurring transactions and account billing updates to our fraud service.

What are the fraud rules included in Fraud Management Settings?

  • Decline based on High Risk Rule
  • Decline based on Risk Score
  • 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 American Express will always return US)

How does it work?

After you set up your Fraud Settings and enable the feature, 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.

Our system will respond to transaction call with a risk decision based on your fraud management settings. If the risk decision is to decline the transaction based on your settings, then Recurly will terminate this transaction and not contact the payment gateway. Otherwise, Recurly will continue with the transaction processing by submitting the details to the payment gateway. If you disable risk checks then Recurly will stop invoking the risk check service. 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 at least IP address) for your end-customer. Device fingerprint info is required if you have score-based rules. IP address is required if you enable the rule to decline transactions based on velocity for the same device IP address. Failure to include device fingerprint info will drive inaccurate risk score calculations and create false positives, potentially blocking otherwise valid purchase attempts.

  • If you use Recurly.js, then make sure you are using the latest version of RJS. Update RJS config to set the dataCollector value to true. Please see example in github and within the developers documentation.
  • If you use Recurly's hosted pages, then the device fingerprint information will automatically be passed to Kount.

In addition to passing Recurly the device fingerprint and/or IP address information, the Recurly API, UI and exports contain some additional fraud details about which you should be aware.


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.


Configuration for Fraud Management is located within the Fraud Settings page in Recurly Admin console. This is where a customer updates their fraud settings.

Transaction Status

The status of transactions declined due to risk checks will be shown as “Declined” and the error code will be “fraud_risk_check”. You can view all fraudulent transactions (transactions declined by Fraud Management) within the transactions page in Recurly admin. The Fraud Details section in the Transaction Details page will contain additional information on the risk checks.


The Transactions export will be updated to include information pertinent to risk checks. The risk checks "fraud_decision", "fraud_score", and "fraud_message" will be added at the end of the export to maintain backward compatibility. 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 signups and when existing customers enter a new credit or debit card. Please note that existing accounts with credit or debit card on file will not undergo risk checks.
  2. We found that Recurly Fraud Velocity Checks (see Transactions ) are still critical based as first line of defense in a fraudulent attack, based on merchant studies. 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.

Recommended Testing Instructions

We recommend you perform a few risk checks in a sandbox site before enabling Kount in production. The recommended scenarios to test are:

  1. Enter Enable and save Kount credentials configure Recurly's Fraud Management settings by visiting the "Fraud Management" section of the Recurly console under “Fraud Management "Configuration".
  2. Create a new account and add new billing info and test card details (you can use the 'successful' test card -- 4111-1111-1111-1111). This should trigger a risk check. Verify that the risk check details are shown in the Recurly account's transaction details and also in your Kount dashboard details.
  3. Create a subsequent transaction for the above account. Risk checks should not be performed on this transaction.
  4. Update the card details for the above account. Verify that the risk checks are performed for this transaction.
  5. Create a custom rule in Kount Perform Velocity and Country Blacklist checks according to decline transactions (ex: based on the provided email). Update the billing info following steps.
    A. Adjust your Fraud Management settings to allow only one transaction per hour for an IP address.
    B. Open a hosted checkout page for your test account and process a test transaction.
    C. Run an additional test transaction. This should be declined.
    Country Blacklist:
    A. Adjust your Fraud Management settings to blacklist a specific country.
    B. Use to locate a BIN from the above account country you blacklisted.
    C. Use to trigger risk checks. Generate a card number using the BIN generated above. Be sure that you do not store this number and only use it for testing purposes on your sandbox site.
    D. Open a hosted checkout page for your test account and process a test transaction using the test card number you generated. This should be declined.
  6. Download the Transactions export from the Analytics -> Exports area. Verify that the transactions contain relevant details related to risk checks.

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.