Tap2iD SDK for Android - API Reference

API reference for the Tap2iD Android SDK. Covers SDK initialization, mDL verification over BLE, NFC, and QR, and PDF417 barcode verification for physical driver's licenses.

Overview

The Tap2iD Android SDK verifies ISO 18013-5 mobile driver's licenses (mDLs) over BLE, NFC, or QR engagement, and AAMVA PDF417 barcodes on physical driver's licenses. Call Tap2iDSdk.initSdk(…) once at startup, then Tap2iDSdk.verifyMdoc(…) or Tap2iDSdk.verifyPdf417(…) for each verification.

  • Language: Kotlin (Java interop supported)
  • Min SDK: Android 10 (API 29)
  • Transport: BLE, NFC, QR.
  • Standard: ISO/IEC 18013-5:2021
  • PDF417: AAMVA barcode verification with CA / NY / VA cryptographic authenticity v2.2.0+, arm64 only
01

Initialize SDK

Call initSdk once at startup, before any mDL verification. Pass your license key and application context in SdkConfig, and receive results through InitSdkResultListener.

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

Parameters

ParameterTypeDescription
configSdkConfigSDK configuration containing license key and application context. required
initSdkListenerInitSdkResultListenerCallback 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 license 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
        }
    })
}
02

Verify mDL

Call verifyMdoc with an EngagementConfig that sets the verification method: QR code, NFC, or both. Subscribe to MdocVerificationListener for lifecycle events.

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

Parameters

ParameterTypeDescription
engagementConfigEngagementConfigVerification method configuration: QR, NFC, or both. required
mdocVerificationListenerMdocVerificationListenerCallback interface for verification lifecycle events. required

EngagementConfig

Sets 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

Lifecycle callbacks that report verification progress.

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)
}
03

Handle Results

The onVerificationCompleted callback returns a VerificationResult with the 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

PropertyTypeDescription
isIssuerSignedAuthenticatedBooleanMobile Security Object signature is valid.
isDeviceSignedAuthenticatedBooleanECDSA/MAC device signature passes verification.
isIssuerVerifiedBooleanIssuing CA found in the SDK trust store.
isMsoSignedBooleanMobile Security Object is properly signed.
validationErrorsMutableSet?Detailed issues. Null or empty when all checks pass.
⚠ Always verify both isIssuerSignedAuthenticated and isDeviceSignedAuthenticated before trusting the credential data.
04

Verify PDF417 Barcode

In addition to mobile credentials, the SDK verifies the PDF417 barcode printed on the back of a physical AAMVA driver's license or ID card. Capture the raw barcode string — typically from a camera decode (ML Kit's Barcode.FORMAT_PDF417) or a hardware scanner — and pass it to verifyPdf417. An AAMVA payload starts with the compliance indicator @, a convenient way to route a scanned value to PDF417 rather than mDoc engagement.

Tap2iDSdk: verifyPdf417()
suspend fun verifyPdf417(
    request: Pdf417VerificationRequest
): Pdf417VerificationResult

Parameters

ParameterTypeDescription
requestPdf417VerificationRequestWraps the raw AAMVA PDF417 string. required
Kotlin
data class Pdf417VerificationRequest(val pdf417Value: String)

Pdf417VerificationResult

Unlike verifyMdoc, this is a single suspending call with no lifecycle listener — the result is returned directly.

Kotlin
data class Pdf417VerificationResult(
    val verdict: PDF417Verdict,                   // REAL | FAKE | SUSPICIOUS | ERROR
    val confidenceLevel: Int,                     // 0 - 100
    val stateCode: String?,                       // e.g. "CA"; null if unparseable
    val fields: Map<String, Any?>,                // ISO mDL attribute names -> values
    val errors: List<PDF417ClassifierCode>,       // Failures (code < 5000)
    val crypto: Pdf417CryptoVerification,         // Cryptographic authenticity
    val warnings: List<PDF417ClassifierCode>,     // Non-fatal findings (code >= 5000)
    val attestations: Pdf417Attestations          // Profile-driven attestations
)

Supporting types

Kotlin
enum class PDF417Verdict { REAL, FAKE, SUSPICIOUS, ERROR }

data class PDF417ClassifierCode(val code: Int, val message: String)

data class Pdf417CryptoVerification(
    val authority: String,    // "CA_DMV", "NY_DMV", "VA_DMV"
    val checked: Boolean,     // true when a signature check was evaluated
    val verified: Boolean,    // true when the signature is valid
    val detail: String?
)

data class Pdf417Attestations(
    val documentExpired: Boolean = false,        // Expiry date strictly before today
    val ageAttestationPassed: Boolean? = null    // null if age check not requested
)
ℹ Errors vs. warnings. The SDK splits these into two separate lists, so you don't need to test code ranges yourself. PDF417ClassifierCode.WARNING_CODE_FLOOR (5000) is the boundary: codes at or above it are warnings, codes below it are errors.

Verdict values

REAL
FAKE
SUSPICIOUS
ERROR

Example

Kotlin: Verify a PDF417 Barcode
lifecycleScope.launch {
    try {
        val result = Tap2iDSdk.verifyPdf417(Pdf417VerificationRequest(scannedBarcode))

        Log.d(TAG, "Verdict: ${result.verdict} (${result.confidenceLevel}%) State: ${result.stateCode}")

        if (result.crypto.checked) {
            val status = if (result.crypto.verified) "VERIFIED" else "NOT verified"
            Log.d(TAG, "Crypto (${result.crypto.authority}): $status")
        }

        if (result.attestations.documentExpired) {
            Log.w(TAG, "Document is EXPIRED")
        }

        result.fields.forEach { (key, value) -> Log.d(TAG, "$key: $value") }

        result.errors.forEach { Log.e(TAG, "[${it.code}] ${it.message}") }
        result.warnings.forEach { Log.w(TAG, "[${it.code}] ${it.message}") }
    } catch (t: Throwable) {
        // e.g. the native classifier is unavailable on a non-arm64 device
        Log.e(TAG, "PDF417 verification failed", t)
    }
}
✦ The verdict is independent of expiry — an authentic but expired card is still REAL, with expiry surfaced via attestations.documentExpired. PDF417Verdict.ERROR is returned — rather than an exception thrown — for a blank or non-AAMVA payload, or when the SDK has not been initialized; inspect errors for the reason (1000 SDK not initialized, 1001 classification failed, 1002 no profile).
⚠ The PDF417 classifier ships inside the tap2idSdk artifact — no additional dependency is required. It uses native code and requires an arm64 device. Cryptographic verification is only available for issuing authorities that publish signing keys (currently CA, NY, and VA); for all other states crypto.checked is false and the verdict rests on the classifier alone.

Utility Methods

Get SDK Version

Returns the 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")