Tap2iD SDK for Windows - API Reference
API reference for the Tap2iD Windows SDK. Covers SDK initialization, mDL verification over BLE and NFC, and PDF417 barcode verification for physical driver's licenses.
Overview
The Tap2iD Windows SDK verifies ISO 18013-5 mobile driver's licenses (mDLs) over BLE and NFC, and AAMVA PDF417 barcodes on physical driver's licenses. Use Tap2iDSdk: initialize it once with your license key, then call VerifyMdocAsync or VerifyPdf417Async for each session.
- Language: C# / .NET 8.0
- Platform: Windows 11 (x64), build 22000 or later
- Transport: BLE, NFC.
- Standard: ISO/IEC 18013-5:2021
- PDF417: AAMVA barcode verification with CA / NY / VA cryptographic authenticity v2.2.0+
- Readers: Access-IS ATOM / ATOM3K and HID TripTick Halo 210, Bluetooth readiness check, and age attestation v2.3.0+
Installation
Add the Credence ID Nexus repository to your NuGet sources in Visual Studio, then install Tap2iDSdk. Requires .NET 8.0 and Windows 11+.
NuGet Source URL
https://nexus.credenceid.com/repository/tap2id-sdk-nuget/
Auto-installed dependencies
Installing Tap2iDSdk 2.3.0 pulls in the following package versions:
Tap2iDSdk — it is not a separate NuGet dependency to restore. Tap2iDSdk.HidAtom (1.1.0) is a separate, optional package for Access-IS ATOM / ATOM3K readers and is not pulled in automatically. See Access-IS ATOM readers.
Initialize SDK
Call InitSdk once at startup, before any mDL verification. Pass your license key in CoreSdkConfig, and attach result callbacks through InitSdkResultListener.
/// Initializes the SDK with the provided configuration.
public void InitSdk(
CoreSdkConfig coreSdkConfig,
InitSdkResultListener sdkInitlistener
);
CoreSdkConfig
| Property | Type | Default | Description |
|---|---|---|---|
| ApiKey | string | "" | Your Verify with Credence license key. required |
| PackageName | string | "" | Application package identifier. optional |
InitSdkResultListener delegates
Example
var config = new CoreSdkConfig { ApiKey = "YOUR_API_KEY_HERE" };
var listener = new InitSdkResultListener
{
OnInitializationSuccess = result => Console.WriteLine("SDK ready"),
OnInitializationFailure = (e, msg) => Console.WriteLine($"Failed: {e}: {msg}")
};
sdk.InitSdk(config, listener);
Check Bluetooth readiness v2.3.0+
Before InitSdk, call CheckBlePeripheralSupportAsync to find out whether the PC can run an mDL transaction over Bluetooth. On the Microsoft Bluetooth stack it reports whether the adapter supports Bluetooth Low Energy and the peripheral role, and whether Bluetooth is switched on. If the adapter cannot be used, a transaction fails at once with a specific error instead of timing out.
public Task<BluetoothStatus> CheckBlePeripheralSupportAsync();
// Tap2iDBluetoothCommon
public class BluetoothStatus
{
public bool IsSupported { get; set; } // true when the adapter can run a BLE transaction
public string Message { get; set; } // what was found, or why it cannot be used
}
BluetoothStatus status = await sdk.CheckBlePeripheralSupportAsync();
if (!status.IsSupported)
{
// BLE transactions will fail: show status.Message and ask for a supported dongle.
// PDF417 barcode verification does not need Bluetooth and still works.
Console.WriteLine($"Bluetooth not ready: {status.Message}");
}
sdk.InitSdk(config, listener);
Verify mDL
Call VerifyMdocAsync with the engagement string from a QR scan, NFC tap, or BLE discovery. Subscribe to DelegateVerifyState for progress updates.
public Task<Tap2iDResult> VerifyMdocAsync(
MdocConfig mdocConfig,
DelegateVerifyState State,
CancellationToken cancellationToken = default
);
MdocConfig Properties
| Property | Type | Default | Description |
|---|---|---|---|
| DeviceEngagementString | string | "" | Encoded engagement payload. Required for QR code engagement |
| EngagementMode | DeviceEngagementMode | QrCode | Physical capture method (QrCode or Nfc). |
| BleWriteOption | BleWriteOption | Write | BLE write mode: Write or WriteWithoutResponse. |
| IsReaderAuthentication | bool | false | Present verifier certificate to holder device. |
| NfcReaderNameFilter | string? | null | Substring to select a specific NFC reader. optional |
| NfcDeviceEngagementTimeout | int | 30s | NFC engagement wait time. Range: 5–300. |
| BleConnectionTimeout | int | 10s | BLE scan + connect phase. Range: 5–300. |
| BleConsentAndDataTransferTimeout | int | 30s | Consent + data transfer after connection. Range: 5–300. |
| QrDeviceEngagementTimeout | int | 60s | How long the SDK waits for a QR scan when it captures the QR itself. Range: 5–300. |
| QrPeripheral | PeripheralModel? | null | Reader that captures the engagement QR. With HidAtom or HidAtom3K and an empty DeviceEngagementString, the SDK captures the QR itself. optional |
| NfcPeripheral | PeripheralModel? | null | Reader used for NFC engagement. null uses the default reader. optional |
| BlePeripheral | PeripheralModel? | null | Reader used for the BLE transfer. null uses the configured transport. Only set a combo reader (e.g. P35) when its BLE modem is connected. optional |
PeripheralModel values
Defined in Tap2iDBluetoothCommon. HidAtom, HidAtom3K and HidHalo are recognised from 2.3.0.
VerifyState Lifecycle
Example
var config = new MdocConfig
{
DeviceEngagementString = qrCodeData,
EngagementMode = DeviceEngagementMode.QrCode,
BleConnectionTimeout = 15,
BleConsentAndDataTransferTimeout = 45
};
Tap2iDResult result = await sdk.VerifyMdocAsync(config, new DelegateVerifyState
{
OnVerifyState = state => Console.WriteLine($"→ {state}")
});
Handling Results
Both VerifyMdocAsync and VerifyPdf417Async resolve to a result object describing the outcome of the transaction. The mDoc result, Tap2iDResult, supports multi-document transactions — for example, receiving an mDL and a Photo ID in the same session.
| Property | Type | Description |
|---|---|---|
| ResultError | Tap2iDResultError | The global result of the transaction, e.g. OK, ERROR_CONNECTION. |
| Documents | List<VerifiedDocument> | All documents retrieved and verified in this session. |
| Identity | CIdentity? | Flat identity object. deprecated — prefer Documents |
VerifiedDocument
| Property | Type | Description |
|---|---|---|
| DocType | string | ISO document type, e.g. org.iso.18013.5.1.mDL |
| Authentication | AuthenticationResult | Cryptographic and trust verification for this document. |
| Namespaces | List<NamespaceData> | Attributes organized by namespace → key → value. |
ResultError before accessing Documents: a non-OK result may return an empty or partial list.
Retrieve Data
Iterate through Namespaces and their Items to access attribute values. Binary fields like portrait and signature_usual_mark are returned as byte[].
foreach (var doc in result.Documents)
foreach (var ns in doc.Namespaces)
foreach (var item in ns.Items)
{
if (item.Key == "portrait" && item.Value is byte[] img)
{ /* render as ImageSource */ continue; }
Console.WriteLine($"{item.Key}: {item.Value}");
}
org.iso.18013.5.1. Common fields: family_name, given_name, birth_date, document_number, portrait, driving_privileges.
Security Status
Each VerifiedDocument has an AuthenticationResult with five checks. Review them before trusting the data.
var auth = doc.Authentication;
bool isTrusted = auth.TrustAttributes.IsIssuerTrusted;
bool deviceSigned = auth.SecurityChecks.IsDeviceSignedValid;
bool issuerSigned = auth.SecurityChecks.IsIssuerSignedValid;
bool digestsValid = auth.SecurityChecks.AreDigestsValid;
var msoStatus = auth.MsoValidity.Status; // Valid | NotYetValid | Expired
foreach (var err in auth.ValidationErrors)
Console.WriteLine($"Error: {err.Message}");
| Property | Type | Description |
|---|---|---|
| TrustAttributes.IsIssuerTrusted | bool | Issuing CA found in the SDK trust store. |
| SecurityChecks.IsDeviceSignedValid | bool | ECDSA/MAC device signature passes verification. |
| SecurityChecks.IsIssuerSignedValid | bool | Mobile Security Object signature is valid. |
| SecurityChecks.AreDigestsValid | bool | Data item hashes match MSO digests. |
| MsoValidity.Status | MsoStatus | Valid, NotYetValid, or Expired. |
| ValidationErrors | List<ValidationError> | Detailed issues. Empty when all checks pass. |
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 — from a camera decode, an HID/keyboard-wedge scanner, or a dedicated barcode reader — and pass it to VerifyPdf417Async. An AAMVA payload starts with the compliance indicator @, a convenient way to route a scanned value to PDF417 vs. mDoc engagement.
/// Verifies a PDF417 driver's-license barcode.
public Task<Pdf417VerificationResult> VerifyPdf417Async(
Pdf417VerificationRequest request
);
public record Pdf417VerificationRequest(string Pdf417Value);
Pdf417VerificationResult
| Property | Type | Description |
|---|---|---|
| Verdict | Pdf417Verdict | Real, Fake, Suspicious, or Error. |
| ConfidenceLevel | int | 0–100. |
| StateCode | string? | Issuing state, e.g. CA. null if unparseable. |
| Fields | IReadOnlyDictionary<string, object?> | ISO mDL attribute names → values, e.g. family_name, given_name, birth_date, expiry_date. |
| Errors | IReadOnlyList<Pdf417ValidationError> | Code + message. Codes below 5000 are warnings, not failures. |
| Crypto | Pdf417CryptoResult | Cryptographic authenticity check for supported issuing authorities (CA, NY, VA). |
| Attestations | Pdf417Attestations | Profile-driven attestations: document expiry and minimum-age. |
Pdf417CryptoResult & Pdf417Attestations
public record Pdf417CryptoResult(
string Authority, // "CA_DMV", "NY_DMV", "VA_DMV"
bool Checked, // true when a signature check was evaluated
bool Verified, // true when the signature is cryptographically valid
string? Detail
);
public record Pdf417Attestations(
bool DocumentExpired = false, // expiry date strictly before today
bool? AgeAttestationPassed = null // null if age check not requested
);
Verdict values
Example
try
{
var result = await verifier.VerifyPdf417Async(new Pdf417VerificationRequest(barcode));
Console.WriteLine($"Verdict: {result.Verdict} ({result.ConfidenceLevel}%) State: {result.StateCode}");
if (result.Crypto.Checked)
Console.WriteLine($"Crypto ({result.Crypto.Authority}): {result.Crypto.Verified}");
if (result.Attestations.DocumentExpired)
Console.WriteLine("Document is EXPIRED");
foreach (var field in result.Fields)
Console.WriteLine($"{field.Key}: {field.Value}");
}
catch (Pdf417ImplException ex)
{
Console.WriteLine($"PDF417 error [{ex.Error}]: {ex.Message}");
}
Real, with expiry surfaced via Attestations.DocumentExpired. Verdict.Error is returned for a blank / non-AAMVA payload, or when the SDK has not been initialized.
Age Attestation
The SDK checks the minimum age set in your Verify with Credence profile (18+, 21+, or a custom age) and reports the result to the portal. Age attestation is independent of authenticity: an authentic licence held by someone under the minimum age is still Real.
PDF417
Read Attestations.AgeAttestationPassed on the Pdf417VerificationResult.
| Value | Meaning |
|---|---|
| true | The holder meets the profile's minimum age. |
| false | The holder is under the minimum age. The portal records ERROR_AGE_VERIFICATION_FAIL (316). |
| null | The profile does not request an age check. |
string age = result.Attestations.AgeAttestationPassed switch
{
true => "Passed",
false => "Failed: under the minimum age",
null => "Not requested",
};
mDL
For an mDL, the SDK checks every age_over_NN element the profile requests (for example age_over_21). A false value is reported to the portal as an age verification failure. Read the element from the document's Namespaces to show the result in your app:
foreach (var ns in doc.Namespaces)
foreach (var item in ns.Items)
{
if (item.Key == "age_over_21" && item.Value is bool isOver21)
Console.WriteLine(isOver21 ? "Age 21+ ✓" : "Under 21 ✗");
}
Access-IS ATOM / ATOM3K Readers
The optional Tap2iDSdk.HidAtom package reads engagement QR codes and PDF417 barcodes from Access-IS ATOM and ATOM3K readers. It requires the Access-IS Document Reader (ADRS) to be installed; the ATOM3K needs ADRS 6.0.0.4 or newer.
public static class HidAtomBarcodeReader
{
// Starts the Access-IS engine. Returns false when ADRS is not installed.
public static bool Start();
// Waits for an mdoc: engagement QR. Throws TimeoutException if nothing is scanned.
public static Task<string> CaptureEngagementAsync(int timeoutSeconds, CancellationToken cancellationToken = default);
// Waits for an AAMVA PDF417 barcode. Throws TimeoutException if nothing is scanned.
public static Task<string> CapturePdf417Async(int timeoutSeconds, CancellationToken cancellationToken = default);
}
Example
// Start once, after InitSdk succeeds. The ATOM3K camera needs about 40 s to start.
if (!HidAtomBarcodeReader.Start())
return; // Access-IS Document Reader (ADRS) is not installed
try
{
string barcode = await HidAtomBarcodeReader.CapturePdf417Async(timeoutSeconds: 300);
var result = await sdk.VerifyPdf417Async(new Pdf417VerificationRequest(barcode));
}
catch (TimeoutException)
{
// Nothing scanned in this window: call CapturePdf417Async again to keep listening.
}
QrPeripheral = PeripheralModel.HidAtom and leave DeviceEngagementString empty, the SDK uses the same QR capture, so do not also call CaptureEngagementAsync yourself. A capture only receives scans while it is waiting, so start a new one after each scan or timeout.
Class Reference
NfcCommunicationException
Thrown when an error occurs during NFC data exchange.
| Constructor | Description |
|---|---|
NfcCommunicationException(string message) | Creates exception with descriptive message. |
NfcCommunicationException(string message, Exception inner) | Wraps the underlying NFC failure. |
CommunicationBleCentralClientMode
Manages the BLE Central role for reading from a holder device acting as a peripheral.
| Member | Type | Description |
|---|---|---|
| SetTimeout(int) | void | Overrides BLE operation timeout in seconds. |
| BleWriteOption | BleWriteOption | Acknowledged write or fire-and-forget mode. |
| ConsentStarted | EventHandler? | Fires when holder device begins consent flow. |
| ConsentEnded | EventHandler? | Fires when consent flow completes. |
| MessageReceived | MessageReceivedHandler? | Raw BLE message as byte[]. |
Error Codes
Returned via Tap2iDResult.ResultError and the OnInitializationFailure callback.
SDK / License
| Enum name | Value | Description |
|---|---|---|
| OK | 0 | No error. |
| LicenceError | 1 | License is invalid. |
| NoNFCTagDetected | 2 | No NFC tag was presented. |
| LicenceExpiredLicenceError | 10 | License expired. |
| ApiExceptionLicenseError | 11 | Failed to verify license. |
Transaction / Connection
| Enum name | Value | Description |
|---|---|---|
| ERROR_INVALID_BARCODE / ERROR_INVALID_QR_CODE | 111 | Invalid QR code. |
| ERROR_NFC_STATIC_HANDOVER | 112 | NFC connection failed. |
| ERROR_NFC_NEGOTIATED_HANDOVER | 113 | NFC connection failed. |
| ERROR_NFC_NOT_ENABLED | 114 | NFC not enabled. |
| ERROR_DE_CONNECTION_TIMEOUT | 115 | Bluetooth connection timed out. |
| ERROR_NFC_TAG | 116 | NFC connection failed, not an ID. |
| ERROR_GENERAL | 117 | Unknown error. |
| OperationCancelled | 130 | Operation cancelled by caller. |
| ERROR_GENERAL_NFC_DEVICE_ENGAGEMENT | 132 | Unknown NFC error during device engagement. |
| ERROR_TAG_LOST | 133 | NFC tag lost. |
| ERROR_BLE_CONNECTION | 212 | Bluetooth connection failed. |
| ERROR_BLE_L2CAP | 213 | Bluetooth L2CAP connection failed. |
| ERROR_DR_CONNECTION_TIMEOUT | 214 | Data retrieval timed out. |
| ERROR_NFC_READER_NOT_AVAILABLE | 215 | No NFC reader connected. Reported at once from 2.3.0, instead of after 30 s. |
| ERROR_CONSENT_DENIED_FOR_ALL | 216 | Holder denied sharing all data. |
| ERROR_CONSENT_DENIED_FOR_FEW | 217 | Holder denied sharing some data. |
| ERROR_DR_UNKNOWN_ERROR | 218 | Data retrieval failed, unknown error. |
| ERROR_CONSENT_DENIED_FOR_ALL_ATTRIBUTE | 219 | Consent denied, no attribute returned. |
| ERROR_PERIPHERAL_NOT_AVAILABLE | 220 | The selected reader is not connected. |
| ERROR_AGE_VERIFICATION_FAIL | 316 | The holder is under the profile's minimum age. See Age Attestation. |
Supported Hardware
BLE Dongles
The BLE transport uses the Bumble library and requires a compatible USB Bluetooth adapter.
| VID/PID | Device |
|---|---|
| 0BDA / A728 | Realtek BLE Adapter |
| 0BDA / 8771 | Startech Adapter / USBA-BLUETOOTH-V5-C2 |
NFC Readers
Any PC/SC-compatible USB NFC reader. Most readers work with the standard Windows drivers.
QR / Barcode
Any built-in or USB webcam, or USB barcode scanner operating as a standard HID / keyboard wedge device.
| Reader | Support |
|---|---|
| Access-IS ATOM / ATOM3K | QR device engagement and PDF417 capture through Tap2iDSdk.HidAtom. Requires Access-IS Document Reader (ADRS); ATOM3K needs 6.0.0.4+. v2.3.0+ |
| HID TripTick Halo 210 | Detected as a peripheral (PeripheralModel.HidHalo). v2.3.0+ |