Tap2iD SDK for iOS - API Reference

API reference for the Tap2iD iOS SDK. Covers SDK initialization and mDL verification over BLE, NFC, QR, and PDF417.

Overview

Use Tap2iDVerifySDK.shared: the singleton that conforms to the CoreTap2iDVerifySDK protocol. Initialize it once at startup, then call verifyMdoc for each verification session.

Language: Swift 5.9+
Platform: iOS 16+ / iPadOS 16+
Transport: BLE, NFC, QR, PDF417.
Standard: ISO/IEC 18013-5:2021

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

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 (String?, String?, String?) -> Void
)

Parameters

Parameter	Type	Description
config	CoreSdkConfig	Core SDK configuration containing the license key. required
initResult	(String?, String?, String?) -> Void	Callback returning status, message, and optional additional information. required

CoreSdkConfig

Swift

public struct CoreSdkConfig {
    public var apiKey: String
}

verifyMdoc

Starts verification of a mobile driver's license (mDL). Supports NFC, QR code, PDF417, and external NFC reader engagement. Returns an Error?; nil means the session started.

CoreTap2iDVerifySDK: verifyMdoc()

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

Parameters

Parameter	Type	Description
engagementConfig	EngagementConfig	Engagement method: `.nfc`, `.qrCode`, `.pdf417`, 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

Swift: EngagementConfig enum

public enum EngagementConfig {
    case nfc
    case qrCode(String)
    case pdf417(String)
    case nfcExternalReader
}

stopMonitoring

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

Swift

func stopMonitoring()

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
}

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

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]
}

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

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.

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

Swift

extension VerificationResult {
    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?
}

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

Reference

Enumerations

VerificationStatus

success

partialSuccess

failure

Swift

public enum VerificationStatus {
    case success
    case partialSuccess
    case failure
}

MsoStatus

valid

notYetValid

expired

unknown

Swift

public enum MsoStatus {
    case valid
    case notYetValid
    case expired
    case unknown
}

TrustResult

verified

untrustedRoot

unchecked

Swift

public enum TrustResult {
    case verified
    case untrustedRoot
    case unchecked
}