Android SDK

// settings.gradle.kts (host app)
include(":thirdfactor-kyc")
project(":thirdfactor-kyc").projectDir =
    file("path/to/thirdfactor-obsidian/sdks/android")

// app/build.gradle.kts
dependencies {
    implementation(project(":thirdfactor-kyc"))
}

import com.thirdfactor.kyc.*

class CheckoutActivity : ComponentActivity() {
    private val verify = registerForActivityResult(ThirdFactor.Contract()) { result ->
        if (result.status == VerificationStatus.APPROVED) onApproved()  // confirm server-side!
    }

    private fun startKyc(sessionUrl: String) = verify.launch(VerifyRequest(sessionUrl))
}

data class VerificationResult(
    val status: VerificationStatus,      // APPROVED | DECLINED | IN_REVIEW | CANCELLED | ERROR
    val sessionId: String? = null,       // echoed by the flow when available
    val rawStatus: String? = null,       // raw server status, e.g. "abandoned"
    val error: ThirdFactorError? = null, // set only when status == ERROR
)

private val verify = registerForActivityResult(
    ThirdFactor.Contract(onEvent = { e -> Log.d("kyc", e.toString()) })
) { result ->
    when (result.status) {
        VerificationStatus.APPROVED  -> proceed()             // confirm server-side first
        VerificationStatus.DECLINED  -> showFailure()
        VerificationStatus.IN_REVIEW -> showPending()
        VerificationStatus.CANCELLED -> { /* let them retry */ }
        VerificationStatus.ERROR     ->
            if (result.error?.code == "expired") reMintSession() else showError(result.error)
    }
}

import com.thirdfactor.kyc.*

lifecycleScope.launch {
    val result = ThirdFactorNfc.read(
        activity = this@MyActivity,
        accessKey = NfcAccessKey.Mrz(
            documentNumber = "L898902C3",
            dateOfBirth    = "740812",   // YYMMDD
            dateOfExpiry   = "301001",   // YYMMDD
        ),
        dataGroups = listOf(NfcDataGroup.DG1, NfcDataGroup.DG2, NfcDataGroup.SOD),
        overallTimeoutMs = 60_000,       // give up if no chip is presented in 60 s
    )
    when (result) {
        is NfcReadResult.Success -> {
            val sod = result.dataGroups[NfcDataGroup.SOD]   // raw ByteArray
            // base64 + POST to your backend, which runs passive authentication.
        }
        is NfcReadResult.Failure -> showError(result.code)   // NfcErrorCode.*
    }
}

object ThirdFactorNfc {
    fun isAvailable(context: Context): Boolean
    suspend fun read(
        activity: Activity,
        accessKey: NfcAccessKey,                       // .Mrz(doc, dob, expiry) | .Can(can)
        dataGroups: List<NfcDataGroup> = DEFAULT_DATA_GROUPS,   // DG1, DG2, SOD
        transceiveTimeoutMs: Int = 15_000,             // per-APDU timeout
        overallTimeoutMs: Long = 0,                    // 0 = wait until cancelled
    ): NfcReadResult
    fun readTag(                                        // low-level: you own tag discovery
        isoDep: IsoDep,
        accessKey: NfcAccessKey,
        dataGroups: List<NfcDataGroup> = DEFAULT_DATA_GROUPS,
        transceiveTimeoutMs: Int = 15_000,
    ): NfcReadResult
}

package com.acme.app

import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.lifecycle.lifecycleScope
import com.thirdfactor.kyc.*
import kotlinx.coroutines.launch
import okhttp3.OkHttpClient
import okhttp3.Request
import org.json.JSONObject

class VerifyActivity : ComponentActivity() {

    // Idiomatic: register unconditionally as a property, before onCreate/onStart run.
    private val verifyLauncher = registerForActivityResult(
        ThirdFactor.Contract(onEvent = { e -> Log.d("kyc", e.toString()) }),
    ) { result -> handleResult(result) }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            Button(onClick = { startVerification() }) { Text("Verify identity") }
        }
    }

    private fun startVerification() {
        lifecycleScope.launch {
            // Call YOUR backend, which calls POST /v3/session/ with your secret key.
            val url = fetchSessionUrl() ?: return@launch
            verifyLauncher.launch(
                VerifyRequest(url, VerifyOptions(title = "Verify your identity", autoClose = true)),
            )
        }
    }

    private suspend fun fetchSessionUrl(): String? {
        val client = OkHttpClient()
        val request = Request.Builder()
            .url("https://api.acme.com/kyc/session")
            .post(okhttp3.RequestBody.create(null, ByteArray(0)))
            .build()
        return runCatching {
            client.newCall(request).execute().use { resp ->
                JSONObject(resp.body?.string() ?: "{}").optString("url")
            }
        }.getOrNull()
    }

    private fun handleResult(result: VerificationResult) {
        when (result.status) {
            VerificationStatus.APPROVED  -> Log.i("kyc", "approved — confirm server-side")
            VerificationStatus.DECLINED  -> Log.i("kyc", "declined")
            VerificationStatus.IN_REVIEW -> Log.i("kyc", "in review")
            VerificationStatus.CANCELLED -> Log.i("kyc", "cancelled")
            VerificationStatus.ERROR     -> Log.e("kyc", "error: ${result.error?.code}")
        }
    }
}