iFrame APISupportBlog
Guides

Kount

How to set up and use Kount as your embedded fraud provider

Suggest Edits

Founded in 2007, Kount, an Equifax Company, is the leader in trust and safety technology. Powered by advanced AI and machine learning, Kount helps businesses grow with complete confidence. The platform includes solutions for fraud detection and prevention, identity verification, chargeback management, regulatory compliance, and more.

Kount account configuration

Before getting started with Spreedly and Kount, you will need to create an API key and configure a User Defined Field. Both of these steps are completed in the Agent Web Console.

The API key will be used to create your Fraud Vendor token.

Create a user defined field (UDF), type alphanumeric, called "SPREEDLYTXN_TOKEN". Spreedly will use this field to transmit Spreedly's transaction token to the Kount dashboard. Not creating this field will cause transaction errors later on. This field will be automatically populated and there is no need to include it in your vendor-specific fields on each transaction. Spreedly sends the token value as a hexadecimal value; in order to get the token, convert the value from hexadecimal to text.

Create a Kount Vendor

To create a Kount Fraud Vendor, send a request to https://core.spreedly.com/v1/fraud_control/vendors.json. You will need your Kount API Key, Merchant ID and Site ID. 

{  
  "fraud_control_vendor": {  
    "type": "kount", 
    "site_id":"<your site ID>",
    "merchant_id": "<your merchant ID>",
    "api_key":"<your API Key>",
    "sandbox": true  
  }  
}

Including sandbox: true will point to Kount's sandbox. To utilize Kount in production, make sure your Fraud Vendor has sandbox: false.

Spreedly will respond with a Fraud Vendor Token. Save the token for utilizing in your transactions:

{
    "fraud_control_vendor": {
        "token": "5SVN7FCAMF9M98VG67FS9MTA",
        "sandbox": true,
        "created_at": "2024-02-12T18:08:48Z",
        "updated_at": "2024-02-12T18:08:48Z",
        "type": "kount"
    }
}

Prepare your front end

In order to utilize Kount, the Device Data Collector (DDC) will need to be added to the checkout page, and a session ID will need to be generated and sent to Spreedly. This allows Spreedly to send the data collected on the checkout page to Kount. It is recommended to add the DDC to the top of the checkout page code.

Session ID

A Session identifier is used to connect the device data collected by the DDC to the order information. This value must be unique per each risk assessment transaction. Kount provides instructions for generating Session Ids. In general the identifiers must have the following requirements:

  • Must be unique per request and for a minimum of 30 days
  • Must contain only alphanumeric characters (0-9, a-z, or A-Z), dashes (-) or underscores (_)
  • Session ID values cannot exceed 32 characters in length

This value will be passed to the DDC and then to your back end and Spreedly transaction.

In the sandbox, any value can be passed as the session ID. However, in production it is required to have a valid session identifier that follows the requirements and is tied to a Device Data Collector session.

Device Data Collector (DDC)

For the most accurate information on the DDC, and other implementation tips please utilize Kount's documentation or their FAQs.

Kount provides SDKs for both Web and Mobile. The Client ID you provide to the SDK will be the same value that you include under merchant_id during the Fraud Vendor Token creation at Spreedly.

In the sandbox, this information can be omitted. If omitted, information about the device with not show in either the vendor_response nor the Kount Dashboard. In production the DDC is required.

Transacting

For a full understanding of initializing a transaction that includes embedded fraud, refer to initializing a transaction. Documented here are the items needed for a specific Kount integration.

When utilizing Kount as a Fraud vendor, it is important that your transaction contain the information required to receive an accurate fraud determination. This information can be sent in Spreedly's fields and in the Kount-specific fields.
Currently, Kount will only return fraud scores on transactions utilizing the following payment methods:

  • Credit Cards
  • Apple Pay
  • Google Pay

Spreedly Mappings

The following fields, if sent on a Spreedly transaction, will be sent to Kount. We recommend sending the most information available in order to get the most accurate fraud review.

  • email
  • shipping_address
  • billing_address
  • ip
  • order_id

Please note that Kount expects two character country codes in the addresses.

Kount-Specific Fields for Transactions

Kount requires cart information in addition to the session_id. Spreedly has also allowed any additional User Defined Fields to be passed via the vendor-specific fields. For the User Defined Fields, please provide the field and the value. 

"fraud_detection_parameters": {  
    "pre_authorization_check": true,  
    "vendor_specific_fields": {  
      "kount":{
       "session_id":"<session id>",
        "user_defined_fields":{}
      },
      "cart_items": [
        {
          "desc": "Spreedly TEST Monitor",
          "item": "SpreedlTest_U4919DW",
          "price": "136999",
          "quantity": "1",
          "type": "Monitor"
        },
        {
          "desc": "Spreedly TEST Display Port Cable",
          "item": "SpreedlTest_DPC10FT",
          "price": "001",
          "quantity": "1",
          "type": "Cable"
        }
      ]
    }  
}

Response Fields

In addition to the standard fraud response fields, Spreedly will pass back raw information from Kount. Upon a successful response, the fraud_detection_pre_authorization nest will contain information about the request. The vendor_response object will provide Kount fields.

"fraud_detection_pre_authorization": {
  "created_at": "2024-02-16T19:33:33Z",
  "updated_at": "2024-02-16T20:04:09Z",
  "succeeded": true,
  "state": "succeeded",
  "token": "Cv4mxTvDpjLRMy9kuQ53N692r2p",
  "amount": 100,
  "currency_code": "USD",
  "ip": "181.57.222.58",
  "email": "[email protected]",
  "order_id": null,
  "transaction_type": "FraudControl::Detection",
  "vendor_transaction_id":"KK530MTDC5N7",
  "vendor_response": {
    "content": {
      "VERS": "0720",
      "MODE": "Q",
      "TRAN": "KDPN08N85BSX",
      "MERC": "100458",
      "SESS": "17079372081334ozaxpqy91",
      "ORDR": null,
      "AUTO": "A",
      "SCOR": "30",
      "GEOX": "CO",
      "BRND": "VISA",
      "REGN": "CO_34",
      "NETW": "N",
      "KAPT": "Y",
      "CARDS": "1",
      "DEVICES": "1",
      "EMAILS": "1",
      "VELO": "0",
      "VMAX": "0",
      "SITE": "EU2",
      "DEVICE_LAYERS": "24E34ED3A1..B1DD0E613E.B9D9F20AB5.D118C78A29",
      "FINGERPRINT": "869BD6383F1B4E12A6A87936095F7C97",
      "TIMEZONE": "300",
      "LOCALTIME": "2024-02-16 15:04",
      "REGION": "CO_34",
      "COUNTRY": "CO",
      "PROXY": "N",
      "JAVASCRIPT": "Y",
      "FLASH": "N",
      "COOKIES": "Y",
      "HTTP_COUNTRY": null,
      "LANGUAGE": "ES",
      "MOBILE_DEVICE": "N",
      "MOBILE_TYPE": null,
      "MOBILE_FORWARDER": "N",
      "VOICE_DEVICE": "N",
      "PC_REMOTE": "N",
      "RULES_TRIGGERED": 0,
      "COUNTERS_TRIGGERED": 0,
      "REASON_CODE": null,
      "DDFS": "2023-11-07",
      "DSR": "1080x1920",
      "UAS": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "BROWSER": "Chrome 121.0.0.0",
      "OS": "Mac OS X 10.15.7",
      "PIP_IPAD": null,
      "PIP_LAT": null,
      "PIP_LON": null,
      "PIP_COUNTRY": null,
      "PIP_REGION": null,
      "PIP_CITY": null,
      "PIP_ORG": null,
      "IP_IPAD": "165.1.173.37",
      "IP_LAT": "4.6",
      "IP_LON": "-74.0833",
      "IP_COUNTRY": "CO",
      "IP_REGION": "Distrito Especial",
      "IP_CITY": "Bogota",
      "IP_ORG": "Palo Alto Networks  Inc",
      "OMNISCORE": 27.2,
      "PREVIOUSLY_WHITELISTED": "N",
      "THREE_DS_MERCHANT_RESPONSE": null,
      "WARNING_COUNT": 0
    },
    "message": "Approved",
    "fraud_control_vendor_key": "7G2QB14W3Z9SH9MD6VKNRZWCY0"
  }

Post Authorization

Spreedly will asynchronously send a "Mode U" update to Kount with the results of the authorization. This can be viewed under "History" in the Kount Dashboard.

Fraud Detection During Card Add

You can also send information to Kount when you are creating a card via the API. For a full understanding of creating a payment method that includes an embedded fraud check, refer to adding a card in our Embedded Fraud Guide. Documented here are the items needed for a specific Kount integration.

When utilizing Kount as a Fraud vendor, it is important that your payment method API call contain the information required to receive an accurate fraud determination. This information can be sent in Spreedly's fields and in the Kount-specific fields.

Currently, Kount will only return fraud scores when adding the following payment methods via the API:

  • Credit Cards

Spreedly Mappings

The following fields, if sent with the payment method, will be sent to Kount. We recommend sending the most information available in order to get the most accurate fraud review.

  • email
  • shipping_address
  • billing_address
  • ip

Please note that Kount expects two character country codes in the addresses.

Kount-Specific Fields for Card Add

Kount requires cart information in addition to the session_id. Spreedly has also allowed any additional User Defined Fields to be passed via the vendor-specific fields. For the User Defined Fields, please provide the field and the value. 

"fraud_detection_parameters": {  
    "card_add_check": true,  
    "vendor_specific_fields": {  
      "kount":{
       "session_id":"<session id>",
        "user_defined_fields":{}
      },
      "cart_items": [
        {
          "desc": "Spreedly TEST Monitor",
          "item": "SpreedlTest_U4919DW",
          "price": "136999",
          "quantity": "1",
          "type": "Monitor"
        },
        {
          "desc": "Spreedly TEST Display Port Cable",
          "item": "SpreedlTest_DPC10FT",
          "price": "001",
          "quantity": "1",
          "type": "Cable"
        }
      ]
    }  
}

Response Fields

In addition to the standard fraud response fields, Spreedly will pass back raw information from Kount. Upon a successful response, the fraud_detection_card_check nest will contain information about the request. The vendor_response object will provide Kount fields.

These fields will be the same as returned during a pre-authorization response.

Kount Dashboard

Transactions with Kount initiated by Spreedly will display in the Kount dashboard. If you have questions about the Kount Dashboard about its functionality, please contact Kount Support or your Kount Customer Success representative.

Troubleshooting

Make sure that your Spreedly account is enabled for Embedded Fraud services. Please contact your Customer Success Manager to enable this service.

Validate that you are using sandbox credentials with a sandbox token or production credentials with a production token.

Kount provides detailed error messaging, which Spreedly returns in fraud_detection_pre_authorization.message.

Updated 2 months ago