In-person verification Verifier Mobile SDKs cheatsheet

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 linked tutorials and reference documentation tailored for each platform.

Core usage

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 Verifier Mobile SDKs cheatsheet

Core usage

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