Tap2iD SDK for iOS - API Reference

API reference for Tap2iDVerifierSDK 2.3.1. Covers SDK initialization, mDL verification over BLE, NFC, and QR, PDF417 barcode verification for physical driver's licenses, and reading IDs in Apple Wallet with Tap to Present ID.

Overview

Use Tap2iDVerifySDK.shared: the singleton that conforms to the CoreTap2iDVerifySDK protocol. Initialize it once at startup, then call verifyMdoc for each mDL verification session, verifyPdf417 to verify a physical driver's-license barcode, or verifyMdocWithEntitlement to read an ID from Apple Wallet.

  • Language: Swift 5.9+
  • Platform: iOS 17.0+ / iPadOS 17.0+
  • Transport: BLE, NFC, QR, and Tap to Present ID (Apple Wallet) v2.3.0+
  • Standard: ISO/IEC 18013-5:2021
  • PDF417: Verified via a dedicated async API (verifyPdf417), independent of mDoc engagement v2.0.1+
ℹ Register on the Verify with Credence to get your license key before integrating the SDK.
01

initSdk

Initializes the SDK with the given configuration. Call once at app startup before any mDL verification session.

CoreTap2iDVerifySDK: initSdk()
func initSdk(
    config: CoreSdkConfig,
    initResult: @escaping (LicenseKeyVerificationResult) -> Void
)

Parameters

ParameterTypeDescription
configCoreSdkConfigSDK configuration carrying the API key. required
initResult(LicenseKeyVerificationResult) -> VoidReceives a LicenseKeyVerificationResult. required

CoreSdkConfig

Swift
public struct CoreSdkConfig {
    public var apiKey: String
    public init(apiKey: String)
}

LicenseKeyVerificationResult

Swift
public struct LicenseKeyVerificationResult {
    public let isValid: Bool
    public let expiryDate: Int64?      // epoch milliseconds
    public let profileName: String?
    public let error: Error?
}

Example

Swift
let config = CoreSdkConfig(apiKey: "")
Tap2iDVerifySDK.shared.initSdk(config: config) { result in
    if result.isValid {
        // ready
    } else {
        print(result.error?.localizedDescription ?? "license invalid")
    }
}
02

verifyMdoc

Starts verification of a mobile document (mDL / mDoc). Supports NFC, QR code, and external NFC reader engagement. PDF417 barcodes use verifyPdf417. Returns an Error?; nil means the session started.

CoreTap2iDVerifySDK: verifyMdoc()
func verifyMdoc(
    engagementConfig: EngagementConfig,
    delegate: Tap2iDVerifySDKDelegate?,
    readerDelegate: NfcExternalReaderDelegate? = nil
) -> Error?

Progress and results arrive on the delegate; the return value is non-nil only when verification could not be started.

Parameters

ParameterTypeDescription
engagementConfigEngagementConfigEngagement method: .nfc, .qrCode, or .nfcExternalReader. required
delegateTap2iDVerifySDKDelegate?Verification lifecycle delegate for stage and result callbacks. optional
readerDelegateNfcExternalReaderDelegate?External NFC reader delegate. Only required when using .nfcExternalReader. optional

EngagementConfig

Swift: EngagementConfig enum
public enum EngagementConfig {
    case nfc                // NFC engagement
    case qrCode(String)     // QR code engagement
    case nfcExternalReader  // external NFC reader over cable
}
⚠ Changed in 2.0.1 — the pdf417(String) case has been removed. PDF417 barcodes are verified with verifyPdf417, which runs the classifier and the jurisdiction signature checks. The removed case performed neither.

stopMonitoring

Stops monitoring for NFC tags or external NFC readers. Call this when your view disappears or verification should be cancelled.

Swift
func stopMonitoring()
03

verifyPdf417

Verifies a PDF417 barcode from the back of a driver's licence using the on-device classifier and jurisdiction cryptography. This is the only PDF417 entry point. Unlike verifyMdoc, it is async, returns its result directly, and emits no VerificationStage callbacks.

CoreTap2iDVerifySDK: verifyPdf417()
func verifyPdf417(
    request: Pdf417VerificationRequest
) async throws -> Pdf417VerificationResult

Throws Pdf417ImplError

Parameters

ParameterTypeDescription
requestPdf417VerificationRequestWraps the raw AAMVA PDF417 string. required

PDF417 Models

Swift
public struct Pdf417VerificationRequest {
    public let pdf417Value: String
    public init(pdf417Value: String)
}

public struct Pdf417VerificationResult {
    public let verdict: PDF417Verdict
    public let nativeVerdict: String        // raw classifier token
    public let confidenceLevel: Int
    public let stateCode: String?           // e.g. "CA"
    public let fields: [String: Any?]       // ISO 18013-5 attribute names
    public let errors: [PDF417ValidationError]
    public let cryptoVerification: CryptoVerification

    public func toJsonString() -> String?
}

public enum PDF417Verdict: String {
    case authentic
    case likelyAuthentic
    case likelyFraudulent
    case error
}

public struct CryptoVerification {
    public let authority: String   // e.g. "CA_DMV"
    public let checked: Bool
    public let verified: Bool
    public let detail: String

    public static let none: CryptoVerification
}

public struct PDF417ValidationError {
    public let code: Int
    public let message: String
}

public enum Pdf417ImplError: Error {
    case sdkNotInitialized
    case classificationFailed
    case noProfileDefined
}
ℹ Pdf417ImplError conforms to LocalizedError, so errorDescription, failureReason, and recoverySuggestion carry user-readable text.

Verdict values

authentic
likelyAuthentic
likelyFraudulent
error

Example

Swift
do {
    let request = Pdf417VerificationRequest(pdf417Value: scannedBarcode)
    let result  = try await Tap2iDVerifySDK.shared.verifyPdf417(request: request)
    print(result.verdict.rawValue, result.confidenceLevel)
} catch {
    print(error.localizedDescription)
}
✦ Reading the crypto outcome. cryptoVerification.checked says whether a jurisdiction signature check was attempted; verified says whether it passed. Both false means the barcode carried no verifiable signature — not that it failed.
⚠ Profile requirement. Your VwC profile must include an aamva.pdf417 document request. Without it the SDK throws Pdf417ImplError.noProfileDefined.
04 · New in 2.3.0

verifyMdocWithEntitlement

Runs an Apple Tap to Present ID request. .display shows the requested elements to the verifier through iOS and returns only the outcome. .data reads the attributes in your verification profile and verifies them like verifyMdoc, with no fallback to another engagement.

CoreTap2iDVerifySDK: verifyMdocWithEntitlement()
func verifyMdocWithEntitlement(
    request: ProximityReaderRequest,
    delegate: ProximityReaderDelegate
) -> ProximityReaderError?

Progress, the result and errors go to the delegate. The return value is .sdkNotInitialized when initSdk has not completed, otherwise nil.

Parameters

ParameterTypeDescription
requestProximityReaderRequest.display(document:elements:) or .data. required
delegateProximityReaderDelegateReceives stage callbacks, errors and the outcome or result. required
⚠ Requires Apple's Tap to Present ID entitlements, and for data requests a Brand ID and Key ID in Verify with Credence. See the Integration Guide.

Example

Swift
let error = Tap2iDVerifySDK.shared.verifyMdocWithEntitlement(request: .data, delegate: self)

isProximityReaderSupported

Whether this device can run Tap to Present ID requests. The host app does not need to import ProximityReader.

CoreTap2iDVerifySDK: isProximityReaderSupported()
func isProximityReaderSupported() -> Bool

Tap to Present ID Models

Swift
public enum ProximityReaderRequest {
    case display(document: ProximityDocumentType, elements: [ProximityDisplayElement])
    case data   // elements come from the verification profile
}

public enum ProximityDocumentType: Equatable {
    case driversLicense
    case nationalIDCard(region: Locale.Region)   // iOS 18 and later
    case photoID                                 // iOS 26 and later
}

// Apple allows only these elements in a display request.
public enum ProximityDisplayElement: Hashable {
    case givenName
    case familyName
    case age
    case ageAtLeast(Int)
}

public enum ProximityDisplayOutcome {
    case approved
    case rejected
    case dismissed
}

public enum ProximityReaderStage {
    case PREPARE_READER
    case REQUEST_DOCUMENT
    case VALIDATE_RESPONSE    // data requests only
}

public enum ProximityReaderError: Error, Equatable {
    case sdkNotInitialized
}

ProximityReaderDelegate

All callbacks are delivered on the main thread. A data request delivers the same VerificationResult as verifyMdoc.

Swift: ProximityReaderDelegate
public protocol ProximityReaderDelegate: AnyObject {
    func onProximityReaderStageStarted(stage: ProximityReaderStage)
    func onProximityReaderStageCompleted(stage: ProximityReaderStage)
    func onProximityReaderError(stage: ProximityReaderStage?, error: CoreCredenceErrorStruct)
    func onDisplayRequestCompleted(outcome: ProximityDisplayOutcome)       // display requests
    func onVerificationCompleted(verificationResult: VerificationResult)   // data requests
}
Delegates

Tap2iDVerifySDKDelegate

Conform to this delegate to receive lifecycle callbacks during verification.

onVerificationStageStarted(stage: VerificationStage)
Called when a verification stage begins.
onVerificationStageError(stage: VerificationStage?, error: CoreCredenceErrorStruct?)
Called if a verification stage encounters an error.
onVerificationStageCompleted(stage: VerificationStage)
Called when a verification stage completes successfully.
onVerificationCompleted(verificationResult: VerificationResult?)
Called with the final verification result and all credential data.
Swift: Delegate Implementation
extension YourClass: Tap2iDVerifySDKDelegate {

    func onVerificationStageStarted(stage: VerificationStage) {
        // Handle verification stage start
    }

    func onVerificationStageError(
        stage: VerificationStage?,
        error: CoreCredenceErrorStruct?
    ) {
        // Handle verification error
    }

    func onVerificationStageCompleted(stage: VerificationStage) {
        // Handle verification stage completion
    }

    func onVerificationCompleted(
        verificationResult: VerificationResult?
    ) {
        // Handle final verification result
    }
}

NfcExternalReaderDelegate

The NfcExternalReaderDelegate protocol handles external NFC reader and smart card connection events.

Swift: NfcExternalReaderDelegate
public protocol NfcExternalReaderDelegate: AnyObject {

    func didDetectReaders()         // External NFC reader detected
    func didDisconnectFromReader()   // External reader disconnected
    func didDetectSmartCard()        // Smart card detected
    func didDisconnectFromSmartCard() // Smart card disconnected
}

CoreCredenceErrorStruct

Delivered by onVerificationStageError and onProximityReaderError. See Credential Verification Errors for the codes.

Swift: CoreCredenceErrorStruct
public struct CoreCredenceErrorStruct: Error {
    public var componentCode: Int
    public var combinedCode: Int     // the code listed in the errors guide
    public var errorMessage: String
}
ℹ combinedCode is public from 2.2.0. Earlier releases kept it internal, so host apps could not read it.
Reference

VerificationStage

Each stage of the mDL verification pipeline. Reported via onVerificationStageStarted, onVerificationStageCompleted, and onVerificationStageError.

Swift: VerificationStage enum
public enum VerificationStage {
    case NFC_ENGAGEMENT
    case QR_ENGAGEMENT
    case PDF417
    case CONNECTION
    case SEND_MDOC_REQUEST
    case READ_MDOC_RESPONSE
    case PARSE_MDOC_RESPONSE
    case VALIDATE_MDOC_RESPONSE
}
NFC_ENGAGEMENT
QR_ENGAGEMENT
PDF417
CONNECTION
SEND_MDOC_REQUEST
READ_MDOC_RESPONSE
PARSE_MDOC_RESPONSE
VALIDATE_MDOC_RESPONSE
⚠ PDF417 is never emitted from 2.0.1 — verifyPdf417 returns its result directly rather than reporting stages.

Result Models

Verification Result Model

The VerificationResult returned by onVerificationCompleted contains the credential documents and the overall verification status.

Swift: VerificationResult
public struct VerificationResult {
    public let documents: [VerifiedDocument]
    public let status: VerificationStatus
}

public struct VerifiedDocument {
    public let docType: String
    public let nameSpaces: [VerifiedNamespace]
    public let authentication: AuthenticationDetails
}

public struct VerifiedNamespace {
    public let name: String
    public let attributes: [String: Any?]
    public let requestedAttributeStatus: [String: Bool]
}

// Values in attributes are the element as the wallet encoded it. Date elements are
// String from 2.2.0 ("1971-09-01", or "2020-05-04T10:30:00Z" for a tdate), not Date.

public struct AuthenticationDetails {
    public let security: SecurityDetails
    public let msoValidity: MsoValidityDetails
    public let trust: TrustDetails
    public let errors: [String]

    // Derived from the three checks above.
    public var authenticationStatus: VerificationAuthenticationStatus { get }
}
PropertyTypeDescription
documents[VerifiedDocument]Array of verified documents from the mDL response.
statusVerificationStatusOverall result: success, partialSuccess, or failure.
docTypeStringISO document type, e.g. org.iso.18013.5.1.mDL.
nameSpaces[VerifiedNamespace]Credential attributes organised by namespace.
authenticationAuthenticationDetailsSecurity, MSO validity, and trust details for the document.
authentication.authenticationStatusVerificationAuthenticationStatusDerived pass/warn/fail verdict from the three checks above — prefer this over combining them yourself.
✦ Primary mDL namespace: org.iso.18013.5.1. Common fields: family_name, given_name, birth_date, document_number, portrait. Use attributes on VerifiedNamespace to access them.

JSON Export

Convert the full verification result to a JSON string for logging or transmission. Pdf417VerificationResult supports the same conversion.

⚠ toJsonString() renders every value as text, so binary elements such as the portrait do not survive it intact; read those from attributes directly.
Swift
extension VerificationResult {
    public func toJsonString() -> String?
}

extension Pdf417VerificationResult {
    public func toJsonString() -> String?
}

// Usage
if let json = verificationResult?.toJsonString() {
    print(json)
}
Security & Trust

Security & Trust Models

Each AuthenticationDetails has three structs. Review them before trusting the data.

Swift: Security & Trust structs
public struct SecurityDetails {
    public let isIssuerSignedValid: Bool
    public let isDeviceSignedValid: Bool
    public let areDigestsValid: Bool
}

public struct MsoValidityDetails {
    public let status: MsoStatus
    public let signedTimestamp: Int64?
    public let validFromTimestamp: Int64?
    public let validUntilTimestamp: Int64?
}

public struct TrustDetails {
    public let isIssuerTrusted: Bool
    public let chainStatus: TrustResult
    public let issuerDistinguishedName: String?
}
PropertyTypeDescription
isIssuerSignedValidBoolMobile Security Object (MSO) signature is valid.
isDeviceSignedValidBoolECDSA/MAC device signature passes verification.
areDigestsValidBoolData item hashes match the MSO digests.
msoValidity.statusMsoStatusvalid, notYetValid, expired, or unknown.
trust.isIssuerTrustedBoolIssuing CA found in the SDK trust store.
trust.chainStatusTrustResultverified, untrustedRoot, or unchecked.

Reference

Utility Methods

refreshConfiguration

Re-fetches the reader profile and device trust-management settings while the SDK is running — for example on a profile-update push, or when the app returns to the foreground. The refreshed profile applies to the next transaction; a verification already in flight is unaffected.

CoreTap2iDVerifySDK: refreshConfiguration()
func refreshConfiguration(
    completion: @escaping (ConfigurationRefreshResult) -> Void
)
⚠ The completion is not guaranteed to be called on the main thread.
Swift
public struct ConfigurationRefreshResult {
    public let profileName: String?
    public let error: Error?
    public var isRefreshed: Bool { get }   // true when error == nil
}

public enum ConfigurationRefreshError: Error {
    case sdkNotInitialized
}

getSdkVersion

Returns a version string for the linked SDK.

CoreTap2iDVerifySDK: getSdkVersion()
func getSdkVersion() -> String

getDeviceIdentifier

Returns the decrypted device identifier, used when provisioning a reader profile.

CoreTap2iDVerifySDK: getDeviceIdentifier()
func getDeviceIdentifier() -> String?

Reference

Enumerations

VerificationStatus

success
partialSuccess
failure
Swift
public enum VerificationStatus: String {
    case success
    case partialSuccess
    case failure
}

VerificationAuthenticationStatus

The derived pass/warn/fail verdict exposed by AuthenticationDetails.authenticationStatus — most integrations should branch on this rather than combining security, msoValidity and trust themselves.

success
warning
failure
Swift
public enum VerificationAuthenticationStatus {
    case success
    case warning
    case failure
}

MsoStatus

valid
notYetValid
expired
unknown
Swift
public enum MsoStatus: String {
    case valid
    case notYetValid
    case expired
    case unknown
}

TrustResult

verified
untrustedRoot
unchecked
Swift
public enum TrustResult: String {
    case verified
    case untrustedRoot
    case unchecked
}

Reference

Credential Verification Errors

Standard error codes encountered while verifying mDL and PDF417 (physical ID) credentials, grouped by verification phase: Device Engagement, Data Retrieval, and Validation.

Device Engagement

CodeErrorMessage
111Scanned QR code is invalidPlease scan a valid QR code
112NFC static handover errorTap and try again
113NFC negotiated handover errorTap and try again
114NFC not enabledTurn on the NFC and try again
115Connection timeoutUnable to verify mobile driving license. Please try again
116NFC tag errorNot an ID. Please try a valid ID
117Other general errorGeneral error occurred. Please try again
118Error code text not availableTransaction failed with unknown error
119Holder not configured to accept BluetoothOnly Bluetooth data retrieval option is available
120iOS version below 17 (fallback)The feature is unsupported as the iOS version is below 17.
121Mobile document request canceledThe mobile document request was canceled
122Request isn't validThe request is invalid. Please try again
123Response isn't validThe response from holder app is invalid
124Reader token for framework isn't validThe provided reader token for framework's is invalid
125System can't reach the networkThe system is unable to connect to the network.
126Device not allowed to perform requestThe device is not authorized to make the mobile document request.
127Mobile document reading not supported on the current deviceMobile document reading is not supported on the current device.
128Mobile document reader service unavailableThe mobile document reader service is currently unavailable.
129Reader session expiredThe current reader session has expired. Please refresh the page or start a new session.
130System is busyThe system is currently busy. Please try again later.
131Framework encountered a problem the system can't interpretIt looks like something went wrong with the system. The framework encountered a problem which the system can't interpret
132General NFC device engagement errorGeneral error occurred. Please try again
133Tag lost errorThe tag is lost. Please hold the phone a little bit longer.

Device Engagement: Tap to Present ID

Setup errors for Tap to Present ID data requests, delivered on onProximityReaderError. Apple framework errors in this flow use codes 120–131 above.

CodeErrorMessage
132Reader token unavailableThe reader token could not be obtained. Please check the network connection and the Tap to Present ID setup of the account.
133Profile has no requestable attributeThe verification profile has no driver's license attribute that Tap to Present ID can request.
134Profile requests attributes outside the entitlementThe verification profile requests attributes this app's entitlement does not allow: <attribute names>
135No data entitlementThis app does not have the Tap to Present ID data entitlement.
136Account not registered with AppleThis account is not registered with Apple for Tap to Present ID. Add the Brand ID and Key ID in Verify with Credence.
⚠ Codes 132 and 133 have two meanings. On onVerificationStageError (NFC engagement through verifyMdoc) they are the NFC errors in the first table. On onProximityReaderError (verifyMdocWithEntitlement) they are the Tap to Present ID errors above. Branch on the callback as well as combinedCode.

Data Retrieval

CodeErrorMessage
211Unable to initialize BLEPlease restart Bluetooth and try again
212BLE connection errorBluetooth connection failed. Please try again
213BLE L2CAP errorBluetooth connection failed. Please try again
214Connection timeoutConnection timeout. Please try again & keep your device nearby
215Invalid mDLInvalid mDL. Please scan a valid mDL
216Consent denied for all — the holder tapped Deny in the wallet appPlease provide consent to share driving license data
217Reserved—
218Data retrieval failed, unknown errorData retrieval failed with unknown error
219Consent denied for all attributes — the holder approved with every attribute uncheckedPlease provide consent for sharing mDL data
220Invalid CBORInvalid CBOR: There is some issue with decrypting databytes with CBOR

Validation

CodeErrorMessage
311Issuer data authentication (mDL data modified)mDL data authentication failed
312Issuer data authentication (mDL cloned to another device)mDL data authentication failed
313Issuing authority not trustedmDL issuing authority not trusted
314Issuing authority certificate expiredmDL issuing authority certificate expired
315General validation errorUnable to verify mobile driving license. Please try again
316Age over NN, failmDL: Age verification failed / Physical: Age not NN
318mDoc validity expiredDriving license is expired
319Visual verification passVisual verification passed
320Visual verification failVisual verification failed
321ID attribute missing or not sharedOne or more ID attributes are not shared
322Issuer certificate signature does not matchIssuer certificate signature does not match
323Issuer certificate is not validIssuer certificate is not valid
324MSO not valid (current date is outside the MSO's valid-from / valid-until range)MSO is not valid (i.e. Current date does not fall in range when the MSO was valid from <-> valid until)
325No match for issuer cert in local trust storeNo match found for issuer cert in local trust store
326Issuer certificate CA does not match trust storeIssuer certificate CA does not match with cert in local trust store
327Exception processing issuer certificateThere was an exception processing issuer certificate
328mDL issue date is not validmDL Issue Date is Not Valid
329Issuer certificate is expiredIssuer certificate is expired
330mDL expiredmDL Expired
331Requested data identifiers missing in responseRequested data identifiers are missing in response
332Values for requested data identifiers missingValues for requested data identifiers are missing in response
333Consent denied for all attributes, no attribute returnedPlease provide consent for sharing mDL data
⚠ PDF417 error codes not yet published. Pdf417VerificationResult.errors returns PDF417ValidationError values carrying a numeric code, but the code-to-message mapping for PDF417 has not been finalized by the SDK team. This table will be updated once that list is available.