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    

Kount Fraud Management Integration

Recurly’s fraud management is powered by Kount. Merchants can log into their Kount account to create custom rules, as well as search and investigate transactions for which risk checks were performed.

Kount is available on Recurly's Enterprise Plan.

How do I enable Fraud Management?

  1. Contact Recurly's support team to get additional details and help you setup your Kount account.
  2. Create your custom fraud rules under the “DEFAULT” site in Kount.
  3. Contact Recurly's support team to enable Fraud Management on your site.
  4. Navigate to Fraud Management under the Configuration section in your Recurly site.
  5. Click on “Configure Account”.
  6. Enter Kount credentials, enable Fraud Monitoring and click “Save”.
  7. To enable Kount's ENS notifications (more info below), merchants will have to configure the callback URL for DEFAULT website in Kount dashboard. Set the URL to
  8. To take advantage of device fingerprinting technology (more info below):
    a) 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
    b) If you use Recurly's hosted pages, then the device fingerprint information will automatically be passed to Kount.

How does it work?

When you add Kount credentials, Recurly will invoke Kount’s risk check 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’s risk check service responds with a risk decision based on their proprietary algorithms 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. If you disable risk checks then Recurly will stop invoking Kount's risk check service.

Kount’s fraud solution is very effective when used in conjunction with the device fingerprinting. Device fingerprinting allows Kount to identify the transaction's originating device accurately. Device fingerprinting technology needs to collect device info directly from the your checkout pages.

Do I need to change anything?

There are no changes required to the way you integrate with Recurly. However new fraud details have been added to our API, UI and exports:


If an API request to create or update an account’s billing info is declined due to Kount's risk checks, 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.


The status of transactions declined due to automatic or manual risk checks will be shown as “Declined” and the error code will be “fraud_risk_check”. 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. Three new columns ("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 the Kount service. The Transactions export will also be updated to include the fraud details from the latest update.

Our Support Team ( can provide relevant answers in case you have any questions.

Please note:

  1. All transactions will be submitted to the “DEFAULT” site in your Kount merchant account. This means that the custom rules for the “DEFAULT” site will be applied to each risk check invocation.
  2. Kount only accepts account_codes that are 32 characters or less. To honor this restriction, for any account_codes exceeding 32 characters, Recurly will only send the first 32 characters to Kount. If you use the Link Analysis in Kount, this could lead to merging the histories of different accounts whose account_code’s contain the same first 32 characters.
  3. Only credit cards are supported at this time. Tokenized (wallet) payment methods like PayPal or AmazonPay are currently not supported. ACH is also not supported.

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 and save Kount credentials under “Fraud Management”
  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 transaction details and also in your Kount dashboard.
  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 to decline transactions (ex: based on the provided email). Update the billing info for the above account to trigger risk checks. Confirm that your custom rule is triggered as expected and also that Recurly declines the transactions.
  6. Download the Transactions export from the Analytics -> Exports area. Verify that the transactions contain relevant details related to risk checks.

Kount Fraud Management Integration

Suggested Edits are limited on API Reference Pages

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