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
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.
suspend fun initSdk(
config: SdkConfig,
initSdkListener: InitSdkResultListener
)
Parameters
| Parameter | Type | Description |
|---|---|---|
| config | SdkConfig | SDK configuration containing license key and application context. required |
| initSdkListener | InitSdkResultListener | Callback interface for initialization results. required |
SdkConfig
data class SdkConfig(
val apiKey: String,
val applicationContext: Context
)
InitSdkResultListener
interface InitSdkResultListener {
fun onInitializationSuccess(result: SdkInitializationResult)
fun onInitializationFailure(error: Error)
}
Example
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 that sets the verification method: QR code, NFC, or both. Subscribe to MdocVerificationListener for lifecycle events.
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
Sets QR code verification, NFC verification, or both. At least one of qrConfig or nfcConfig must be non-null.
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.
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
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
val nfcConfig = EngagementConfig(
nfcConfig = NfcConfig(activity = this)
)
lifecycleScope.launch {
Tap2iDSdk.verifyMdoc(nfcConfig, verificationListener)
}
Example: Dual Mode (QR + NFC)
val dualConfig = EngagementConfig(
qrConfig = QrConfig(mDocString = scannedQrCode),
nfcConfig = NfcConfig(activity = this)
)
lifecycleScope.launch {
Tap2iDSdk.verifyMdoc(dualConfig, verificationListener)
}
Handle Results
The onVerificationCompleted callback returns a VerificationResult with the credential attributes and the outcome of each security check.
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. |
isIssuerSignedAuthenticated and isDeviceSignedAuthenticated before trusting the credential data.
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.
suspend fun verifyPdf417(
request: Pdf417VerificationRequest
): Pdf417VerificationResult
Parameters
| Parameter | Type | Description |
|---|---|---|
| request | Pdf417VerificationRequest | Wraps the raw AAMVA PDF417 string. required |
data class Pdf417VerificationRequest(val pdf417Value: String)
Pdf417VerificationResult
Unlike verifyMdoc, this is a single suspending call with no lifecycle listener — the result is returned directly.
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
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
)
PDF417ClassifierCode.WARNING_CODE_FLOOR (5000) is the boundary: codes at or above it are warnings, codes below it are errors.
Verdict values
Example
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)
}
}
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).
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.
fun getSdkVersion(): String
val version = Tap2iDSdk.getSdkVersion()
Log.d("SDK", "Using Tap2iD SDK version: version")