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 is committed to supporting our customers by providing the tools you need to continue to grow - and protect your business from fraud. In addition to our native Fraud Velocity Checks, we partner with Kount, the leading fraud management platform, to give you superior fraud-fighting capabilities directly within Recurly.

Fraud Velocity Checks

All transactions are passed through a simple fraud velocity filter before being passed on to the payment gateway. This doesn't guarantee that no fraud will occur, but it will reduce the possibility of large volumes of fraudulent transactions. Please note that the following limits only apply to sites in production mode. When enabled, Fraud Velocity Checks combat fraudulent activity based on the following criteria:

  • Billing Info Updates >10 in 24 hours
  • New Subscriptions >10 in 1 hour
  • Transactions > 20 in 1 hour

If any of these limits are exceeded, transactions will fail with the "fraud_velocity" error code.

Some fraud velocity check filters are enforced using IP address-based rules. To take advantage of this functionality you'll need to be passing IP address to Recurly within the billing info object. If no IP address is provided, or if a local address is provided, such as "127.x.x.x" or "10.x.x.x", we cannot accurately detect fraudulent behavior.

Fraud Velocity Check information is accessible via the Transactions Export as well as within the Admin Console by viewing the Transactions list (Customers > Transactions) and filtering based on Status for “Fraudulent” transactions.

Fraud Velocity Check counts can be reset within the Admin Console by viewing the specific customer account and selecting “Reset Limits” in the Fraud Check Limits card on the lower right side within each account.

There may be certain situations (example: Customer Support Call Centers) where your team may need to whitelist an IP address to prevent inadvertently triggering the Fraud Check Limits. In those cases, an IP address whitelist (single IP or single range) can be defined in your Site Settings. If you have multiple Support centers or situations that would inhibit your business, you have the option of disabling fraud velocity checks for your site. Please contact Technical Support to understand the risk/benefit of this approach.

If you require the ability to configure your own Fraud Velocity rules, contact our Technical Support team for information on Kount Basic (requires Recurly Professional , Elite, or Enterprise Plan).

For comprehensive configuration and customization options, contact our Enablement Team for information on Kount Enterprise (requires Recurly Enterprise plan).

Based on merchant studies, Recurly’s Fraud Velocity Checks are a critical first line of defense in a fraudulent attack. Pairing Fraud Velocity Checks with one of Kount’s Risk Inquiry Services provides an additional, customizable layer of fraud protection.

Kount’s Risk Inquiry Services

Risk Inquiry Services (RIS) is the foundation of Kount’s fraud mitigation technology. Recurly offers two paths for integration, Kount Basic and Kount Enterprise (see below).

Notable Benefits

  • Reduce Manual Reviews
  • Accept More Good Orders
  • Decrease Chargebacks
  • Reduce False Positives
  • Improve the User Experience
  • Lower Operational Costs

Note for merchants who utilize a Content Security Policy (CSP)

If you use a CSP on your site, you will need to add the script below to your CSP for device fingerprinting to work correctly. If you do not use a CSP, you do not need to make this change.

<meta http-equiv="Content-Security-Policy" content="img-src https://DATA_COLLECTOR_URL;connect-src 'self' 'unsafe-eval' 'unsafe-inline' https://DATA_COLLECTOR_URL; script-src 'unsafe-eval' 'unsafe-inline' https://DATA_COLLECTOR_URL; child-src https://DATA_COLLECTOR_URL">

You will need to replace the DATA_COLLECTOR_URL fields above with Recurly provided values. Please contact Recurly support to obtain the correct URL to use.

Kount Basic

When enabled, Recurly invokes Kount’s Risk Inquiry Service (RIS). This services sends IP address, email address, card details, billing info, and transaction details, for each new card verification (new sign-up and billing info update) prior to contacting the payment gateway for verification.

If the risk decision is to decline the transaction, then Recurly will terminate the transaction and it will not be submitted 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.

What fraud rules are included?

Decline Threshold Rules

  • Decline based on High-Risk Rule
  • Decline based on Risk Score

Fraud Velocity Rules

  • Credit Card: Decline based on velocity for the same credit card within an hour
  • IP Address: Decline based on velocity for the same IP address within an hour
  • Email Address: Decline based on velocity for the same email within 24 hours
  • Device: Decline based on velocity for the same device within an hour

Blacklisted Countries

  • Decline blacklisted payment countries based on BIN number (only VISA and MasterCard BIN countries are provided. Discover and AmEx will always return “US")

How do I get started?

  • Contact Recurly Technical Support to enable Kount Basic.
  • Configure your fraud rules under the Configuration > Fraud Management section of your Admin Console
  • 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.

Kount Basic Fraud Management is available on Recurly's Professional, Elite, and Enterprise Plans.

Kount Enterprise

Kount Enterprise is the most powerful and customizable fraud management option available. Kount Enterprise provides you with the same leading digital fraud prevention technology as Kount Basic but with the added benefit of direct access to your own Kount Control Center and a dedicated Kount Customer Success Manager. Kount Enterprise provides you with the necessary tools to fight fraud by giving you the capability to create custom rules based off fraud trends and business policies, access to Kount’s business intelligence tool to perform in-depth analysis, ability to conduct manual reviews, and the utilization of Kount's next-generation artificial intelligence scoring.

How does it work?

When enabled, Recurly will invoke Kount’s Risk Inquiry Service (sending IP address, email address, shipping address, card details, billing info, and order details, etc to Kount) for each new card prior to contacting the payment gateway.

Kount responds with a risk decision based on their proprietary artificial intelligence and applies your custom rules. Recurly will honor the risk decision returned by Kount’s service. If the risk decision is to decline the transaction 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.

Contact Recurly's Enablement Team to get started.

Kount Enterprise Fraud Management is available on Recurly's Elite and Enterprise Plan.

Updated about a month ago

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.