This integration guide describes the process to integrate Kount Control. This includes a high-level overview of integration points and flow, and detailed technical specifications for relevant SDKs and the corresponding API.
Device Data Collector
The Device Data Collector (DDC) gathers information from a customer’s device by redirecting the device browser momentarily to Kount then back to the merchant. This passive analysis conceals the Kount interaction with the customer and does not affect the customer’s purchasing experience.
To ease DDC set up, use our guided DDC content generator or follow the steps below.
The DDC requires a two step process for mobile integration: Integration (Step 1) and Invocation (Step 2).
- Refer to How to Integrate the Kount Device Data Collector XCFramework Package into an iOS Application
- Refer to How to Integrate the Kount Device Data Collector CocoaPods Package into an iOS Application
- Refer to How to Integrate the Device Data Collector into Mobile SDKs using iOS Universal Static Library
- Refer to How to Integrate the Device Data Collector Swift Package Manager into an iOS Application
- Refer to How to Integrate the Device Data Collector into Mobile Apps using Android Gradle
- Refer to How to Integrate the Device Data Collector into Android Applications using the Library JAR
If you are developing for iOS and Android using a hybrid application refer to:
- How to Integrate the Device Data Collector into React Native Applications
- How to Integrate the Device Data Collector into Flutter Applications
DDC Browser Recommendations
Proper placement and configuration of the browser DDC is crucial in gathering information to identify devices, adhere to business policies, and accurately define login risk. Incorrect placement or misconfiguration can cause limited or no data collection.
Page and Page Location
Suggested placement of the DDC code is in the body of the login page. Kount reduces collection from the same sessionId when a collection comes within 15 minutes. However, it is strongly recommended that you run a single data collection per session. When multiple collections are run in a single session (if the collection was placed in the header, for example), it is possible the collection events can be mistaken as a DDOS attack, throttling all collections from your site.
Google Chrome Lazy Load
The Google Chrome “Lazy Load” feature defers loading images and iframes that come below the fold of the page. This feature is active when the Chrome Data Saver feature is on and when the loading attribute is set to auto or unset.
For customers using the Kount legacy data collector that utilizes an iframe, it is recommended to update integration or set the loading attribute to eager, which bypasses lazy loading functionality.
Content Security Policy
Kount utilizes both third-party and first-party cookies as well as device data to identify devices. In order to take full advantage of the DDC features, you might need to make modifications to the Content Security Policy on your site.
For more information on Content Security Policy and settings for the DDC, please contact your Kount Implementation Engineer.
- Info: https://api.kount.com/info/help/
- Login: https://api.kount.com/login/help/
- Event: https://api.kount.com/events/help/
- Trusted Device: https://api.kount.com/trusted-device/help/
- Secure MFA: https://api.kount.com/securemfa/help
Kount Control has two environments for integration:
- Sandbox – Full integration with test data
- Production – Full integration with Production data
Valid customer identification (clientID) and JWT credentials are required to make a call to any of the API endpoints (JWT credentials are not required for device data collection). These credentials are provided as part of technical integration.
The Sandbox environment is intended for user setup and integration testing. It includes a user interface so fraud analysts can set Profiles and Policies, research login event history, and run reports. It also includes all functionality of the current Production environment; however, it is not scalable like the Production environment.
The Production Environment is architected to handle full-scale production traffic.
It is recommended to parameterize the variables below to facilitate testing and to ease the move from one environment to another.
This token is supplied by Kount and is different from Sandbox to Production. As a parameter, this should facilitate testing.
The API host contains the location for the environment the post is being made to:
- Predictive Response Harness and Sandbox:
environmentDomain = “api-sandbox”
environmentDomain = “api”
While every attempt is made to prevent breaking changes to the API endpoints, it is recognized that there might be times when adding new functionality will cause breaking changes to occur. In those events, the version of API endpoint will increment.
It is important to use the proper data collection host to ensure that sessions are properly aligned between data collection and login requests.
dataCollectionHost = “https://tst.kaptcha.com”
dataCollectionHost = “https://ssl.kaptcha.com”
Device Info Endpoint
The Device Info Endpoint provides basic information related to the device including the device browser settings, geolocation, device language, network data, and the device ID. Refer to Info Endpoints for more information.
Login Event Workflow
The basic workflow of Kount Control starts with collecting data from the device. When the user logs in with valid credentials, the customer makes a post to the Kount Login API to get a response of Accept, Block, or Challenge.
Depending on the response based on your policies from Kount, the customer may either allow access, deny access, or challenge their user using their existing step-up authentication.
After the user’s login credentials have been posted to your authentication service, there are two paths:
Valid Credentials – If the user presented valid credentials, the customer posts to the Kount Login Decision API prior to granting access. The response to this API call is Allow, Block, or Challenge.
Invalid Credentials – If the user fails authentication, the customer declines access to the user and Post to the failed-attempt API. This API increases velocities and informs the Kount ML and AI models for future login attempts.
If the login decision results in a Challenge, it is imperative to send the outcome of the login challenge to Kount to better update our AI models and to update information for use within the portal.
The Login Endpoint can be found in the Kount Sandbox.
The API for the Failed Attempt and Login Challenge Outcome can be found in the Kount Sandbox.
Trusted Device Workflow
The Trusted Device Service may store a trust relationship between a device and a specific user.
Users typically employ a small handful of devices to log in (a cell phone, a work laptop, and a home computer). By identifying these devices for specific users, the customer may reduce friction at login using policies to only challenge users with a device not already known and trusted.
Example: A policy is created to Challenge a login coming from a user with a device not previously trusted for that user. Sandra logs in using her new cell phone. Because this cell phone is not trusted for her, the response from the Kount login event API is Challenge.
The customer asks Sandra to perform a step-up authentication (asking for her to input a code sent to her via text). She succeeds and is able to log into her account. When Sandra succeeds on the step-up challenge, the customer also sends an update to Kount to trust this device for Sandra. Kount stores this trust relationship so the next time Sandra logs in with this device, she would not be asked for step-up authentication.
There are several purpose-built endpoints available with the Trusted Device Service.
- Create Trusted Device Record: Used after a user has met a step-up challenge and the customer would like to store the trust state of the device for that user.
- Update Trusted Device Record: Used to alter the trust state between a device and a user. Options include trusted or banned. Typically, this is to ensure that a specific user cannot log in using a specific device.
- Read Trust States: Options to review information for all users connected to a device, all devices connected to a user, or the trust state for a specific user/device pair. May be used to identify a user before the user has logged into the site. Can also be used to allow typically used to display a list of trusted devices specific to the customer.
- Delete Trusted Device Record: Used to delete the record of a relationship between a user’s ID and a device. Typically used when there is a limited number of devices that can be used for a specific account and the user wants to replace one device for a new one.
Trust State Endpoint
The Trusted Device Endpoint can be found in the Kount Sandbox.