Android SDK · API Reference

Tap2iD SDK — Android API Reference

Complete API reference for integrating the Tap2iD Android SDK. Verify mobile credentials (mDL) based on ISO/IEC 18013-5:2021 via QR code, NFC, or both with just a few lines of Kotlin.

Explore API

>_ tap2id-android-sdk ––docs

Initialize SDK

Configure your API key and application context, then initialize the SDK before performing any mDL verification.

Verify mDL

One coroutine-based call supports QR code, NFC, or dual-mode engagement for mDL verification.

Handle Results

Process VerificationResult — inspect credential attributes, issuer trust, and device signatures.

Utility Methods

Retrieve the current SDK version string and other helper methods.

Initialize SDK

Call initSdk once at startup before any mDL verification. Provide your API key and application context via SdkConfig and receive results through InitSdkResultListener.

Tap2iDSdk — initSdk()

suspend fun initSdk(
    config: SdkConfig,
    initSdkListener: InitSdkResultListener
)

Parameters

Parameter	Type	Description
config	SdkConfig	SDK configuration containing API key and application context. required
initSdkListener	InitSdkResultListener	Callback interface for initialization results. required

SdkConfig

Kotlin

data class SdkConfig(
    val apiKey: String,
    val applicationContext: Context
)

InitSdkResultListener

Kotlin

interface InitSdkResultListener {
    fun onInitializationSuccess(result: SdkInitializationResult)
    fun onInitializationFailure(error: Error)
}

onInitializationSuccess(result: SdkInitializationResult)

Invoked when initialization completes successfully. The SDK is ready to use.

onInitializationFailure(error: Error)

Invoked on failure — inspect the error to diagnose API key or network issues.

Example

Kotlin

val config = SdkConfig(
    apiKey = "your_api_key_here",
    applicationContext = applicationContext
)

lifecycleScope.launch {
    Tap2iDSdk.initSdk(config, object : InitSdkResultListener {
        override fun onInitializationSuccess(result: SdkInitializationResult) {
            // SDK ready to use
        }

        override fun onInitializationFailure(error: Error) {
            // Handle initialization error
        }
    })
}

Verify mDL

Call verifyMdoc with an EngagementConfig specifying the verification method — QR code, NFC, or both simultaneously. Subscribe to MdocVerificationListener for real-time lifecycle events.

Tap2iDSdk — verifyMdoc()

suspend fun verifyMdoc(
    engagementConfig: EngagementConfig,
    mdocVerificationListener: MdocVerificationListener
)

Parameters

Parameter	Type	Description
engagementConfig	EngagementConfig	Verification method configuration — QR, NFC, or both. required
mdocVerificationListener	MdocVerificationListener	Callback interface for verification lifecycle events. required

EngagementConfig

Configure QR code verification, NFC verification, or both. At least one of qrConfig or nfcConfig must be non-null.

Kotlin

data class EngagementConfig(
    val qrConfig: QrConfig? = null,
    val nfcConfig: NfcConfig? = null
)

data class QrConfig(
    val mDocString: String  // QR code payload
)

data class NfcConfig(
    val activity: Activity  // Activity for NFC operations
)

MdocVerificationListener

Track verification progress through granular lifecycle callbacks.

Kotlin

interface MdocVerificationListener {
    // Called when a verification stage begins
    fun onVerificationStageStarted(stage: VerificationStage)

    // Called if a verification stage encounters an error
    fun onVerificationStageError(stage: VerificationStage, error: Throwable)

    // Called when a verification stage completes successfully
    fun onVerificationStageCompleted(stage: VerificationStage)

    // Called with final verification result and credential data
    fun onVerificationCompleted(verificationResult: VerificationResult)
}

Example: QR Code Verification

Kotlin — QR Code

val qrConfig = EngagementConfig(
    qrConfig = QrConfig(mDocString = scannedQrCode)
)

lifecycleScope.launch {
    Tap2iDSdk.verifyMdoc(qrConfig, object : MdocVerificationListener {
        override fun onVerificationStageStarted(stage: VerificationStage) {
            // Update UI: show progress for current stage
        }

        override fun onVerificationStageError(stage: VerificationStage, error: Throwable) {
            // Handle stage-specific errors
        }

        override fun onVerificationStageCompleted(stage: VerificationStage) {
            // Stage completed successfully
        }

        override fun onVerificationCompleted(verificationResult: VerificationResult) {
            val attributes = verificationResult.mdocAttributes
            val isValid = verificationResult.isIssuerSignedAuthenticated &&
                         verificationResult.isDeviceSignedAuthenticated

            if (isValid) {
                // Process verified credential
            } else {
                verificationResult.validationErrors?.forEach { error ->
                    Log.e("Verification", "Error: ${error.message}")
                }
            }
        }
    })
}

Example: NFC Verification

Kotlin — NFC

val nfcConfig = EngagementConfig(
    nfcConfig = NfcConfig(activity = this)
)

lifecycleScope.launch {
    Tap2iDSdk.verifyMdoc(nfcConfig, verificationListener)
}

Example: Dual Mode (QR + NFC)

Kotlin — Dual Mode

val dualConfig = EngagementConfig(
    qrConfig  = QrConfig(mDocString = scannedQrCode),
    nfcConfig = NfcConfig(activity = this)
)

lifecycleScope.launch {
    Tap2iDSdk.verifyMdoc(dualConfig, verificationListener)
}

Handle Results

The onVerificationCompleted callback delivers a VerificationResult containing all extracted credential attributes and the outcome of each security check.

VerificationResult structure

data class VerificationResult(
    val mdocAttributes: MdocAttributes,               // Extracted credential attributes
    val isIssuerSignedAuthenticated: Boolean,           // Issuer signature validation
    val isDeviceSignedAuthenticated: Boolean,           // Device signature validation
    val issuerInfo: String,                            // Issuer information
    val isIssuerVerified: Boolean,                     // Issuer trust verification
    val isMsoSigned: Boolean,                         // Mobile Security Object signature
    val validationErrors: MutableSet?                 // Any validation errors encountered
)

Security Properties

Property	Type	Description
isIssuerSignedAuthenticated	Boolean	Mobile Security Object signature is valid.
isDeviceSignedAuthenticated	Boolean	ECDSA/MAC device signature passes verification.
isIssuerVerified	Boolean	Issuing CA found in the SDK trust store.
isMsoSigned	Boolean	Mobile Security Object is properly signed.
validationErrors	MutableSet?	Detailed issues. Null or empty when all checks pass.

⚠ Always verify both isIssuerSignedAuthenticated and isDeviceSignedAuthenticated before trusting the credential data.

Reference

Utility Methods

Get SDK Version

Returns the current SDK version string. Useful for debugging and logging.

Tap2iDSdk — getSdkVersion()

fun getSdkVersion(): String

Kotlin — Example

val version = Tap2iDSdk.getSdkVersion()
Log.d("SDK", "Using Tap2iD SDK version: version")

Overview

Key Features

ISO/IEC 18013-5:2021 Compliant

Multi-Modal Verification (QR + NFC)

Issuer & Device Signature Validation

Coroutine-Based API

Granular Lifecycle Events

Detailed Error Reporting

✦ The SDK uses a coroutine-based suspend fun pattern — call initSdk and verifyMdoc inside a lifecycleScope.launch { } block to keep UI responsive.