In-person verification quickstart guide

This guide provides a quick overview of how to use the MATTR Pi mDocs Verifier SDKs to verify an mDoc presented in-person via a proximity presentation workflow as per ISO/IEC 18013-5:2021.

Use these guides as a quick reference to get started. For detailed information, explore the tutorial and reference documentation tailored for each platform.

Embed the Verifier SDK in your mobile application

Initialize the SDK

mobileCredentialVerifier.initialize()

Add a trusted issuer certificate

try await mobileCredentialVerifier.addTrustedIssuerCertificates(certificates: [certificate])

certificate : Pass the IACA certificate of an issuer your want your application to trust.

Initialize the SDK

MobileCredentialVerifier.initialize(activity)

Add a trusted issuer certificate

MobileCredentialVerifier.addTrustedIssuerCertificates(certificates = listOf(certificate))

certificate : Pass the IACA certificate of an issuer your want your application to trust.

Initialize the SDK

await mobileCredentialVerifier.initialise()

Add a trusted issuer certificate

await mobileCredentialVerifier.addTrustedIssuerCertificates([certificate])

Create a presentation request

    let mobileCredentialRequest = MobileCredentialRequest(
        docType: "<DocType>",
        namespaces: [
            "<Namespace>": [
                "<AttributeName1>": false,
                "<AttributeName2>": false,
                "<AttributeName3>": false
            ]
        ]
    )

docType : The type of credential being requested (e.g., an mDL).
namespaces : A dictionary mapping each namespace to its requested attributes. Each attribute is a key with a Boolean indicating whether the verifier intends to retain this attribute (true) or not (false).

Create a presentation request

val mobileCredentialRequest = MobileCredentialRequest(
    docType = "<DocType>",
    namespaces = NameSpaces(
        mapOf(
            "<Namespace>" to DataElements(
                mapOf(
                    "<AttributeName1>" to false,
                    "<AttributeName2>" to false,
                    "<AttributeName3>" to false
                )
            )
        )
    )
)

docType : The type of credential being requested (e.g., an mDL).
namespaces : A map of requested attributes under each namespace, where false indicates the verifier does not intent to retain this attribute.

Create a presentation request

const mobileCredentialRequest = {
    docType: '<DocType>',
    namespaces: {
        '<Namespace>': {
            '<AttributeName1>': false,
            '<AttributeName2>': false,
            '<AttributeName3>': false
        }
    }
}

docType : The type of credential being requested (e.g., an mDL).
namespaces : An object that defines the attributes being requested for each namespace. A value of false indicates the verifier does not intent to retain this attribute.

Create a proximity presentation session

Extend a class with the ProximityPresentationSessionListener protocol:

Conform to ProximityPresentationSessionListener

extension VerifierViewModel: ProximityPresentationSessionListener {
  public func onEstablished() {
    // Handle session establishment: show presentation session details or send a request.
  }
  public func onTerminated(error: (any Error)?) {
    /// Handle session termination
    print("Session Terminated")
  }
}

Call the createProximityPresentationSession function with an instance of the extended class:

Create a proximity presentation session

mobileCredentialVerifier.createProximityPresentationSession(encodedDeviceEngagementString: deviceEngagementString, listener: self)

encodedDeviceEngagementString : Pass the device engagement string retrieved from a QR code presented by the holder.
listener : An object that conforms to ProximityPresentationSessionListener protocol and will handle the session events.

Implement the ProximityPresentationSessionListener interface:

Implement ProximityPresentationSessionListener

val sessionListener = object : ProximityPresentationSessionListener {
    override fun onEstablished() {
        // Handle session establishment: show presentation session details or send a request.
    }

    override fun onTerminated(error: Throwable?) {
        Log.d("SessionListener", "Session Terminated")
    }
}

Call the createProximityPresentationSession function with an instance of the extended class:

Create a proximity presentation session

MobileCredentialVerifier.createProximityPresentationSession(activity, deviceEngagementString, sessionListener)

deviceEngagementString : Pass the device engagement string retrieved from a QR code presented by the holder.
sessionListener : An object that implements ProximityPresentationSessionListener interface and will handle the session events.

Create a proximity presentation session

const proximityPresentationSession =
    await mobileCredentialVerifier.createProximityPresentationSession({
        encodedDeviceEngagementString: encodedDeviceEngagementString,
        onSessionTerminated: (error) => {
            // Handle session termination or error
        }
    })

encodedDeviceEngagementString : Pass the device engagement string retrieved from a QR code presented by the holder.
onSessionTerminated : A callback triggered when the session ends or fails.

The createProximityPresentationSession method returns an empty success response, indicating that the session has been created and the verifier application can send a presentation request to the holder.

Listen to NFC session requests

This capability is currently only available in the Android SDK.

MobileCredentialVerifier.registerForNfcDeviceEngagement(activity, sessionListener)

sessionListener : An object that implements the ProximityPresentationSessionListener interface and will handle the session events.

MobileCredentialVerifier.deregisterForNfcDeviceEngagement(activity)

This capability is currently only available in the Android SDK.

Send a presentation request

try await mobileCredentialVerifier.sendProximityPresentationRequest(request: [mobileCredentialRequest])

request : Pass the MobileCredentialRequest object created in the previous step.
skipStatusCheck : A Boolean indicating whether to skip the revocation status check. Set to false to check credential revocation status as part of the verification.

Send a presentation request

MobileCredentialVerifier.sendProximityPresentationRequest(request = listOf(mobileCredentialRequest))

request : Pass the MobileCredentialRequest object created in the previous step.
skipStatusCheck : A Boolean indicating whether to skip the revocation status check. Set to false to check credential revocation status as part of the verification.

Send a presentation request

const mobileCredentialResponse =
    await proximityPresentationSession.sendProximityPresentationRequest({
        request: mobileCredentialRequest,
        skipStatusCheck: false
    })

request : Pass the MobileCredentialRequest object created two steps up.
skipStatusCheck : A Boolean indicating whether to skip the status check. Set to false to check credential revocation status as part of the verification.

Handle the presentation response

The requestMobileCredentials method returns a MobileCredentialResponse object. This response contains the presentation details provided by the holder, including any errors encountered and the verification status of the credentials returned in the response:

MobileCredentialResponse

let mobileCredentialResponse = MobileCredentialResponse(
    credentialErrors: [/* CredentialError */],
    credentials: [
        MobileCredentialPresentation(
            branding: /* Branding information for displaying the credential */,
            claimErrors: [
                /* Namespace */: [
                    /* ElementID */: /* MobileCredentialResponseErrorCode */
                ]
            ],
            claims: [
                /* Namespace */: [
                    /* ElementID */: /* MobileCredentialElementValue */
                ]
            ],
            docType: /* DocType */,
            issuerInfo: /* IssuerInfo */,
            validityInfo: /* Validity */,
            verificationResult: /* VerificationResult */
        )
    ]
)

credentialErrors : Any requested docTypes not returned by the holder.
credentials : A list of presented credentials with their data, status, and any attribute-specific errors.

The sendProximityPresentationRequest method returns a MobileCredentialResponse object. This response contains the presentation details provided by the holder, including any errors encountered and the verification status of the credentials returned in the response:

MobileCredentialResponse structure

data class MobileCredentialResponse(
    val credentials: List<MobileCredentialPresentation>?,
    val credentialErrors: List<CredentialError>?
)

MobileCredentialPresentation structure

data class MobileCredentialPresentation(
    val docType: DocType,
    val validityInfo: MobileCredentialValidity,
    val claimErrors: Map<NameSpace, Map<DataElementIdentifier, ErrorCode>>?,
    val claims: Map<NameSpace, Map<DataElementIdentifier, MobileCredentialElement>>?,
    val branding: Branding?,
    val issuerInfo: IssuerInfo?,
    val verificationResult: MobileCredentialVerificationResult
)

CredentialError structure

data class CredentialError(
    val docType: DocType,
    val errorCode: ErrorCode
)

typealias DocType = String
typealias ErrorCode = Int

credentialErrors : Any requested docTypes not returned by the holder.
credentials : A list of presented credentials with their data, status, and any attribute-specific errors.

The sendProximityPresentationRequest returns a MobileCredentialResponse object. This response contains the presentation details provided by the holder, including any errors encountered and the verification status of the credentials returned in the response:

MobileCredentialResponse

const mobileCredentialResponse = {
  credentialErrors: [/* CredentialError */],
  credentials: [
    {
      branding: /* Branding */,
      claimErrors: {
        /* Namespace */: {
          /* ElementID */: /* MobileCredentialResponseErrorCode */
        }
      },
      claims: {
        /* Namespace */: {
          /* ElementID */: /* MobileCredentialElementValue */
        }
      },
      docType: /* DocType */,
      issuerInfo: /* IssuerInfo */,
      validityInfo: /* Validity */,
      verificationResult: /* VerificationResult */
    }
  ]
};

credentialErrors : Any requested docTypes not returned by the holder.
credentials : A list of presented credentials with their data, status, and any attribute-specific errors.

In-person verification quickstart guide

Embed the Verifier SDK in your mobile application

Initialize the SDK

Create a presentation request

Create a proximity presentation session

Listen to NFC session requests

Send a presentation request

Handle the presentation response

On this page