# Identity Verification Android SDK

`Version 0.1.0`

You can use the Identity Verification Android SDK to redirect applicants to attempts in your Android mobile app.

> **Information**
>
> To enable the SDK for your Identity Verification [configuration ID](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities/using-the-api.md#Configuration) supports 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).

---

## Before you start

You must have integrated the [Identity Verification](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities.md) solution.

### Minimum requirements

The following minimum versions apply:
- Kotlin 2.1.0
- Android minSdkVersion 24

---

## How it works

Follow these steps:

1. Install the SDK.
2. Initialize the SDK.
3. Handle the verification result.

---

## Install the SDK

The Identity Verification Android SDK is distributed as a local Maven repository containing Android archive files (AARs).

1. Download and unzip the file provided by your account manager.

2. Copy the unzipped folder to your project root at `<project-root>/local-repo/`, using the following structure:

```
<project-root>/
├── local-repo/
│   └── com/
│       └── checkout/
│           └── idv/
│               ├── idv/
│               │   └── 0.1.0/
│               │       └── idv-0.1.0.aar
│               └── idv-ui/
│                   └── 0.1.0/
│                       └── idv-ui-0.1.0.aar
└── ...
```

### Configure Gradle

1. In `settings.gradle.kts`, add the local Maven repository to `dependencyResolutionManagement`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven(url = uri("${rootProject.projectDir}/local-repo"))
    }
}
```

2. In `gradle/libs.versions.toml`, add the following dependencies to the version catalog:

```toml
[versions]
idv = "0.1.0"

[libraries]
idv = { group = "com.checkout.idv", name = "idv", version.ref = "idv" }
idv-ui = { group = "com.checkout.idv", name = "idv-ui", version.ref = "idv" }
```

3. In your app module `build.gradle.kts`, add the dependencies:

```kotlin
dependencies {
    implementation(libs.idv)
    implementation(libs.idv.ui)
}
```

> **Information**
>
> Checkout.com sends you a new .zip file when we release updates to the SDK.

### Add your logo

In your app's assets library, add your business's logo in any image format supported by Android.
For example GIF, JPG, PNG, WebP, Android Vector Drawable (AVD).

> **Information**
>
> For information on providing a logo for dark mode, see Medium – [Use a Different Image When Dark Mode is Enabled on Android](https://medium.com/@ridvanozcan48/use-a-different-image-when-dark-mode-is-enabled-on-android-777ff5cc96b7).

---

## Initialize the SDK

1. Call the [Create an attempt](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities.md#Create_an_attempt) endpoint from your back end, which returns the following:

- The attempt URL, which is valid for 15 minutes, in the `verification_url` field
- The `client_secret`, which is valid for 48 hours, to authorize the verification

2. Initialize the SDK and pass the attempt URL and the client secret:

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()

    setContent {
        // 1. Create the configuration (optionally, add your company name and logo)
        val configuration = IdentityVerificationConfiguration(
            commercialName = "YOUR_BRAND",
            logo = R.drawable.logo,
            buttonCornerRadius = 80.dp,
            typography =
                        IdentityVerificationConfiguration.Typography(
                            pageTitle = R.font.YOUR_BRAND_FONT
                            sectionTitle = R.font.YOUR_BRAND_FONT,
                            body = R.font.YOUR_BRAND_FONT,
                            caption = R.font.YOUR_BRAND_FONT,
                            button = R.font.YOUR_BRAND_FONT,
                        ),
            // For example, your app's primary color
            lightColorScheme = ColorScheme(
                primary = Color(0xFFEC1408),
                onPrimary = Color.White
            )
        )

        // 2. Optionally, customize the colors, button corner radius, and fonts
        public data class IdentityVerificationConfiguration(
            val typography: Typography = Typography(),
            val lightColorScheme: ColorScheme = ColorScheme.light,
            val darkColorScheme: ColorScheme = ColorScheme.dark,
            val buttonCornerRadius: Dp = 4.dp,
            @DrawableRes val logo: Int,
            val commercialName: String,
        ) : Parcelable {
            @Parcelize
            public data class Typography(
            @FontRes val pageTitle: Int = R.font.roboto,
            @FontRes val sectionTitle: Int = R.font.roboto,
            @FontRes val body: Int = R.font.inter,
            @FontRes val caption: Int = R.font.inter,
            @FontRes val button: Int = R.font.inter,
        ) : Parcelable

        // 3. Initialize the launcher
        val idv = CheckoutIdentityVerification.rememberCheckoutIdentityVerification(
            configuration = configuration
        ) { result ->
            // 3. Handle the result
            when (result) {
                is IDVResult.Completed -> {
                    println("Verification completed successfully!")
                }
                is IDVResult.Failed -> {
                    println("Verification failed or cancelled. Reason: ${result.reason}")
                }
            }
        }

        val launchOptions = IDVLaunchOptions(
            verificationUrl = "https://example.com/verify",
            clientSecret = "Your_client_secret",
        )

        Scaffold(modifier = Modifier.fillMaxSize()) { padding ->
            Box(modifier = Modifier.padding(padding).fillMaxSize(), contentAlignment = Alignment.Center) {
                Button(onClick = {
                    // 4. Launch the SDK
                    idv.launch(launchOptions = launchOptions)
                }) {
                    Text("Start Verification")
                }
            }
        }
    }
}
```

You can use the `IdentityVerificationConfiguration` struct to customize the following elements of the verification UI:

- Button corner radius
- Colors
- Commercial name for your business
- Fonts
- Logo

### Localization

The UI supports the following languages:

- Chinese (simplified)
- Dutch
- English (UK)
- English (US)
- Estonian
- Finnish
- French
- German
- Italian
- Japanese
- Korean
- Latvian
- Polish
- Portuguese
- Romanian
- Russian
- Slovak
- Spanish
- Swedish

---

## Handle the verification result

When the verification is completed and the result is available, catch the `ReturnReason` enum.

| Enum | Description |
| --- | --- |
| `success` | The verification was completed successfully. |
| `refusal` | The applicant selected a button to refuse to perform the verification.<br><br>This can have the value `refusal`. |
| `retryRequired` | The applicant needs to retry the verification. <br><br>Create a new attempt.<br><br>This can have the following values:<br><br>- `connectionIssue` – The network connection was weak or the video quality was poor.<br>- `error` – An unexpected technical error occurred during the attempt.<br>- `focusLost` – The applicant navigated away from your app during the attempt.<br>- `noDocument` – The applicant indicated that they did not have their identity document available to complete the verification.<br>- `verifyLater` – The applicant selected a button to complete the verification at a later time. |

> **Information**
>
> Each `ReturnReason` returns a response code that provides more information about the reason.
> See [Identities response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md#Response_codes).