{"_id":"5b1972b45952df0003e8a70b","category":{"_id":"5b1972b45952df0003e8a6ea","version":"5b1972b45952df0003e8a725","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":7,"slug":"topics","title":"Guides"},"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","parentDoc":null,"version":{"_id":"5b1972b45952df0003e8a725","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5addef809a4b8c0003207f4c","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z","categories":["5b1972b45952df0003e8a6e3","5b1972b45952df0003e8a6e4","5b1972b45952df0003e8a6e5","5b1972b45952df0003e8a6e6","5b1972b45952df0003e8a6e7","5b1972b45952df0003e8a6e8","5b1972b45952df0003e8a6e9","5b1972b45952df0003e8a6ea"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.26 Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-16T18:09:20.576Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"Failing to stop fraudulent transactions can lead to higher chargebacks and chargeback-related expenses, in addition to lost merchandise. BlueSnap has partnered with Kount to analyze customer data and purchase behavior on every transaction to identify and stop fraudulent orders.\n\nLearn more about:\n  * [Service levels](#section-service-levels): The three fraud prevention service levels offered by BlueSnap\n  * [AVS and CVV fraud rules](#section-avs-and-cvv-fraud-rules): These rules are available to all merchants, and apply to all United States credit card and debit card transactions.\n  * [Device data checks](#section-device-data-checks): Some of the most critical fraud prevention rules depend on information related to the shopper’s device. All merchants that use our API are required to add the BlueSnap JavaScript iFrame to their checkout pages in order to enable device data checks.\n  * [Site IDs and user defined fields](#section-site-ids-and-user-defined-fields): If you are using the Enterprise level fraud prevention service, you can configure these additional fields directly in Kount and then include them in your API requests\n  * Fraud errors: When a transaction triggers fraud rules, BlueSnap returns error 15011 FRAUD_DETECTED, with information about what type of fraud rule was triggered and why.\n   See [Payment API Fraud Errors](/v8976-JSON/docs/fraud-errors) or [Extended Payment API Fraud Errors](/v8976-Extended/docs/fraud-errors).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Fraud analysis is based only on the fields that BlueSnap receives. If you define a fraud rule based on a field that you don't pass to BlueSnap, then that fraud rule will be ignored. For example, if you set an fraud rule that uses the billing address but you do not include the billing address on the checkout form, then this fraud rule will not be applied.\\n\\nNote that there are some fields that may be optional for order processing, depending on your BlueSnap integration type. These include Shopper Email, Shipping Address, Billing Address, CVV, and device data. If you configure fraud rules using any of these optional fields, you should verify that you include these fields in the checkout form so that the data will be passed to BlueSnap and your fraud rules will work.\",\n  \"title\": \"Fraud rules run based on data you pass to BlueSnap\"\n}\n[/block]\n##Service levels\nBlueSnap offers three levels of enhanced fraud prevention services, which provide different capabilities and opportunities for customization. Below is a summary of each level. For more in-depth information about each one, see [Fraud prevention service levels](http://support.bluesnap.com/docs/fraud-prevention-services).\n \n**Managed**\nBlueSnap’s Managed fraud prevention service is enabled on your account by default. We use the most sophisticated fraud detection technology available to analyze every transaction for fraud indicators. Based on the results, we will either accept or reject each transaction.\n\n**Merchant Configurable**\nThis service level is ideal for merchants that would like to customize thresholds for key fraud rules. This service is available to all merchants for a monthly fee. Contact support ([merchants:::at:::bluesnap.com](mailto:merchants@bluesnap.com)) or your account manager for more details. For setup information, see [Merchant Configurable service setup & reporting](http://support.bluesnap.com/docs/merchant-configurable-service).\n\n**Enterprise**\nThis service level is designed for merchants that want to customize their fraud prevention strategy, from creating and maintaining fraud rules, to manually reviewing transactions. Merchants signed up for this service will manage their entire fraud strategy directly in Kount’s Agent Web Console. If you are interested in the Enterprise fraud prevention service, please contact us to discuss pricing and availability.\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##AVS and CVV fraud rules\nAll merchants can use the Address Verification Service (AVS) and Card Verification Value (CVV) fraud tools at no additional cost. These rules apply to credit card and debit card transactions only, and do not apply to recurring payments.\n \n**How it works**\nWhen you submit a transaction request for a credit or debit card, BlueSnap passes the address and CVV information as entered by the cardholder to the issuing bank. The bank’s response will usually include AVS and CVV response codes. These codes indicate whether the numeric values in the address and CVV match their records for that cardholder.\n\nMany banks approve transactions even if the address information or CVV included with the order does not match what they have on file for that cardholder. Banks approve these transactions because they often have the right to chargeback the purchase to the merchant if the transaction is later determined to be fraudulent; and this costs you money.\n\nAVS rules are particularly useful for merchants that ship physical merchandise. If the issuing bank’s response triggers one of your AVS or CVV rules, we send a void request to the issuing bank. Alternatively, if you choose not to enable AVS or CVV rules, BlueSnap will not take any action based on the response codes.\n\n**Setup**\n See [Enabling AVS and CVV rules](http://support.bluesnap.com/docs/setting-up-avs-and-cvv#section-enabling-avs-and-cvv-rules).\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Device data checks\nSome of the most critical fraud prevention rules depend on information related to the shopper’s device. All merchants that use our API are required to add the BlueSnap JavaScript iFrame to their checkout pages. This small change greatly improves BlueSnap’s ability to detect fraudulent transactions by gathering device-specific information.\n\nThe JavaScript will collect information about the shopper’s device and pass it to BlueSnap. The information being collected includes:\n  * browser settings\n  * operating system and other software version numbers\n  * cookies\n  * cache IDs\n\nThis data will be used to stop fraud by identifying when multiple people are using the same device, a shopper is trying to hide their identity, a known fraudster is submitting an order, or a shopper’s account has been taken over by a fraudster. Alternatively, device data can also identify trusted customers when they return to your website.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"The instructions directly below describe how to implement device data checks with the BlueSnap Mobile SDK. For instructions on how you can integrate the Kount Data Collector in your mobile app, see [Implementing Kount's SDK for Android](https://developers.bluesnap.com/v8976-Basics/docs/fraud-prevention#section-implementing-kount-s-sdk-for-android) and [Implementing Kount's SDK for iOS](https://developers.bluesnap.com/v8976-Basics/docs/fraud-prevention#section-implementing-kount-s-sdk-for-ios), later in this section.\\n\\nMake sure you use BlueSnap's Kount Merchant ID (700000) and start the Data Collector *prior *to starting the checkout process.\"\n}\n[/block]\n###Implementing device data with the BlueSnap Mobile SDK###\n\nImplementing this data is performed in a quick three-step process:\n\n###Step 1: Create a Fraud Session ID\nThe Fraud Session ID allows BlueSnap to link a shopper’s device data with order details for analysis. This identifier must be unique for at least 30 days and must be unique for every transaction submitted by each unique customer. If a single session ID were to be used on multiple transactions, those transactions would link together and erroneously affect the fraud analysis.\n\nThe Fraud Session ID may contain up to 32 characters. You can use the UUID if you remove the hyphens (otherwise it would be 36 characters), or you can create your own Session ID. The Fraud Session ID should contain alpha-numeric characters only.\n\n###Step 2: Embed BlueSnap Data in your checkout page\nInsert the following HTML code into your payment page:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<iframe width='1' height='1' frameborder='0' scrolling='no' src='https://www.bluesnap.com/servlet/logo.htm?s=fbcc094208f54c0e974d56875c73af7a'>\\n     <img width='1' height='1' src='https://www.bluesnap.com/servlet/logo.gif?s=fbcc094208f54c0e974d56875c73af7a'>\\n</iframe>\",\n      \"language\": \"html\",\n      \"name\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"`fbcc094208f54c0e974d56875c73af7a` is an example Session ID. You should insert your own Fraud Session ID from Step 1 here. If the Fraud Session ID parameter is missing or invalid (longer than 32 characters), the logo.htm and logo.gif URLs will return HTTP error 400 (Bad Input).\",\n  \"title\": \"Insert your own Session ID\"\n}\n[/block]\n###Step 3: Add the Fraud Session ID to your API call\nYou also need to pass your Fraud Session ID as part of your API call, as follows:\n\n**Payment API**\nIn the Payment API, the Fraud Session ID should be passed in the `fraudSessionId` property within the [transactionFraudInfo](/v8976-JSON/docs/transaction-fraud-info) object. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"    \\\"transactionFraudInfo\\\": {\\n        \\\"fraudSessionId\\\": 1234\\n    }\",\n      \"language\": \"json\",\n      \"name\": \"fraudSessionId in the Payment API\"\n    }\n  ]\n}\n[/block]\n**Extended Payment API**\nIn the Extended Payment API, the Fraud Session ID should be passed in the `fraud-session-id` property within the [fraud-info](/v8976-Extended/docs/fraud-info) resource. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<fraud-info>\\n  <fraud-session-id>1234567890</fraud-session-id>\\n</fraud-info>\",\n      \"language\": \"xml\",\n      \"name\": \"fraud-session-id in the Extended Payment API\"\n    }\n  ]\n}\n[/block]\n###Implementing Kount's SDK for Android###\n\nKount's SDK for Android helps integrate Kount's fraud fighting solution into your Android app.\n\n**Requirements:**\n\n* Kount integration\n* Android Studio and Android SDK\n* Target Android SDK >= 10\n* Instant App support dependency (if using version 3.3.0 and higher). You must include the Instant App library at compile time; even if you are not building an Instant App (see **Instant App Dependencies** below for more information).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"Due to the restrictions imposed on Instant Apps by Android, Instant App collection may be degraded compared to a full Android App.\"\n}\n[/block]\n**Installation:**\n\nDownload the Kount Android SDK and unzip the file in a folder separate from your project\n* Copy the JAR file in the KountDataCollector folder into the **libs **folder of your app\n\n**Initialization:**\n\nTo set up the Data Collector, you'll need to set the context, the merchant ID, configuration for location collection, and the Kount environment. While testing your integration, use the *Test *environment, switching to *Production *when your app is ready to release.\n\n**Setup:**\nIn the main activity of your app, add the following initialization:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.kount.api.DataCollector;\\n          \\n@Override\\nprotected void onCreate(Bundle savedInstanceState) {\\n  ...\\n  DataCollector.getInstance().setContext(this);\\n  DataCollector.getInstance().setMerchantID(<MERCHANT_ID>);\\n  DataCollector.getInstance().setLocationCollectorConfig(DataCollector.LocationConfig.COLLECT);\\n  // For Test Environment\\n  DataCollector.getInstance().setEnvironment(DataCollector.ENVIRONMENT_TEST);\\n  // For Production Environment\\n  // DataCollector.getInstance().setEnvironment(DataCollector.ENVIRONMENT_PRODUCTION);\\n  ...\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Location Permissions:**\nFor location collection support, you'll need to add these permissions to your **AndroidManifest.xml** file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<uses-permission android:name=\\\"android.permission.INTERNET\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_NETWORK_STATE\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_WIFI_STATE\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_FINE_LOCATION\\\" />\\n<uses-permission android:name=\\\"android.permission.ACCESS_COARSE_LOCATION\\\" />\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nFor Android API >= 23, you'll also need to add permission requesting code to your main activity, similar to the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"...\\nif (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {\\n  if (ActivityCompat.shouldShowRequestPermissionRationale(this, Manifest.permission.ACCESS_FINE_LOCATION)) {\\n    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, <REQUEST_ID>);\\n  } else {\\n    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, <REQUEST_ID>);\\n  }\\n}\\n...\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Collection:**\n\nEarly in the checkout process, start the data collection with a unique session ID tied to the transaction, and collect once per unique session ID.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"Only run collection during the checkout process (and the call should be made early in the collection process). Calling collection outside of the checkout process may result in a high proportion of collection to RIS calls. This may be misinterpreted by our services as a DDOS attack. While this is rare, we highlight this to emphasize the importance that collection only be placed at the beginning of the checkout process.\\n\\nBelow is an example adding the controller to the onCreate method:\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.kount.api.DataCollector;\\n            \\n@Override\\nprotected void onCreate(Bundle savedInstanceState) {\\n  ...\\n  DataCollector.getInstance().collectForSession(sessionID, new DataCollector.CompletionHandler() {\\n   /* Add handler code here if desired. The handler is optional. */\\n    @Override\\n    public void completed(String sessionID) {\\n    }\\n    @Override\\n    public void failed(String sessionID, final DataCollector.Error error) {\\n    }\\n  });\\n  ...\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**Example:**\n\nOpen the `CheckoutExample` folder in Android Studio to see a simple example of using the SDK.\n\n**Migrating to version 3.x:**\n\nThe interface and workflow of the SDK has changed between version 2 and version 3. The old version would have you create an instance of the Data Collector, configure it, make a call to collect, and then implement the listener methods if you wished to receive feedback regarding the collection.\n\nWith the new version, the Data Collector is implemented as a singleton and is configured when your main activity is created. The collect call is now a method on the Data Collector singleton and has an optional completion handler interface argument you can implement if you wish to get additional information on the collection. Here are the steps to upgrade to version 3.x:\n\n* Remove the old library from your project and replace it with the new library.\n* Remove the old initialization code and replace it with the new initialization code methods on the DataCollector singleton in your main activity.\n* Remove the old call to collect and corresponding listener methods and replace it with the collect method on the DataCollector singleton, and optionally implement the completion handler interface.\n* Be certain that the call to collect is made at the beginning of the checkout process.\n\n**Instant App dependencies:**\nIf your application is not also an Instant App, you will need to include the Instant App library during compile time to your project. This can be done in Android Studio by adding the following line in your module's gradle file under the dependency section:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"dependencies {\\n    compile 'com.google.android.instantapps:instantapps:1.1.0'\\n...\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n###Implementing Kount's SDK for iOS###\n\nKount's SDK for iOS helps integrate Kount's fraud fighting solution into your iOS app.\n\n**Requirements:**\n\n* Kount integration\n* Xcode 8 and iOS 10 SDK\n* iOS 8.0+ deployment target\n\n**Installation:**\n\nDownload the Kount iOS SDK and unzip the file in a folder separate from your project.\n\nOpen your app in Xcode. In Finder, drag the KountDataCollector folder into the top level of your project, and check **Copy If Needed**. Modify your build settings in **App Target > Build Settings**. Update Header Search Paths:\n\n* Add `$(PROJECT_DIR)/KountDataCollector`\n\n**Initialization:**\n\nTo set up the Data Collector, you'll need to set the merchant ID, configuration for location collection, and the Kount environment. While testing your integration you'll want to use the *Test *environment, switching to *Production *when your app is ready to release.\n\n**Setup:**\nIn your AppDelegate add the initialization code:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import \\\"KDataCollector.h\\\"\\n              \\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\\n  ...\\n  [[KDataCollector sharedCollector] setMerchantID:<MERCHANT_ID>]; \\n  [[KDataCollector sharedCollector] setLocationCollectorConfig:KLocationCollectorConfigRequestPermission];\\n  // For Test Environment\\n  [[KDataCollector sharedCollector] setEnvironment:KEnvironmentTest];\\n  // For Production Environment\\n  //[[KDataCollector sharedCollector] setEnvironment:KEnvironmentProduction];\\n  ...\\n}\",\n      \"language\": \"objectivec\",\n      \"name\": \"Objective-C\"\n    },\n    {\n      \"code\": \"func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {\\n  ...\\n        KDataCollector.shared().merchantID = <MERCHANT_ID>\\n        KDataCollector.shared().locationCollectorConfig = KLocationCollectorConfig.requestPermission\\n        // For test Environment\\n        KDataCollector.shared().environment = KEnvironment.test\\n        // For Production Environment\\n        // KDataCollector.shared().environment = KEnvironment.production\\n  ...\\n}\",\n      \"language\": \"swift\",\n      \"name\": \"Swift\"\n    }\n  ]\n}\n[/block]\n**Location Permissions:**\nFor location collection support, you'll need to add this key to your **Info.plist** file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<key>NSLocationWhenInUseUsageDescription</key>\\n<string></string>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf you choose `KLocationCollectorConfigRequestPermission`, the collector will request permission for you, if needed. If you choose `KLocationCollectorConfigPassive`, the collector will only gather location information if your app has requested permission and the user has granted it permission.\n\n**Collection:**\n\nEarly in the checkout process, start the data collection with a unique session ID tied to the transaction, and collect once per unique session ID.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note:\",\n  \"body\": \"Only run collection during the checkout process (and the call should be made early in the collection process). Calling collection outside of the checkout process may result in a high proportion of collection to RIS calls. This may be misinterpreted by our services as a DDOS attack. While this is rare, we highlight this to emphasize the importance that collection only be placed at the beginning of the checkout process.\"\n}\n[/block]\nBelow is an example adding the controller to the viewDidAppear method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import \\\"KDataCollector.h\\\"\\n\\n- (void)viewDidAppear:(BOOL)animated {\\n  ...\\n  [[KDataCollector sharedCollector] collectForSession:<SESSION_ID> \\n                                           completion:^(NSString * _Nonnull sessionID,  \\n                                                        BOOL success, \\n                                                        NSError * _Nullable error) {\\n    // Add handler code here if desired. The completion block is optional.\\n  }];\\n  ...\\n}\",\n      \"language\": \"objectivec\",\n      \"name\": \"Objective-C\"\n    },\n    {\n      \"code\": \"override func viewDidAppear(animated: Bool) {\\n  ...\\n        KDataCollector.shared().collect(forSession: <SESSION_ID>) { (sessionID, success, error) in\\n            // Add handler code here if desired. The completion block is optional.\\n        }\\n  ...\\n}\",\n      \"language\": \"swift\",\n      \"name\": \"Swift\"\n    }\n  ]\n}\n[/block]\n**Examples:**\n\nOpen `Examples.xcworkspace` in Xcode to open up the workspace with the following example projects:\n\n**CheckoutExampleObj**\nA simple example of using the SDK in an Objective C project.\n\n**CheckoutExampleSwift**\nA simple example of using the SDK in a Swift project.\n\n**Migrating to version 3.x:**\n\nThe interface and workflow of the SDK has changed between version 2 and version 3. The old version would have you create an instance of the Data Collector, configure it, make a call to collect, and then implement the delegate methods if you wished to receive feedback regarding the collection.\n\nWith the new version, the Data Collector is implemented as a singleton and is configured when your app is created. The collect call is now a method on the Data Collector singleton and has an optional callback block you can implement if you wish to get additional information on the collection. Here are the steps to upgrade to version 3.x:\n\n* Remove the old library and header file from your project and replace it with the new library and header file.\n* Remove the old initialization code and replace it with the new initialization code methods on the DataCollector singleton in your AppDelegate.\n* Remove the old call to collect and corresponding delegate methods and replace it with the collect method on the DataCollector singleton, and optionally implement the completion block.\n* Be certain that the call to collect is made at the beginning of the checkout process.\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Site IDs and user defined fields\nIf you are using the Enterprise level fraud prevention service, you can configure these additional fields directly in Kount and then include them in your API requests:\n  * [Site IDs](#section-site-ids)\n  * [User defined fields (UDFs)](#section-user-defined-fields-udfs-)\n\n###Site IDs\nA Site ID (or Website ID) is a custom field used to classify orders for rule creation or for order review. \n\nFor example, you might notice that fraud patterns differ by geographic region. Site IDs allow you to define specific fraud rules for your U.K., U.S., and Canadian websites.\n\nTo manage Site IDs, go to **Fraud Control > Websites** in the Kount web console.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/NqB20VOMRiuvUYciMtNh_site-id-kount.png\",\n        \"site-id-kount.png\",\n        \"1346\",\n        \"382\",\n        \"#bc813a\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nTo implement a Site, define the Site ID in the Kount web console. When you add a Site ID, you will be prompted to assign it a name and a brief description. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3F9hoHLGQgWBvAEZxoXw_site-id-kount2.png\",\n        \"site-id-kount2.png\",\n        \"1365\",\n        \"522\",\n        \"#3e5176\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nOnce you have defined the Site IDs in Kount, then you can pass this data in your BlueSnap API calls, in the `enterpriseSiteId` property within the [transactionFraudInfo](/v8976-JSON/docs/transaction-fraud-info) object in the Payment API or within the [fraud-info](/v8976-Extended/docs/fraud-info) resource in the Extended Payment API. The Enterprise Site ID passed to BlueSnap must exactly match an existing Site ID in Kount. Only one Site ID should be passed for each transaction.\n\n###User defined fields (UDFs)\nUser defined fields (UDFs) allow you to pass information related to an order or shopper that may not be a standard field in Kount. User defined fields can be referenced when creating a fraud rule or simply made available for reference when reviewing suspicious orders.\n\nFor example, it might be helpful to pass an indication of the shopper’s membership in a premium rewards program.  \n\nTo manage Site IDs, go to **Fraud Control > User Defined Fields** in the Kount web console.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/D3cGvua2RSy8P7Rq5eun_site-id-kount.png\",\n        \"site-id-kount.png\",\n        \"1346\",\n        \"382\",\n        \"#bc813a\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nTo implement a user defined field, define the UDF in the Kount web console. When you add a UDF, you will be prompted to assign it a label and a brief description. Each UDF must also be defined as either a number, alpha-numeric, a date, or amount.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Np2sxQU8Q3auhfpo698Z_udf-kount.png\",\n        \"udf-kount.png\",\n        \"110\",\n        \"159\",\n        \"#e5e6e9\",\n        \"\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\nFor example, if you want to set up a UDF for reward membership, you might configure the UDF as follows:\n\n  * Label: PremiumRewardsMember\n  * Description: Is a member of our premium rewards program\n  * Type: Alpha-Numeric \n\nIn the value, you could pass “Yes” to indicate a member and “No” to indicate a non-member.\n\nOnce you have defined the UDF in Kount, then you can pass this data in your BlueSnap API calls, in the `enterpriseUdfs` resource within the [transactionFraudInfo](/v8976-JSON/docs/transaction-fraud-info) resource in the Payment API or within the [fraud-info](/v8976-Extended/docs/fraud-info) resource in the Extended Payment API. The UDF name passed to BlueSnap must exactly match an existing UDF label.\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"Learn about the tools BlueSnap offers to help detect and prevent fraudulent orders.","slug":"fraud-prevention","type":"basic","title":"Fraud Prevention"}

Fraud Prevention

Learn about the tools BlueSnap offers to help detect and prevent fraudulent orders.

Failing to stop fraudulent transactions can lead to higher chargebacks and chargeback-related expenses, in addition to lost merchandise. BlueSnap has partnered with Kount to analyze customer data and purchase behavior on every transaction to identify and stop fraudulent orders.

Learn more about:

  • Service levels: The three fraud prevention service levels offered by BlueSnap
  • AVS and CVV fraud rules: These rules are available to all merchants, and apply to all United States credit card and debit card transactions.
  • Device data checks: Some of the most critical fraud prevention rules depend on information related to the shopper’s device. All merchants that use our API are required to add the BlueSnap JavaScript iFrame to their checkout pages in order to enable device data checks.
  • Site IDs and user defined fields: If you are using the Enterprise level fraud prevention service, you can configure these additional fields directly in Kount and then include them in your API requests
  • Fraud errors: When a transaction triggers fraud rules, BlueSnap returns error 15011 FRAUD_DETECTED, with information about what type of fraud rule was triggered and why.
    See Payment API Fraud Errors or Extended Payment API Fraud Errors.

Fraud rules run based on data you pass to BlueSnap

Fraud analysis is based only on the fields that BlueSnap receives. If you define a fraud rule based on a field that you don't pass to BlueSnap, then that fraud rule will be ignored. For example, if you set an fraud rule that uses the billing address but you do not include the billing address on the checkout form, then this fraud rule will not be applied.

Note that there are some fields that may be optional for order processing, depending on your BlueSnap integration type. These include Shopper Email, Shipping Address, Billing Address, CVV, and device data. If you configure fraud rules using any of these optional fields, you should verify that you include these fields in the checkout form so that the data will be passed to BlueSnap and your fraud rules will work.

Service levels

BlueSnap offers three levels of enhanced fraud prevention services, which provide different capabilities and opportunities for customization. Below is a summary of each level. For more in-depth information about each one, see Fraud prevention service levels.

Managed
BlueSnap’s Managed fraud prevention service is enabled on your account by default. We use the most sophisticated fraud detection technology available to analyze every transaction for fraud indicators. Based on the results, we will either accept or reject each transaction.

Merchant Configurable
This service level is ideal for merchants that would like to customize thresholds for key fraud rules. This service is available to all merchants for a monthly fee. Contact support (merchants@bluesnap.com) or your account manager for more details. For setup information, see Merchant Configurable service setup & reporting.

Enterprise
This service level is designed for merchants that want to customize their fraud prevention strategy, from creating and maintaining fraud rules, to manually reviewing transactions. Merchants signed up for this service will manage their entire fraud strategy directly in Kount’s Agent Web Console. If you are interested in the Enterprise fraud prevention service, please contact us to discuss pricing and availability.



Back to Top

AVS and CVV fraud rules

All merchants can use the Address Verification Service (AVS) and Card Verification Value (CVV) fraud tools at no additional cost. These rules apply to credit card and debit card transactions only, and do not apply to recurring payments.

How it works
When you submit a transaction request for a credit or debit card, BlueSnap passes the address and CVV information as entered by the cardholder to the issuing bank. The bank’s response will usually include AVS and CVV response codes. These codes indicate whether the numeric values in the address and CVV match their records for that cardholder.

Many banks approve transactions even if the address information or CVV included with the order does not match what they have on file for that cardholder. Banks approve these transactions because they often have the right to chargeback the purchase to the merchant if the transaction is later determined to be fraudulent; and this costs you money.

AVS rules are particularly useful for merchants that ship physical merchandise. If the issuing bank’s response triggers one of your AVS or CVV rules, we send a void request to the issuing bank. Alternatively, if you choose not to enable AVS or CVV rules, BlueSnap will not take any action based on the response codes.

Setup
See Enabling AVS and CVV rules.



Back to Top

Device data checks

Some of the most critical fraud prevention rules depend on information related to the shopper’s device. All merchants that use our API are required to add the BlueSnap JavaScript iFrame to their checkout pages. This small change greatly improves BlueSnap’s ability to detect fraudulent transactions by gathering device-specific information.

The JavaScript will collect information about the shopper’s device and pass it to BlueSnap. The information being collected includes:

  • browser settings
  • operating system and other software version numbers
  • cookies
  • cache IDs

This data will be used to stop fraud by identifying when multiple people are using the same device, a shopper is trying to hide their identity, a known fraudster is submitting an order, or a shopper’s account has been taken over by a fraudster. Alternatively, device data can also identify trusted customers when they return to your website.

Note:

The instructions directly below describe how to implement device data checks with the BlueSnap Mobile SDK. For instructions on how you can integrate the Kount Data Collector in your mobile app, see Implementing Kount's SDK for Android and Implementing Kount's SDK for iOS, later in this section.

Make sure you use BlueSnap's Kount Merchant ID (700000) and start the Data Collector prior to starting the checkout process.

Implementing device data with the BlueSnap Mobile SDK

Implementing this data is performed in a quick three-step process:

Step 1: Create a Fraud Session ID

The Fraud Session ID allows BlueSnap to link a shopper’s device data with order details for analysis. This identifier must be unique for at least 30 days and must be unique for every transaction submitted by each unique customer. If a single session ID were to be used on multiple transactions, those transactions would link together and erroneously affect the fraud analysis.

The Fraud Session ID may contain up to 32 characters. You can use the UUID if you remove the hyphens (otherwise it would be 36 characters), or you can create your own Session ID. The Fraud Session ID should contain alpha-numeric characters only.

Step 2: Embed BlueSnap Data in your checkout page

Insert the following HTML code into your payment page:

<iframe width='1' height='1' frameborder='0' scrolling='no' src='https://www.bluesnap.com/servlet/logo.htm?s=fbcc094208f54c0e974d56875c73af7a'>
     <img width='1' height='1' src='https://www.bluesnap.com/servlet/logo.gif?s=fbcc094208f54c0e974d56875c73af7a'>
</iframe>

Insert your own Session ID

fbcc094208f54c0e974d56875c73af7a is an example Session ID. You should insert your own Fraud Session ID from Step 1 here. If the Fraud Session ID parameter is missing or invalid (longer than 32 characters), the logo.htm and logo.gif URLs will return HTTP error 400 (Bad Input).

Step 3: Add the Fraud Session ID to your API call

You also need to pass your Fraud Session ID as part of your API call, as follows:

Payment API
In the Payment API, the Fraud Session ID should be passed in the fraudSessionId property within the transactionFraudInfo object. For example:

    "transactionFraudInfo": {
        "fraudSessionId": 1234
    }

Extended Payment API
In the Extended Payment API, the Fraud Session ID should be passed in the fraud-session-id property within the fraud-info resource. For example:

<fraud-info>
  <fraud-session-id>1234567890</fraud-session-id>
</fraud-info>

Implementing Kount's SDK for Android

Kount's SDK for Android helps integrate Kount's fraud fighting solution into your Android app.

Requirements:

  • Kount integration
  • Android Studio and Android SDK
  • Target Android SDK >= 10
  • Instant App support dependency (if using version 3.3.0 and higher). You must include the Instant App library at compile time; even if you are not building an Instant App (see Instant App Dependencies below for more information).

Note:

Due to the restrictions imposed on Instant Apps by Android, Instant App collection may be degraded compared to a full Android App.

Installation:

Download the Kount Android SDK and unzip the file in a folder separate from your project

  • Copy the JAR file in the KountDataCollector folder into the libs folder of your app

Initialization:

To set up the Data Collector, you'll need to set the context, the merchant ID, configuration for location collection, and the Kount environment. While testing your integration, use the Test environment, switching to Production when your app is ready to release.

Setup:
In the main activity of your app, add the following initialization:

import com.kount.api.DataCollector;
          
@Override
protected void onCreate(Bundle savedInstanceState) {
  ...
  DataCollector.getInstance().setContext(this);
  DataCollector.getInstance().setMerchantID(<MERCHANT_ID>);
  DataCollector.getInstance().setLocationCollectorConfig(DataCollector.LocationConfig.COLLECT);
  // For Test Environment
  DataCollector.getInstance().setEnvironment(DataCollector.ENVIRONMENT_TEST);
  // For Production Environment
  // DataCollector.getInstance().setEnvironment(DataCollector.ENVIRONMENT_PRODUCTION);
  ...
}

Location Permissions:
For location collection support, you'll need to add these permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

For Android API >= 23, you'll also need to add permission requesting code to your main activity, similar to the following:

...
if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
  if (ActivityCompat.shouldShowRequestPermissionRationale(this, Manifest.permission.ACCESS_FINE_LOCATION)) {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, <REQUEST_ID>);
  } else {
    ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, <REQUEST_ID>);
  }
}
...

Collection:

Early in the checkout process, start the data collection with a unique session ID tied to the transaction, and collect once per unique session ID.

Note:

Only run collection during the checkout process (and the call should be made early in the collection process). Calling collection outside of the checkout process may result in a high proportion of collection to RIS calls. This may be misinterpreted by our services as a DDOS attack. While this is rare, we highlight this to emphasize the importance that collection only be placed at the beginning of the checkout process.

Below is an example adding the controller to the onCreate method:

import com.kount.api.DataCollector;
            
@Override
protected void onCreate(Bundle savedInstanceState) {
  ...
  DataCollector.getInstance().collectForSession(sessionID, new DataCollector.CompletionHandler() {
   /* Add handler code here if desired. The handler is optional. */
    @Override
    public void completed(String sessionID) {
    }
    @Override
    public void failed(String sessionID, final DataCollector.Error error) {
    }
  });
  ...
}

Example:

Open the CheckoutExample folder in Android Studio to see a simple example of using the SDK.

Migrating to version 3.x:

The interface and workflow of the SDK has changed between version 2 and version 3. The old version would have you create an instance of the Data Collector, configure it, make a call to collect, and then implement the listener methods if you wished to receive feedback regarding the collection.

With the new version, the Data Collector is implemented as a singleton and is configured when your main activity is created. The collect call is now a method on the Data Collector singleton and has an optional completion handler interface argument you can implement if you wish to get additional information on the collection. Here are the steps to upgrade to version 3.x:

  • Remove the old library from your project and replace it with the new library.
  • Remove the old initialization code and replace it with the new initialization code methods on the DataCollector singleton in your main activity.
  • Remove the old call to collect and corresponding listener methods and replace it with the collect method on the DataCollector singleton, and optionally implement the completion handler interface.
  • Be certain that the call to collect is made at the beginning of the checkout process.

Instant App dependencies:
If your application is not also an Instant App, you will need to include the Instant App library during compile time to your project. This can be done in Android Studio by adding the following line in your module's gradle file under the dependency section:

dependencies {
    compile 'com.google.android.instantapps:instantapps:1.1.0'
...
}

Implementing Kount's SDK for iOS

Kount's SDK for iOS helps integrate Kount's fraud fighting solution into your iOS app.

Requirements:

  • Kount integration
  • Xcode 8 and iOS 10 SDK
  • iOS 8.0+ deployment target

Installation:

Download the Kount iOS SDK and unzip the file in a folder separate from your project.

Open your app in Xcode. In Finder, drag the KountDataCollector folder into the top level of your project, and check Copy If Needed. Modify your build settings in App Target > Build Settings. Update Header Search Paths:

  • Add $(PROJECT_DIR)/KountDataCollector

Initialization:

To set up the Data Collector, you'll need to set the merchant ID, configuration for location collection, and the Kount environment. While testing your integration you'll want to use the Test environment, switching to Production when your app is ready to release.

Setup:
In your AppDelegate add the initialization code:

#import "KDataCollector.h"
              
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  ...
  [[KDataCollector sharedCollector] setMerchantID:<MERCHANT_ID>]; 
  [[KDataCollector sharedCollector] setLocationCollectorConfig:KLocationCollectorConfigRequestPermission];
  // For Test Environment
  [[KDataCollector sharedCollector] setEnvironment:KEnvironmentTest];
  // For Production Environment
  //[[KDataCollector sharedCollector] setEnvironment:KEnvironmentProduction];
  ...
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  ...
        KDataCollector.shared().merchantID = <MERCHANT_ID>
        KDataCollector.shared().locationCollectorConfig = KLocationCollectorConfig.requestPermission
        // For test Environment
        KDataCollector.shared().environment = KEnvironment.test
        // For Production Environment
        // KDataCollector.shared().environment = KEnvironment.production
  ...
}

Location Permissions:
For location collection support, you'll need to add this key to your Info.plist file:

<key>NSLocationWhenInUseUsageDescription</key>
<string></string>

If you choose KLocationCollectorConfigRequestPermission, the collector will request permission for you, if needed. If you choose KLocationCollectorConfigPassive, the collector will only gather location information if your app has requested permission and the user has granted it permission.

Collection:

Early in the checkout process, start the data collection with a unique session ID tied to the transaction, and collect once per unique session ID.

Note:

Only run collection during the checkout process (and the call should be made early in the collection process). Calling collection outside of the checkout process may result in a high proportion of collection to RIS calls. This may be misinterpreted by our services as a DDOS attack. While this is rare, we highlight this to emphasize the importance that collection only be placed at the beginning of the checkout process.

Below is an example adding the controller to the viewDidAppear method:

#import "KDataCollector.h"

- (void)viewDidAppear:(BOOL)animated {
  ...
  [[KDataCollector sharedCollector] collectForSession:<SESSION_ID> 
                                           completion:^(NSString * _Nonnull sessionID,  
                                                        BOOL success, 
                                                        NSError * _Nullable error) {
    // Add handler code here if desired. The completion block is optional.
  }];
  ...
}
override func viewDidAppear(animated: Bool) {
  ...
        KDataCollector.shared().collect(forSession: <SESSION_ID>) { (sessionID, success, error) in
            // Add handler code here if desired. The completion block is optional.
        }
  ...
}

Examples:

Open Examples.xcworkspace in Xcode to open up the workspace with the following example projects:

CheckoutExampleObj
A simple example of using the SDK in an Objective C project.

CheckoutExampleSwift
A simple example of using the SDK in a Swift project.

Migrating to version 3.x:

The interface and workflow of the SDK has changed between version 2 and version 3. The old version would have you create an instance of the Data Collector, configure it, make a call to collect, and then implement the delegate methods if you wished to receive feedback regarding the collection.

With the new version, the Data Collector is implemented as a singleton and is configured when your app is created. The collect call is now a method on the Data Collector singleton and has an optional callback block you can implement if you wish to get additional information on the collection. Here are the steps to upgrade to version 3.x:

  • Remove the old library and header file from your project and replace it with the new library and header file.
  • Remove the old initialization code and replace it with the new initialization code methods on the DataCollector singleton in your AppDelegate.
  • Remove the old call to collect and corresponding delegate methods and replace it with the collect method on the DataCollector singleton, and optionally implement the completion block.
  • Be certain that the call to collect is made at the beginning of the checkout process.



Back to Top

Site IDs and user defined fields

If you are using the Enterprise level fraud prevention service, you can configure these additional fields directly in Kount and then include them in your API requests:

Site IDs

A Site ID (or Website ID) is a custom field used to classify orders for rule creation or for order review.

For example, you might notice that fraud patterns differ by geographic region. Site IDs allow you to define specific fraud rules for your U.K., U.S., and Canadian websites.

To manage Site IDs, go to Fraud Control > Websites in the Kount web console.

To implement a Site, define the Site ID in the Kount web console. When you add a Site ID, you will be prompted to assign it a name and a brief description.

Once you have defined the Site IDs in Kount, then you can pass this data in your BlueSnap API calls, in the enterpriseSiteId property within the transactionFraudInfo object in the Payment API or within the fraud-info resource in the Extended Payment API. The Enterprise Site ID passed to BlueSnap must exactly match an existing Site ID in Kount. Only one Site ID should be passed for each transaction.

User defined fields (UDFs)

User defined fields (UDFs) allow you to pass information related to an order or shopper that may not be a standard field in Kount. User defined fields can be referenced when creating a fraud rule or simply made available for reference when reviewing suspicious orders.

For example, it might be helpful to pass an indication of the shopper’s membership in a premium rewards program.

To manage Site IDs, go to Fraud Control > User Defined Fields in the Kount web console.

To implement a user defined field, define the UDF in the Kount web console. When you add a UDF, you will be prompted to assign it a label and a brief description. Each UDF must also be defined as either a number, alpha-numeric, a date, or amount.

For example, if you want to set up a UDF for reward membership, you might configure the UDF as follows:

  • Label: PremiumRewardsMember
  • Description: Is a member of our premium rewards program
  • Type: Alpha-Numeric

In the value, you could pass “Yes” to indicate a member and “No” to indicate a non-member.

Once you have defined the UDF in Kount, then you can pass this data in your BlueSnap API calls, in the enterpriseUdfs resource within the transactionFraudInfo resource in the Payment API or within the fraud-info resource in the Extended Payment API. The UDF name passed to BlueSnap must exactly match an existing UDF label.



Back to Top