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+.

ℹ Register on the Verify with Credence to get your license key before integrating the SDK.

NuGet Source URL

nuget.config
https://nexus.credenceid.com/repository/tap2id-sdk-nuget/

Auto-installed dependencies

Installing Tap2iDSdk 2.3.0 pulls in the following package versions:

BluetoothWinUI 1.3.0
BluetoothBumble 1.2.3
BluetoothESP32 1.1.1
BluetoothP35 1.0.1
Tap2idBluetoothCommon 1.4.0
Logging 1.3.0
ℹ The PDF417 barcode classifier is statically linked into 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.
01

Initialize SDK

Call InitSdk once at startup, before any mDL verification. Pass your license key in CoreSdkConfig, and attach result callbacks through InitSdkResultListener.

Tap2iDSdk: InitSdk()
/// Initializes the SDK with the provided configuration.
public void InitSdk(
    CoreSdkConfig        coreSdkConfig,
    InitSdkResultListener sdkInitlistener
);

CoreSdkConfig

PropertyTypeDefaultDescription
ApiKeystring""Your Verify with Credence license key. required
PackageNamestring""Application package identifier. optional

InitSdkResultListener delegates

OnInitializationSuccess(SdkInitializationResult result)
Invoked when initialization completes successfully.
OnInitializationFailure(Tap2iDResultError error, string ErrorMessage)
Invoked on failure. Provides structured error code and diagnostic message.

Example

C#
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.

Tap2iDSdk: CheckBlePeripheralSupportAsync()
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
}
C#: Check Bluetooth, then initialize
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);
ℹ Bumble without a dongle. From 2.3.0, when the Bumble transport is configured and no supported Bluetooth dongle is attached, the SDK uses the PC's own Bluetooth radio.
02

Verify mDL

Call VerifyMdocAsync with the engagement string from a QR scan, NFC tap, or BLE discovery. Subscribe to DelegateVerifyState for progress updates.

Tap2iDSdk: VerifyMdocAsync()
public Task<Tap2iDResult> VerifyMdocAsync(
    MdocConfig          mdocConfig,
    DelegateVerifyState State,
    CancellationToken   cancellationToken = default
);

MdocConfig Properties

PropertyTypeDefaultDescription
DeviceEngagementStringstring""Encoded engagement payload. Required for QR code engagement
EngagementModeDeviceEngagementModeQrCodePhysical capture method (QrCode or Nfc).
BleWriteOptionBleWriteOptionWriteBLE write mode: Write or WriteWithoutResponse.
IsReaderAuthenticationboolfalsePresent verifier certificate to holder device.
NfcReaderNameFilterstring?nullSubstring to select a specific NFC reader. optional
NfcDeviceEngagementTimeoutint30sNFC engagement wait time. Range: 5–300.
BleConnectionTimeoutint10sBLE scan + connect phase. Range: 5–300.
BleConsentAndDataTransferTimeoutint30sConsent + data transfer after connection. Range: 5–300.
QrDeviceEngagementTimeoutint60sHow long the SDK waits for a QR scan when it captures the QR itself. Range: 5–300.
QrPeripheralPeripheralModel?nullReader that captures the engagement QR. With HidAtom or HidAtom3K and an empty DeviceEngagementString, the SDK captures the QR itself. optional
NfcPeripheralPeripheralModel?nullReader used for NFC engagement. null uses the default reader. optional
BlePeripheralPeripheralModel?nullReader 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.

None
SystemDefault
BumbleDongle
Esp32
P35
HidAtom
HidAtom3K
HidHalo
HidOmniKey

VerifyState Lifecycle

DeviceEngagementStarted
DeviceEngagementEnded
DeviceConnectionStarted
DeviceConnectionEnded
UserConsentStarted
UserConsentEnded
DataTransferStarted
DataTransferEnded
DataValidationStarted
DataValidationEnded

Example

C#: QR Code Verification
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}")
});
03

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.

PropertyTypeDescription
ResultErrorTap2iDResultErrorThe global result of the transaction, e.g. OK, ERROR_CONNECTION.
DocumentsList<VerifiedDocument>All documents retrieved and verified in this session.
IdentityCIdentity?Flat identity object. deprecated — prefer Documents

VerifiedDocument

PropertyTypeDescription
DocTypestringISO document type, e.g. org.iso.18013.5.1.mDL
AuthenticationAuthenticationResultCryptographic and trust verification for this document.
NamespacesList<NamespaceData>Attributes organized by namespace → key → value.
⚠ Always check ResultError before accessing Documents: a non-OK result may return an empty or partial list.
04

Retrieve Data

Iterate through Namespaces and their Items to access attribute values. Binary fields like portrait and signature_usual_mark are returned as byte[].

C#: Extracting Document Data
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}");
}
✦ Primary mDL namespace: org.iso.18013.5.1. Common fields: family_name, given_name, birth_date, document_number, portrait, driving_privileges.
05

Security Status

Each VerifiedDocument has an AuthenticationResult with five checks. Review them before trusting the data.

C#: Security Checks
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}");
PropertyTypeDescription
TrustAttributes.IsIssuerTrustedboolIssuing CA found in the SDK trust store.
SecurityChecks.IsDeviceSignedValidboolECDSA/MAC device signature passes verification.
SecurityChecks.IsIssuerSignedValidboolMobile Security Object signature is valid.
SecurityChecks.AreDigestsValidboolData item hashes match MSO digests.
MsoValidity.StatusMsoStatusValid, NotYetValid, or Expired.
ValidationErrorsList<ValidationError>Detailed issues. Empty when all checks pass.
06

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.

Tap2iDSdk: VerifyPdf417Async()
/// Verifies a PDF417 driver's-license barcode.
public Task<Pdf417VerificationResult> VerifyPdf417Async(
    Pdf417VerificationRequest request
);

public record Pdf417VerificationRequest(string Pdf417Value);

Pdf417VerificationResult

PropertyTypeDescription
VerdictPdf417VerdictReal, Fake, Suspicious, or Error.
ConfidenceLevelint0–100.
StateCodestring?Issuing state, e.g. CA. null if unparseable.
FieldsIReadOnlyDictionary<string, object?>ISO mDL attribute names → values, e.g. family_name, given_name, birth_date, expiry_date.
ErrorsIReadOnlyList<Pdf417ValidationError>Code + message. Codes below 5000 are warnings, not failures.
CryptoPdf417CryptoResultCryptographic authenticity check for supported issuing authorities (CA, NY, VA).
AttestationsPdf417AttestationsProfile-driven attestations: document expiry and minimum-age.

Pdf417CryptoResult & Pdf417Attestations

C#
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

Real
Fake
Suspicious
Error

Example

C#: Verify a PDF417 Barcode
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}");
}
ℹ The verdict is independent of expiry — an authentic but expired card is still 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.
07 · New in 2.3.0

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.

ValueMeaning
trueThe holder meets the profile's minimum age.
falseThe holder is under the minimum age. The portal records ERROR_AGE_VERIFICATION_FAIL (316).
nullThe profile does not request an age check.
C#: PDF417 age attestation
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:

C#: mDL age_over element
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 ✗");
}
08 · New in 2.3.0

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.

Tap2iDSdk.HidAtom: HidAtomBarcodeReader
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

C#: Verify a licence scanned on the ATOM
// 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.
}
⚠ Only one capture of each kind can wait at a time. If you set 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.

Reference

Class Reference

NfcCommunicationException

Thrown when an error occurs during NFC data exchange.

ConstructorDescription
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.

MemberTypeDescription
SetTimeout(int)voidOverrides BLE operation timeout in seconds.
BleWriteOptionBleWriteOptionAcknowledged write or fire-and-forget mode.
ConsentStartedEventHandler?Fires when holder device begins consent flow.
ConsentEndedEventHandler?Fires when consent flow completes.
MessageReceivedMessageReceivedHandler?Raw BLE message as byte[].
Reference

Error Codes

Returned via Tap2iDResult.ResultError and the OnInitializationFailure callback.

SDK / License

Enum nameValueDescription
OK0No error.
LicenceError1License is invalid.
NoNFCTagDetected2No NFC tag was presented.
LicenceExpiredLicenceError10License expired.
ApiExceptionLicenseError11Failed to verify license.

Transaction / Connection

Enum nameValueDescription
ERROR_INVALID_BARCODE / ERROR_INVALID_QR_CODE111Invalid QR code.
ERROR_NFC_STATIC_HANDOVER112NFC connection failed.
ERROR_NFC_NEGOTIATED_HANDOVER113NFC connection failed.
ERROR_NFC_NOT_ENABLED114NFC not enabled.
ERROR_DE_CONNECTION_TIMEOUT115Bluetooth connection timed out.
ERROR_NFC_TAG116NFC connection failed, not an ID.
ERROR_GENERAL117Unknown error.
OperationCancelled130Operation cancelled by caller.
ERROR_GENERAL_NFC_DEVICE_ENGAGEMENT132Unknown NFC error during device engagement.
ERROR_TAG_LOST133NFC tag lost.
ERROR_BLE_CONNECTION212Bluetooth connection failed.
ERROR_BLE_L2CAP213Bluetooth L2CAP connection failed.
ERROR_DR_CONNECTION_TIMEOUT214Data retrieval timed out.
ERROR_NFC_READER_NOT_AVAILABLE215No NFC reader connected. Reported at once from 2.3.0, instead of after 30 s.
ERROR_CONSENT_DENIED_FOR_ALL216Holder denied sharing all data.
ERROR_CONSENT_DENIED_FOR_FEW217Holder denied sharing some data.
ERROR_DR_UNKNOWN_ERROR218Data retrieval failed, unknown error.
ERROR_CONSENT_DENIED_FOR_ALL_ATTRIBUTE219Consent denied, no attribute returned.
ERROR_PERIPHERAL_NOT_AVAILABLE220The selected reader is not connected.
ERROR_AGE_VERIFICATION_FAIL316The holder is under the profile's minimum age. See Age Attestation.
Hardware

Supported Hardware

BLE Dongles

The BLE transport uses the Bumble library and requires a compatible USB Bluetooth adapter.

VID/PIDDevice
0BDA / A728Realtek BLE Adapter
0BDA / 8771Startech 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.

ReaderSupport
Access-IS ATOM / ATOM3KQR 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 210Detected as a peripheral (PeripheralModel.HidHalo). v2.3.0+
✦ Credence ID recommends the Mini BT540 or Mini BT542 USB adapters for best Bluetooth range and reliability.