Integrator manual Fraud

Integrator manual

SDK

Get started 

The Ironchip mobile SDK captures device information, location-related signals (GPS, Wi-Fi), and user sessions to help differentiate attackers from legit users. To gather risk assessment from the APIs, start by installing and configuring the mobile SDK.

Supported platforms 

We currently support Android and iOS. The following are the latest SDK version for each operating system:

Android

    Changelog

[1.2.7] - 2023-03-15 - nowadays

Added 

  • Changed transaction model to add information about the sim card.

Changed 

Removed 

[1.2.6] - 2023-02-02 - 2023-03-15

Added 

Changed 

  • Changed transaction model to add the requested permissions and if they are granted.
  • Changed transaction model to add if the gps and wifi providers are enabled.

Removed 

[1.2.5] - 2023-01-13 - 2023-02-02

Added 

Changed 

  • Fixed proguard configuration causing the consumer application to be repackaged into our library internal folder.

Removed 

[1.2.4] - 2023-01-10 - 2023-01-13

Added 

Changed 

  • Errors during the send transaction callback will now be logged instead of redirected to the exception callback.

Removed 

[1.2.3] - 2022-12-09 - 2023-01-10

Added 

Changed 

  • Fixed issue with the fingerprint id.

Removed 

[1.2.2] - 2022-11-30 - 2022-12-09

Added 

Changed 

  • Fix a bug when not connected to a wifi.
  • Fix new lines on the encrypted ids.
  • Improved the emulation detection.

Removed 

[1.2.1] - 2022-11-23 - 2022-11-30

Added 

Changed 

  • Class name refactorization.
  • Changed the tags on the logs to match the refactorization.
  • Fraud constructor no longer supports a url host, it only allow to select the desired environment.

Removed 

[1.2.0] - 2022-10-12 - 2022-11-22

Added 

  • Added kernel version into the device properties
  • Debug logs

Changed 

  • Fixed bugs with the JSON sending strings instead of arrays
  • Improvement to the device id, installation id and fingerprint
  • GPS and Signal can no longer cause a blockage in the process

Removed 

[1.1.3] - 2022-09-30 - 2022-10-12

Added 

Changed 

  • Publish repository from nexus to github.

Removed 

[1.1.2] - 2022-09-30 - 2022-10-12

Added 

  • Compatibility for versions 5+

Changed 

Removed 

[1.1.0] - 2022-09-22 - 2022-09-30

Added 

  • LICENSE file added to the project

Changed 

  • Refactor module name.

Removed 

[1.0.2] - 2022-09-10 - 2022-09-22

Added 

  • Custom exceptions

Changed 

  • Excluded callbacks and exceptions from offuscation for easier client use.
  • Changed model paramters names and structure.

Removed 

[1.0.1] - 2022-09-10 - 2022-09-12

Added 

  • CI/CD to build and publish on the dev, testing and release branches.

Changed 

  • Excluded callbacks and exceptions from offuscation for easier client use.
  • Changed model paramters names and structure.

Removed 

[1.0.0] - 2022-09-10

Added 

  • Code obfuscation and gitignore extended.

Changed 

  • Migrated code sections of the code to a common library.
  • Modified the behaviour of the GPS service.

Removed 

   Setup

Supported versions 

Platform Supported versions
Android 5.0.0+

Add Ironchip Location Based Fraud SDK 

Add our library in other projects 

First, on the setting.gradle file, reference the remote repository where the library is located.

dependencyResolutionManagement {
...

repositories {
maven { url 'https://jitpack.io' }
...
}
}

Then, inside the gradle.build file, add the dependency to the sdk.

dependencies {
...
implementation 'com.github.Ironchip-Security:LBFraud-SDK-Android:1.2.7'
...
}

Permissions 

Add the following permissions to your manifest:

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

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

<uses-permission android:name="android.permission.INTERNET" />

  Usage

Use in an app 

To make full use of the potential of the sdk, the ACCESS_FINE_LOCATION permission needs to be granted.

How to request permissions

import com.ironchip.ironchiplbfraudandroidsdk.LBFraudSDK;
...

// Replace APIKEY with the desired generated api key.
LBFraudSDK fraud = new LBFraudSDK(this, "APIKEY");
// By default our SDK target to the production environment.
// In case you desire to target a diferent enviroment:
// LBFraudSDK fraud = new LBFraudSDK(this, "APIKEY", LBFraudSDK.Environment.Testing);

//public enum Environment {
// Production,
// Testing,
// Development
//}

String transactionID = "random_identifier_generated"; // Transaction identifier request for fraud results
String userID = "john.doe@gmail.com"; // User identifier

Map<String, Object> extraData = new HashMap<>(); // Extra information for analysis
extraData.put("concept", "Book august");
extraData.put("amount", new Integer(30));
extraData.put("operation", "booking");

// TransactionID (required,unique): transaction identifier request for fraud results
// UserID (required): User identifier
// ExtraData (optional): extra information for analysis
// The sendTransaction can be provided with 2 callbacks, one is executed when the transaction is finished
// and the other one is called in case an error did occure during the transaction process.
fraud.sendTransaction(transactionID, userID, extraData, () -> {
// Add here any code you want to be executed after the transaction
// has finished.
}, exception -> {
// Add here any code you want to perform in case of an error
// during the transaction.
// exception.printStackTrace()
});

IOS

     Changelog

[1.2.7] - 2023-03-23 - nowadays

Added 

Changed 

  • Commons has been made to link to LBFraud and not be embedded.

Removed 

[1.2.6] - 2023-03-15 - 2023-03-23

Added 

  • Changed the transaction model to add information about the device’s SIM and eSIM cards.

Changed 

Removed 

[1.2.5] - 2023-02-02 - 2023-03-15

Added 

Changed 

  • Changed transaction model to add the requested permissions status.
  • Changed transaction model to add if the gps and wifi providers are enabled.

Removed 

[1.2.4] - 2022-12-20 - 2023-02-02

Added 

Changed 

  • Fixed the problem when validating the application in the Apple Store.
  • Location service logs for iOS 13.

Removed 

[1.2.3] - 2022-12-09 - 2022-12-20

Added 

Changed 

  • Fixed issue with the fingerprint id.
  • Handle external HTTP cals.

Removed 

[1.2.2] - 2022-11-30 - 2022-12-09

Added 

Changed 

  • Change some property of the device in the transaction model.

Removed 

[1.2.1] - 2022-11-23 - 2022-11-30

Added 

Changed 

  • Class name refactorization.
  • Changed the tags on the logs to match the refactorization.
  • Fraud constructor no longer supports a url host, it only allow to select the desired environment.
  • GPS service, throw error when permission is not granted or Location service is disabled.

Removed 

[1.2.0] - 2022-11-16 - 2022-11-22

Added 

  • Debug Logs

Changed 

  • Management of new errors in Commons library.
  • Changes in the transaction model.

Removed 

  • Network errors, now throw the generic not custom ones

[1.1.8] - 2022-10-25 - 2022-10-31

Added 

Changed 

  • Version 1.1.7 is promoted to 1.1.8 because of organizative reasons.

Removed 

[1.1.7] - 2022-10-25 - 2022-10-25

Added 

  • Compatibility for versions 13+.

Changed 

  • Change url from Nexus to GitHub.

Removed 

[1.1.6] - 2022-09-14 - 2022-10-25

Added 

Changed 

Removed 

  • Unnecesary prints.

[1.1.5] - 2022-09-14 - 2022-09-14

Added 

  • In commons library throw custom errors, and in LBFraud rethrow them.

Changed 

  • Rename commons Services.

Removed 

[1.1.4] - 2022-09-12 - 2022-09-14

Added 

  • Add CHANGELOG file to the project.

Changed 

  • Changed model parameters names and structure.

Removed 

[1.1.2] - 2022-09-03 - 2022-09-12

Added 

Changed 

  • Change nexus repository name of .xcframework.zip.

Removed 

[1.1.1] - 2022-08-27 - 2022-09-03

Added 

  • Now the project have two .xcframework one from Commons Library and the other from LBFraud.

Changed 

  • Now the Swift Package is getting the .xcframework from remote not local one.

Removed 

[1.1.0] - 2022-08-24 - 2022-08-27

Added 

- LICENSE file added to the project.

Changed 

Removed 

[1.0.9] - 2022-08-23

Added 

- First Stable version of a SwiftPackage with one XCFramework called LBFraudSDKiOS.xcframework.
- gitignore added.

Changed 

Removed 

    Setup

Supported versions 

Platform Supported versions
iOS 13.0.0+

Add Ironchip Location Based Authentication SDK 

Using Xcode:

To import this swift package dependency, in Xcode go to the root of your application for example ExampleApp.xcodeproj, at the top in PROJECT select ExampleApp item and go to the thrird tab, Package dependencies, select + button.

A pop up will open and in search or enter url copy the repositorie url and press add package button.

In this case: https://github.com/Ironchip-Security/LBFraud-SDK-iOS.git

A new window appears, in dependency rule, you can select an exact version, a range of versions, a branch… in this case to test it you can choose the exact version 1.2.7 and finally add the package to use it, or a range like 1.0.9 < 1.2.7, we recommend to ease package upgrades that you use a range of versions

setup ios

To be able to use Ironchip LBFraud as a SwiftPackage you will need to add to the target of your app a capability so go to Singing and Capabilities and add access Wifi Information.

setup ios

Then in the Target of the app in info tab you have to add the key values of location permission.

  1. Privacy - Location Always and When In Use Usage Description, and insert the description as string
  2. Privacy - Location When In Use Usage Description, and insert the description as string
  3. Privacy - Location Always Usage Description, and insert the description as string
  4. LSApplicationQueriesSchemes, and insert the description (this permission is to be able to know if the device is jailbroken)
setup ios permissions

First of all you have to request Location Permission in your app:

import CoreLocation

let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

     Usage

Use in an app 

The library initialization method must be called in the main thread.

import LBFraudSDKiOS
...

// Replace apikey with the desired generated api key.
let ironchipLBFraud = LBFraudSDKiOS.init(apikey: "XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
// By default our SDK target to the production environment.
// In case you desire to target a diferent enviroment:
// let ironchipLBFraud = LBFraudSDKiOS.init(apikey: "XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", environment: Environment.Testing)

//public enum Environment: String {
// case Production
// case Testing
// case Development
//}

//Call Ironchip Location Based Antifraud to Analyze transaction

let data: [String: Any] = [
"concept": "Book august",
"amount": 60,
"operation": "booking"
]

//TransactionID (required,unique): transaction identifier request for fraud results
//UserID (required): User identifier
//ExtraData (optional): extra information for analysis

// The sendTransaction can be provided with 2 callbacks, one is executed when the transaction is finished
// and the other one is called in case an error did occure during the transaction process.

ironchipLBFraud.sendTransaction(transactionId: "random_identifier_generated", userId: "john.doe@gmail.com", extraData: extraData, finish: {
// Add here any code you want to be executed after the transaction has finished.
}, onError: { err in

// Add here any code you want to perform in case of an error
// during the transaction.

// example:
//if(err is TransactionError) {

// let transactionError = err as! TransactionError

// print(transactionError.traceability_id)
// print(transactionError.message)
// print(transactionError.http_code)
// print(transactionError.code)
//} else {
// print("NetworkError: ", err)
//}
}
)

Web

     Changelog

[0.1.0] - 202-02-22

Added 

  • First version of the Web SDK

Changed 

Removed 

    Setup

What is LBFraud web SDK? 

LBFraud web SDK is the piece that allow you to integrate Ironchip LBFraud in your web environment. Using it Ironchip can evaluate if the device and environment that uses the website is secure. To add the SDK to the website you just need to follow the next steps.

JavaScript integration 

First, you need to download the necessary JavaScript file (Click here). Once you have it you need to import the file

import { LBFraudSDK, LBFraudSDKEnvironment } from 'ironchip.modern.js';

Then, with the SDK imported you need to initialize the client. Please ensure that you have the API- Key and the environment where you will work. By default the chosen environment is Production.

You will initialize the client (Choose just one environment):

const client = new LBFraudSDK({
apiKey: 'api-key',
environment: LBFraudSDKEnvironment.Development,
LBFraudSDKEnvironment.Testing,
LBFraudSDKEnvironment.Production,
});

   Usage

No sooner you initialize the client you can send transaction using the next method.

You have to pass as entry parameters the Transaction ID and the User ID.

client
.sendTransaction(transactionID, userID)

And that is all. Every time the method is called it will send a transaction.

Full example

The following code is a very simple example to test the SDK

(JavaScript file)

test.js

import { LBFraudSDK, LBFraudSDKEnvironment } from './ironchip.modern.js';

const client = new LBFraudSDK({
apiKey: 'api-key',
environment: LBFraudSDKEnvironment.Testing
});

const myButton = document.getElementById('myButton');

function setListener() {

myButton.onclick = function(){
const transactionID = document.getElementById('transactionId').value;
const userID = document.getElementById('userId').value;
client
.sendTransaction(transactionID, userID)
.then((success) => {console.log(success)})
.catch((errorMsg) => {
console.log(errorMsg)
});
}
}

window.onload=function(){
setListener()
}

index.html

<!DOCTYPE html>
<html>
<head>
<title>Web SDK test</title>
</head>
<body>
<label for="transactionId">Transaction ID:</label>
<input type="text" id="transactionId" name="transactionId">

<label for="userId">User ID:</label>
<input type="text" id="userId" name="userId">

<button id="myButton">Send transaction</button>

<script type="module" src="test.js"></script>
</body>
</html>

API's

    Generating an access api-key

All endpoints are protected by an api-key.

Once you generate the api-key, send it through the Authorization header as follows:

    Authorization: <apikey>

To generate the api-key, go to the Credentials page, click on ‘Generate api-key’:

generate access apikey

 

With this api-key you will have access to all possible requests. The generated QR is used to synchronize the mobile application with the dashboard.

API libraries 

Official libraries are available to help the integration with the Ironchip API. These libraries serve as API wrappers and handle features such as:

  • Transparent API authentication
  • Requests for all available endpoints
  • HTTP error handling

    Understanding risk assesssments 

Risk assessment types 

Risk Assessment

Ironchip may provide four types of risk assessments, which depend on our confidence level in a given action performed by a device:

  • fraud: Ironchip deems the action performed by the device as fraudulent, involved in a fraud
  • high_risk: Ironchip deems the action (e.g. sign up, login) performed by the device to be potentially fraudulent, and advises you to take preventive actions in these scenarios.
  • low_risk: ironchip considers this action performed by the device to be safe to accept.
  • unknown_risk: ironchip is unable to provide a precise assessment at the time of the request.

Risk assessment evidences 

Ironchip’s APIs rely on evidence to provide risk assessments. This decision is built on top of different analyses through distinct lenses.

The table below describes possible evidence values, their meaning, and which use cases they impact.

Understanding sensor match type 

Match Type Description
gps When Ironchip is able to perform comparisons by GPS data.
wifi_scan When Ironchip is able to perform comparisons by Wi-Fi sensors, but no matching connected networks are found.
wifi_connection When Ironchip is able to perform comparisons by connected Wi-Fi networks.
mobile_networks When Ironchip is able to perform comparisons by connected Mobile networks.

Risk assessment decision 

Ironchip’s APIs rely on decisions to provide risk assessments. This decision is built on top of different analyses through distinct lenses.

Decision

The table below describes possible decisions values, their meaning, and which use cases they impact.

Decision Description Type
SIM Swapping / ATO Detected Account Takeover based or not on Sim Swapping attack (depending on client user protection) string
Phising Detected phising attack from specific location (Multiple ATO) string
Synthetic identity Detected Synthetic Identity attack string
New user New user detected in Ironchip’s platform string
Location fraud Detected location fraud attempt by user comparing all location datasources string
Banned location Detected location from a banned place. In example: Location detected from russia string
Device Swapping Detected legitimate device swapping of a user string
Location Swapping Detected legitimate location swapping of a user string
Common usage Detected common usage string

    Report API

       Documentation

Ironchip AntiFraud API reference 

Ironchip Antifraud API provides seamless identity verification that reduces trusted user verification and onboarding time, and detects application fraud. Check device location behavior to provide risk assessment and supporting evidence.

When a device is new to the Ironchip network, our technology determines the location of the new user. At the same time, each operation collects location data and provides an updated risk assessment.

In order to evaluate a new registration, Ironchip needs to receive a token to identify the device from which it originates.

Get the specific report 

GET 

https://report.lbfraud.ironchip.com/report/{transaction_id}?timeout=TIMEOUT

This method allows you to query the latest assessment for a given transaction event, identified by its id.

Request
Response

Sample Curl: 

curl -X 'GET' \
'https://dev.report.lbfraud.ironchip.com/report/lHsGJ?timeout=TIMEOUT' \
-H 'accept: application/json' \
-H 'Authorization: APIKEY'

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response field Type Description
id integer Unique report identifier which can be used to verify if the assessment changed in later calls.
transaction_id string A unique identifier to the user’s transaction.
application_id string  
event object Assessment result. The object provides risk assessment and fraud case.
user object An object with the information of the user who made the transaction.
device object An object with the information of the device with which the transaction was made.
location object An object with the information of the location in which the transaction was made.
ip object An object with the information of the ip used to make the transaction.
descriptive_report string String understandable to any customer.
latencies object An object with the information of all latencies.
latency integer The latency with which a report has been made.

Get all reports 

GET 

https://report.lbfraud.ironchip.com/reports?limit=LIMIT&since=SINCE&user=USER&risk=RISK

This method allows you to query assessments, these assessments could be parameterized by limit number of reports, since report generation, user involved and risk assigment.

Request
Response

Sample Curl: 

curl -X 'GET' \
'https://dev.report.lbfraud.ironchip.com/reports?limit=LIMIT&since=SINCE&user=USER&risk=RISK' \
-H 'accept: application/json' \
-H 'Authorization: APIKEY'

Response body

For a 200-OK response, the fields you should expect as a result are the same as when you make a report request.

Realtime reports 

GET 

This method allows you to view all the reports in realtime. This request is unsupported via web. It have not any request paremeter.

Response

Response body

For a 200-OK response, the fields you should expect as a result are the same as when you make a report request.

Release notes

1.0.2 

Features 

  • Added swagger documentation.
  • Batch and streaming report API.
  • Pagination.
  • New client dashboard to manage and view metrics.
  • Transaction processing time improvement.
  • Bussiness rule engine added to time procesing.
  • Banned location settings added.