> 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**
Sandbox
```html
```
Production
```html
```
**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
{% 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": ""
}
}
```
{% 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
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": ""
}
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://firstoken.gitbook.io/api-docs/guides/koin-device-fingerprint-session-id.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.