# Risk Android SDK

`Version 3.0.0`

The `checkout-risk-sdk-android` SDK supports the [Fraud Detection](https://www.checkout.com/docs/business-operations/prevent-fraud.md) solution by capturing advanced fraud signals that are leveraged in Checkout.com's machine learning model for risk scores.

> **Information**
>
> To enable access to the SDK, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
>
> For more information, see [Integrate with Risk SDK](https://www.checkout.com/docs/business-operations/prevent-fraud/integrate-with-risk-sdk.md).

---

## Before you start

Generate a [public API key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md#Public_API_keys) from your [Dashboard](https://dashboard.checkout.com).

The minimum requirements to use the SDK are:

- Android API level 21 (Android 5.0) or later as a build target
- Compatibility with targetSdk versions `21` to `33`

---

## How it works

1. Import the SDK.
2. Initialize the SDK.
3. Publish the device data.
4. Complete the data safety questionnaire.

---

## Import the SDK

1. Add the [Risk Android SDK](https://github.com/checkout/checkout-risk-sdk-android) as a dependency from GitHub.

> **Information**
>
> For the installation steps and available versions, see the [jitpack.io/frames-android](https://jitpack.io/#checkout/checkout-risk-sdk-android) documentation.

2. Add the JitPack repository to your project-level `build.gradle` file:

```kotlin
// project gradle file

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
        maven { url = uri("https://maven.fpregistry.io/releases") }
    }
}
```

3. Add the Risk SDK dependency to the module gradle file:

```kotlin
// module gradle file

dependencies {
    implementation 'com.github.checkout:checkout-risk-sdk-android:<latest_version>'
}
```

To ensure you have the correct [build configuration](https://developer.android.com/build), make sure you:

 - Add the Jitpack repository to the project gradle file.
 - Add the dependency to the module gradle file.

---

## Initialize the SDK

To initialize the package, call the `Risk.getInstance()` method and pass the following:

- API key
- MSSD, which you can find in [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md)
- Environment

```kotlin
// Example usage of package

val yourConfig = RiskConfig(publicKey = "pk_xxx", mssd = "xxxxxxxx", environment = RiskEnvironment.SANDBOX)

// Initialize the package with the getInstance method early-on
val riskInstance =
    Risk.getInstance(
        context,
        RiskConfig(
            BuildConfig.SAMPLE_MERCHANT_PUBLIC_KEY,
            BuildConfig.SAMPLE_MERCHANT_MSSD,
            RiskEnvironment.SANDBOX,
            false,
        ),
    ).let {
        it?.let {
            it
        } ?: run {
            null
        }
    }
```

When the customer selects to pay, publish the device data by calling the `publishData()` method on the Risk instance and retrieve the `deviceSessionId`:

```kotlin
// Publish the device data with the publishData method

riskInstance?.publishData().let {
    if (it is PublishDataResult.Success) {
        println("Device session ID: ${it.deviceSessionId}") // dsid_XXXX
    }
}
```

---

## Publish the device data

The `getInstance` method returns a single instance of `Risk`. When you call the method, Checkout.com performs preliminary checks and retrieves the public keys to initialize the package to collect device data.
If the checks fail or the merchant is disabled, the method returns `null`.

If the checks are successful, the method returns an instance of `Risk` to the package consumer.

1. Call the `publishData()` method on the instance to publish the data.

### Argument

```kotlin
data class RiskConfig(val publicKey: String, val mssd: String, val environment: RiskEnvironment, val framesMode: Boolean = false)

// Instance creation of Risk Android package
public class Risk private constructor(...) {
    public companion object {
        ...
        public suspend fun getInstance(applicationContext: Context, config: RiskConfig): Risk? {
            ...
        }
    }
}

enum class RiskEnvironment {
    SANDBOX,
    PROD
}
```

### Response

```kotlin
class Risk private constructor(...) {
    companion object {
        ...
        suspend fun publishData(...): ... {
            ...
        }
    }
}
```

Call the `publishData()` method to publish and persist the device data.

### Argument

```kotlin
public suspend fun publishData(cardToken: string? = null): PublishDataResult {
...
}
```

### Response

```kotlin
public sealed class PublishDataResult {
    public data class Success(val deviceSessionId: String) : PublishDataResult()

    public data object PublishFailure : PublishDataResult()
}
```

### Example configuration

```kotlin
// Example usage of package
val yourConfig = RiskConfig(publicKey = "pk_xxx", mssd = "xxxxxxxx", environment = RiskEnvironment.SANDBOX)

// Initialize the package with the getInstance method
val riskInstance =
    Risk.getInstance(
        context,
        RiskConfig(
            BuildConfig.SAMPLE_MERCHANT_PUBLIC_KEY,
            BuildConfig.SAMPLE_MERCHANT_MSSD,
            RiskEnvironment.QA,
            false,
        ),
    ).let {
        it?.let {
            it
        } ?: run {
            null
        }
    }

// Publish the device data with the publishData method when the user selects the option to pay

riskInstance?.publishData().let {
    if (it is PublishDataResult.Success) {
        println("Device session ID: ${it.deviceSessionId}") // dsid_XXXX
    }
}
```

---

## Complete Data safety form

When you submit your app to Google Play, provide the [required responses](https://www.checkout.com/docs/developer-resources/sdks/data-safety-form.md) in your Data safety form.