> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/guides/koin-device-fingerprint-session-id.md).

# KOIN - Device Fingerprint Session ID

KOIN's fraud analysis requires a device fingerprint session ID generated client-side before the payment request is sent. This field is required for all KOIN payment and authorization requests.

The session ID is generated by a KOIN SDK or script running on the client device, then passed to your backend and included in `device_info.fingerprint_session_id` of the request payload.

{% hint style="warning" %}
The `org_id` value is environment-specific. Use the value provided by KOIN for each environment (staging/production). Using the wrong `org_id` will result in the `fingerprint_session_id` not being recognized by KOIN's fraud analysis.
{% endhint %}

***

### Web (JavaScript)

**1. Load the fingerprint script on your checkout page**

<details>

<summary><strong>Sandbox</strong></summary>

```html
<script
  type="text/javascript"
  src="https://antifraud-sandbox.koinlatam.com/risk/fingerprint/statics/track-min.js"
  id="deviceId_fp"
  org_id="YOUR_ORG_ID">
</script>
```

</details>

<details>

<summary><strong>Production</strong></summary>

```html
<script
  type="text/javascript"
  src="https://antifraud.koinlatam.com/risk/fingerprint/statics/track-min.js"
  id="deviceId_fp"
  org_id="YOUR_ORG_ID">
</script>
```

</details>

**2. Capture the session ID on page load**

Call `getSessionID` and store the result. Use it in the request payload when the user submits the payment form.

```javascript
let koinSessionId = null;

  window.addEventListener('load', function() {
    if (typeof getSessionID === "function") {
      getSessionID(function(sessionId) {
        koinSessionId = sessionId;
      });
    }
  });
```

**3. Include the value in the payment request**

Map the captured value to `device_info.fingerprint_session_id` when submitting the payment:

```json
{
  ...
  "device_info": {
    "ip_address": "127.0.0.1", // Your Ip Address
    "fingerprint_session_id": koinSessionId
  }
}
```

{% hint style="info" %}
Do not cache or reuse session IDs across separate checkout sessions. The session ID must be captured on the same page load as the payment submission.
{% endhint %}

***

### Android

Download the `.aar` file from the [KOIN Android SDK repository](https://github.com/koinlatam/android-sdk) and place it in your project's `libs` directory.

**1. Add the dependency in `build.gradle`**

```groovy
dependencies {
    implementation files('libs/fingerprint-sdk-release.aar')
}
```

If you encounter dependency errors after syncing, add the following:

```groovy
dependencies {
    implementation 'com.android.volley:volley:1.2.1'
    implementation 'com.google.android.gms:play-services-location:21.3.0'
    implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1'
}
```

**2. Register and capture the session ID**

Call `register` before any other SDK call. The recommended placement is `Application.onCreate()`. Then call `profile()` to generate the session ID.

```kotlin
KoinFingerprinter.register(applicationContext, "YOUR_ORG_ID")
val sessionId = KoinFingerprinter.profile(applicationContext)
```

For sandbox environments, override the default endpoint:

```kotlin
KoinFingerprinter.register(
    applicationContext,
    "YOUR_ORG_ID",
    "https://api-sandbox.koin.com.br/fingerprint/session/mobile"
)
val sessionId = KoinFingerprinter.profile(applicationContext)
```

{% hint style="warning" %}
For production environments, a URL override is required <https://api-antifraud.koin.com.br/fingerprint/session/mobile>
{% endhint %}

**3. Pass the session ID to your backend**

Send `sessionId` to your server and include it in the Firstoken API request:

```json
{
  ...
  "device_info": {
    "ip_address": "127.0.0.1",
    "fingerprint_session_id": "<sessionId>"
  }
}
```

{% hint style="info" %}
Call `profile()` once per app session. Multiple calls will send device data multiple times. The SDK does not require location permissions but will collect additional signals if `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`, or `ACCESS_WIFI_STATE` are already granted by your app.
{% endhint %}

***

### iOS

**Installation via CocoaPods**

KoinFingerprint is available through [CocoaPods](https://cocoapods.org/pods/KoinFingerprint). Add the following to your `Podfile` and run `pod install`:

```ruby
pod 'KoinFingerprint'
```

**Manual installation**

Download `KoinFingerprint-xcframework.zip` from the [KOIN iOS SDK repository](https://github.com/koinlatam/ios-sdk), then:

1. Unzip `KoinFingerprint-xcframework.zip`.
2. Drag `KoinFingerprint.xcframework` into the Project Navigator of your Xcode project.
3. When prompted, check **Copy items if needed** and select the target.
4. In **Frameworks, Libraries, and Embedded Content**, set the embed option to **Embed & Sign**.
5. In **Build Phases > Link Binary With Libraries**, confirm the status is set to **Required**.

**1. Import the library**

```swift
import KoinFingerprint
```

**2. Register your organization ID**

Call `register` at the end of `didFinishLaunchingWithOptions` or `applicationDidFinishLaunching`:

```swift
KoinFingerprinter.register(organizationId: "YOUR_ORG_ID", url: "https://api-sandbox.koin.com.br/fingerprint/session/mobile")
```

{% hint style="warning" %}
For production environments, a URL override is required <https://api-antifraud.koin.com.br/fingerprint/session/mobile>

Refer to the [KoinFingerprint Methods reference](https://github.com/koinlatam/ios-sdk/wiki/KoinFingerprint-Methods) for configuration details.
{% endhint %}

**3. Capture the session ID**

```swift
let sessionId = KoinFingerprinter.profile()
```

**4. Pass the session ID to your backend**

Send `sessionId` to your server and include it in the Firstoken API request:

```json
{
  ...
  "device_info": {
    "ip_address": "127.0.0.1",
    "fingerprint_session_id": "<sessionId>"
  }
}
```