iOS SDK · API Reference

Tap2iD SDK — iOS API Reference

Complete API reference for integrating the Tap2iD iOS SDK. Initialize, verify mDLs, handle delegates, and evaluate security checks via NFC, QR code, PDF417, or external NFC reader.

Explore API

>_ tap2id-ios-sdk ––docs

initSdk

Configure your API key via CoreSdkConfig and boot the SDK before performing any mDL verification.

verifyMdoc

Start verification via NFC, QR code, PDF417, or external NFC reader with a single method call.

Delegates

Track verification lifecycle and external NFC reader events through Tap2iDVerifySDKDelegate and NfcExternalReaderDelegate.

Result Models

Inspect VerificationResult — extracted attributes, namespaces, authentication details, and JSON export.

Security & Trust

Evaluate issuer trust, device and issuer signatures, digest validity, and MSO expiry status.

Enums

VerificationStage, EngagementConfig, VerificationStatus, MsoStatus, and TrustResult reference.

Overview

CoreTap2iDVerifySDK

The CoreTap2iDVerifySDK protocol defines the core functionalities of the Tap2iD Verify SDK. The singleton entry point is Tap2iDVerifySDK.shared.

ℹ Register on the Verify with Credence portal first to obtain your API key before integrating the SDK.

initSdk

Initializes the SDK with the provided 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 API 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 successfully.

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

Implement this delegate to receive granular lifecycle callbacks throughout the verification process.

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 defines delegate methods for handling 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

Represents each stage in 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 delivered via onVerificationCompleted contains all extracted 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 exposes three independent structs to evaluate before trusting the credential 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
}