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+
initSdk
Initializes the SDK with the given configuration. Call once at app startup before any mDL verification session.
func initSdk(
config: CoreSdkConfig,
initResult: @escaping (LicenseKeyVerificationResult) -> Void
)
Parameters
| Parameter | Type | Description |
|---|---|---|
| config | CoreSdkConfig | SDK configuration carrying the API key. required |
| initResult | (LicenseKeyVerificationResult) -> Void | Receives a LicenseKeyVerificationResult. required |
CoreSdkConfig
public struct CoreSdkConfig {
public var apiKey: String
public init(apiKey: String)
}
LicenseKeyVerificationResult
public struct LicenseKeyVerificationResult {
public let isValid: Bool
public let expiryDate: Int64? // epoch milliseconds
public let profileName: String?
public let error: Error?
}
Example
let config = CoreSdkConfig(apiKey: "" )
Tap2iDVerifySDK.shared.initSdk(config: config) { result in
if result.isValid {
// ready
} else {
print(result.error?.localizedDescription ?? "license invalid")
}
}
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.
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
| Parameter | Type | Description |
|---|---|---|
| engagementConfig | EngagementConfig | Engagement method: .nfc, .qrCode, or .nfcExternalReader. required |
| delegate | Tap2iDVerifySDKDelegate? | Verification lifecycle delegate for stage and result callbacks. optional |
| readerDelegate | NfcExternalReaderDelegate? | External NFC reader delegate. Only required when using .nfcExternalReader. optional |
EngagementConfig
public enum EngagementConfig {
case nfc // NFC engagement
case qrCode(String) // QR code engagement
case nfcExternalReader // external NFC reader over cable
}
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.
func stopMonitoring()
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.
func verifyPdf417(
request: Pdf417VerificationRequest
) async throws -> Pdf417VerificationResult
Throws Pdf417ImplError
Parameters
| Parameter | Type | Description |
|---|---|---|
| request | Pdf417VerificationRequest | Wraps the raw AAMVA PDF417 string. required |
PDF417 Models
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
Example
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)
}
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.
aamva.pdf417 document request. Without it the SDK throws Pdf417ImplError.noProfileDefined.
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.
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
| Parameter | Type | Description |
|---|---|---|
| request | ProximityReaderRequest | .display(document:elements:) or .data. required |
| delegate | ProximityReaderDelegate | Receives stage callbacks, errors and the outcome or result. required |
Example
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.
func isProximityReaderSupported() -> Bool
Tap to Present ID Models
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.
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
}
Tap2iDVerifySDKDelegate
Conform to this delegate to receive lifecycle callbacks during verification.
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.
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.
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.
VerificationStage
Each stage of the mDL verification pipeline. Reported via onVerificationStageStarted, onVerificationStageCompleted, and onVerificationStageError.
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
}
PDF417 is never emitted from 2.0.1 — verifyPdf417 returns its result directly rather than reporting stages.
Verification Result Model
The VerificationResult returned by onVerificationCompleted contains the credential documents and the overall verification status.
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 }
}
| Property | Type | Description |
|---|---|---|
| documents | [VerifiedDocument] | Array of verified documents from the mDL response. |
| status | VerificationStatus | Overall result: success, partialSuccess, or failure. |
| docType | String | ISO document type, e.g. org.iso.18013.5.1.mDL. |
| nameSpaces | [VerifiedNamespace] | Credential attributes organised by namespace. |
| authentication | AuthenticationDetails | Security, MSO validity, and trust details for the document. |
| authentication.authenticationStatus | VerificationAuthenticationStatus | Derived pass/warn/fail verdict from the three checks above — prefer this over combining them yourself. |
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.
extension VerificationResult {
public func toJsonString() -> String?
}
extension Pdf417VerificationResult {
public func toJsonString() -> String?
}
// Usage
if let json = verificationResult?.toJsonString() {
print(json)
}
Security & Trust Models
Each AuthenticationDetails has three structs. Review them before trusting the data.
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?
}
| Property | Type | Description |
|---|---|---|
| isIssuerSignedValid | Bool | Mobile Security Object (MSO) signature is valid. |
| isDeviceSignedValid | Bool | ECDSA/MAC device signature passes verification. |
| areDigestsValid | Bool | Data item hashes match the MSO digests. |
| msoValidity.status | MsoStatus | valid, notYetValid, expired, or unknown. |
| trust.isIssuerTrusted | Bool | Issuing CA found in the SDK trust store. |
| trust.chainStatus | TrustResult | verified, untrustedRoot, or unchecked. |
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.
func refreshConfiguration(
completion: @escaping (ConfigurationRefreshResult) -> Void
)
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.
func getSdkVersion() -> String
getDeviceIdentifier
Returns the decrypted device identifier, used when provisioning a reader profile.
func getDeviceIdentifier() -> String?
Enumerations
VerificationStatus
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.
public enum VerificationAuthenticationStatus {
case success
case warning
case failure
}
MsoStatus
public enum MsoStatus: String {
case valid
case notYetValid
case expired
case unknown
}
TrustResult
public enum TrustResult: String {
case verified
case untrustedRoot
case unchecked
}
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
| Code | Error | Message |
|---|---|---|
| 111 | Scanned QR code is invalid | Please scan a valid QR code |
| 112 | NFC static handover error | Tap and try again |
| 113 | NFC negotiated handover error | Tap and try again |
| 114 | NFC not enabled | Turn on the NFC and try again |
| 115 | Connection timeout | Unable to verify mobile driving license. Please try again |
| 116 | NFC tag error | Not an ID. Please try a valid ID |
| 117 | Other general error | General error occurred. Please try again |
| 118 | Error code text not available | Transaction failed with unknown error |
| 119 | Holder not configured to accept Bluetooth | Only Bluetooth data retrieval option is available |
| 120 | iOS version below 17 (fallback) | The feature is unsupported as the iOS version is below 17. |
| 121 | Mobile document request canceled | The mobile document request was canceled |
| 122 | Request isn't valid | The request is invalid. Please try again |
| 123 | Response isn't valid | The response from holder app is invalid |
| 124 | Reader token for framework isn't valid | The provided reader token for framework's is invalid |
| 125 | System can't reach the network | The system is unable to connect to the network. |
| 126 | Device not allowed to perform request | The device is not authorized to make the mobile document request. |
| 127 | Mobile document reading not supported on the current device | Mobile document reading is not supported on the current device. |
| 128 | Mobile document reader service unavailable | The mobile document reader service is currently unavailable. |
| 129 | Reader session expired | The current reader session has expired. Please refresh the page or start a new session. |
| 130 | System is busy | The system is currently busy. Please try again later. |
| 131 | Framework encountered a problem the system can't interpret | It looks like something went wrong with the system. The framework encountered a problem which the system can't interpret |
| 132 | General NFC device engagement error | General error occurred. Please try again |
| 133 | Tag lost error | The 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.
| Code | Error | Message |
|---|---|---|
| 132 | Reader token unavailable | The reader token could not be obtained. Please check the network connection and the Tap to Present ID setup of the account. |
| 133 | Profile has no requestable attribute | The verification profile has no driver's license attribute that Tap to Present ID can request. |
| 134 | Profile requests attributes outside the entitlement | The verification profile requests attributes this app's entitlement does not allow: <attribute names> |
| 135 | No data entitlement | This app does not have the Tap to Present ID data entitlement. |
| 136 | Account not registered with Apple | This account is not registered with Apple for Tap to Present ID. Add the Brand ID and Key ID in Verify with Credence. |
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
| Code | Error | Message |
|---|---|---|
| 211 | Unable to initialize BLE | Please restart Bluetooth and try again |
| 212 | BLE connection error | Bluetooth connection failed. Please try again |
| 213 | BLE L2CAP error | Bluetooth connection failed. Please try again |
| 214 | Connection timeout | Connection timeout. Please try again & keep your device nearby |
| 215 | Invalid mDL | Invalid mDL. Please scan a valid mDL |
| 216 | Consent denied for all — the holder tapped Deny in the wallet app | Please provide consent to share driving license data |
| 217 | Reserved | — |
| 218 | Data retrieval failed, unknown error | Data retrieval failed with unknown error |
| 219 | Consent denied for all attributes — the holder approved with every attribute unchecked | Please provide consent for sharing mDL data |
| 220 | Invalid CBOR | Invalid CBOR: There is some issue with decrypting databytes with CBOR |
Validation
| Code | Error | Message |
|---|---|---|
| 311 | Issuer data authentication (mDL data modified) | mDL data authentication failed |
| 312 | Issuer data authentication (mDL cloned to another device) | mDL data authentication failed |
| 313 | Issuing authority not trusted | mDL issuing authority not trusted |
| 314 | Issuing authority certificate expired | mDL issuing authority certificate expired |
| 315 | General validation error | Unable to verify mobile driving license. Please try again |
| 316 | Age over NN, fail | mDL: Age verification failed / Physical: Age not NN |
| 318 | mDoc validity expired | Driving license is expired |
| 319 | Visual verification pass | Visual verification passed |
| 320 | Visual verification fail | Visual verification failed |
| 321 | ID attribute missing or not shared | One or more ID attributes are not shared |
| 322 | Issuer certificate signature does not match | Issuer certificate signature does not match |
| 323 | Issuer certificate is not valid | Issuer certificate is not valid |
| 324 | MSO 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) |
| 325 | No match for issuer cert in local trust store | No match found for issuer cert in local trust store |
| 326 | Issuer certificate CA does not match trust store | Issuer certificate CA does not match with cert in local trust store |
| 327 | Exception processing issuer certificate | There was an exception processing issuer certificate |
| 328 | mDL issue date is not valid | mDL Issue Date is Not Valid |
| 329 | Issuer certificate is expired | Issuer certificate is expired |
| 330 | mDL expired | mDL Expired |
| 331 | Requested data identifiers missing in response | Requested data identifiers are missing in response |
| 332 | Values for requested data identifiers missing | Values for requested data identifiers are missing in response |
| 333 | Consent denied for all attributes, no attribute returned | Please provide consent for sharing mDL data |
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.