Remote mobile verification quickstart guide

Make a request of the following structure to create an iOS Verifier Application configuration on your MATTR VII tenant (make sure to replace bundleId, teamId and redirectUri with your own values):

POST /v2/presentations/applications

{
    "name": "My iOS Mobile Verifier Application",
    "type": "ios",
    "bundleId": "com.yourname.mobileverifier",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "appAttest": {
        "required": false,
        "environment": "development"
    },
    "openid4vpConfiguration": {
        "redirectUri": "com.yourname.mobileverifier://my/path"
    }
}

• bundleId: This must match the bundle identifier of your iOS application you will create in the next step.
• teamId: This must match the Apple Developer Team ID that actually signs this app.
• redirectUri: The URI the user is redirected to after presenting the credential from their wallet. Structure it as {your_app_bundleId}://my/path.

A successful response returns a 201 status code with the created Verifier Application:

{
    "id": "1ef1f867-20b4-48ea-aec1-bea7aff4964c", 
    "name": "My iOS Mobile Verifier Application",
    "type": "ios",
    // ... rest of application configuration
}

• id: A unique identifier for the Verifier Application (generated by the tenant). You must use this value when initializing the SDK so that it can correctly identify and authenticate your application.

Make a request of the following structure to create an Android Verifier Application configuration on your MATTR VII tenant:

POST /v2/presentations/applications

{
    "name": "My Android Mobile Verifier Application",
    "type": "android",
    "packageName": "com.yourname.mobileverifier",
    "packageSigningCertificateThumbprints": [
        "1232584B6F6A892D356899FB9576C5F226A179E6199F2B7A1D837B5C234C5A8E"
    ],
    "keyAttestation": {
        "required": false
    },
    "openid4vpConfiguration": {
        "redirectUri": "com.yourname.mobileverifier://oid4vp-callback"
    }
}

A successful response returns a 201 status code with the created Verifier Application:

{
    "id": "a82bfa46-72a0-4cde-b6cb-2a0de7e2f3c4", 
    "name": "My Android Mobile Verifier Application",
    "type": "android",
    // ... rest of application configuration
}

• id: A unique identifier for the Verifier Application (generated by the tenant). You must use this value when initializing the SDK so that it can correctly identify and authenticate your application.

A React Native app runs on both iOS and Android, and the MATTR VII tenant validates requests differently for each platform. Create a Verifier Application for each platform you intend to run on by following the iOS and Android tabs above. Each platform's redirectUri must match that platform's URL scheme, so configure one Verifier Application per platform and use the matching application id at runtime.

let platformConfiguration = PlatformConfiguration(
    tenantHost: URL(string: "https://your-tenant.vii.mattr.global")!,
    applicationId: "your-application-id"
)

initialize is asynchronous from v6.0.0 (call it from an asynchronous context). It registers the app instance with your tenant and obtains a license, so it can throw failedToRegister and invalidLicense:

mobileCredentialVerifier = MobileCredentialVerifier.shared
try await mobileCredentialVerifier.initialize(platformConfiguration: platformConfiguration)

• tenantHost : URL of your MATTR VII tenant.
• applicationId : The id returned when you created the verifier application configuration. Supplied here via PlatformConfiguration (no longer passed to requestMobileCredentials) and used for SDK Tethering.

val platformConfiguration = PlatformConfiguration(
    tenantHost = URL("https://your-tenant.vii.mattr.global"),
    applicationId = "your-application-id"
)

initialize registers the app instance with your tenant and obtains a license, so it can throw FailedToRegisterException and InvalidLicenseException:

MobileCredentialVerifier.initialize(context, platformConfiguration)

• tenantHost : URL of your MATTR VII tenant.
• applicationId : The id returned when you created the verifier application configuration. Supplied here via PlatformConfiguration (no longer passed to requestMobileCredentials) and used for SDK Tethering.

import { initialize } from "@mattrglobal/mobile-credential-verifier-react-native";

const result = await initialize({
    platformConfiguration: {
        tenantHost: "https://your-tenant.vii.mattr.global",
    },
});

if (result.isErr()) {
    console.error("Failed to initialize SDK:", result.error);
}

• tenantHost : Base URL of your MATTR VII tenant.

let mobileCredentialRequest = MobileCredentialRequest(
    docType: "org.iso.18013.5.1.mDL",
    namespaces: [
        "org.iso.18013.5.1": [
            "family_name": false,
            "given_name": false,
            "birth_date": false
        ]
    ]
)

• docType : The type of credential being requested (e.g. org.iso.18013.5.1.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).

val mobileCredentialRequest = MobileCredentialRequest(
    docType = "org.iso.18013.5.1.mDL", namespaces = NameSpaces(
        mapOf(
            "org.iso.18013.5.1" to DataElements(
                mapOf(
                    "family_name" to false, "given_name" to false, "birth_date" to false
                )
            )
        )
    )
)

• docType : The type of credential being requested (e.g. org.iso.18013.5.1.mDL).
• namespaces : A map of 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).

const mobileCredentialRequest = {
  docType: "org.iso.18013.5.1.mDL",
  namespaces: {
    "org.iso.18013.5.1": {
      family_name: false,
      given_name: false,
      birth_date: false,
    },
  },
};

• docType : The type of credential being requested (e.g. org.iso.18013.5.1.mDL).
• namespaces : An object 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).

let onlinePresentationResult = try await mobileCredentialVerifier.requestMobileCredentials(
    request: [mobileCredentialRequest]
)

• request : Array of MobileCredentialRequest objects defining what information to request.

From v6.0.0, the applicationId is no longer passed here — it comes from the PlatformConfiguration you set when initializing the SDK. The challenge parameter is now optional: omit it to let the SDK generate a secure challenge, or pass your own unique value per session to mitigate replay attacks.

val onlinePresentationResult = MobileCredentialVerifier.requestMobileCredentials(
    activity = activity,
    request = listOf(mobileCredentialRequest)
)

• activity : Defines the current activity context.
• request : List of MobileCredentialRequest objects defining what information to request.

From v7.0.0, the applicationId is no longer passed here — it comes from the PlatformConfiguration you set when initializing the SDK.

const result = await requestMobileCredentials({
  request: [mobileCredentialRequest],
  applicationId: Constants.APPLICATION_ID,
  challenge: Crypto.randomUUID(),
});

• request : Array of MobileCredentialRequest objects defining what information to request.
• applicationId : The id returned when you created the verifier application configuration.
• challenge : A unique, unpredictable value to identify this presentation session and prevent replay attacks. Generate a new challenge for every request.

.onOpenURL { url in
    // Navigate to response screen
    viewModel.navigationPath.append(NavigationState.viewResponse)
    viewModel.mobileCredentialVerifier.handleDeepLink(url)
}

Add this modifier to your SwiftUI view to navigate to the response screen and pass the redirect URL to the SDK's handleDeepLink method. The SDK processes the response and updates the receivedDocuments variable with the verification results.

The SDK handles the redirect via the Openid4VpCallbackActivity declared in your AndroidManifest.xml. Register the callback activity with an intent filter that matches the redirect URI of your verifier application:

<activity
    android:name="global.mattr.mobilecredential.verifier.a2apresentation.callback.Openid4VpCallbackActivity"
    android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
        android:scheme="com.yourname.mobileverifier"
        android:host="oid4vp-callback" />
  </intent-filter>
</activity>

• android:scheme : Must match the redirect custom scheme you defined when you created the verifier application.
• android:host : Must match the redirect host you defined when you created the verifier application.

Handling the redirect differs by platform:

• iOS: Forward the wallet's redirect URL to the SDK with handleDeepLink so it can complete the pending requestMobileCredentials call:

  useEffect(() => {
    if (Platform.OS !== "ios") {
      return;
    }
    const subscription = Linking.addEventListener("url", ({ url }) => {
      handleDeepLink({ url });
    });
    return () => subscription.remove();
  }, []);

• Android: The withOpenid4VpCallbackActivity config plugin declares the SDK's Openid4VpCallbackActivity in AndroidManifest.xml, bound to {your_packageName}://oid4vp-callback. The SDK handles the redirect automatically, so requestMobileCredentials resolves directly and no additional code is required.

From v6.0.0, OnlinePresentationSessionResult is a @frozen enum with success and failure cases, so you branch over it with switch/case instead of inspecting nullable fields:

switch onlinePresentationResult {
case .success(_, _, let mobileCredentialResponse):
    receivedDocuments = mobileCredentialResponse?.credentials ?? []
case .failure(_, _, let error):
    print("No response received: \(error.message)")
    return
}

• success : Carries sessionId, challenge, and an optional mobileCredentialResponse containing the verified credentials and their claims.
• failure : Carries sessionId, challenge, and an error (type and message) describing what went wrong.
• credentials : A list of presented credentials with their data, status, and verification results.

The sample app assigns the result to the receivedDocuments variable, which a DocumentView then renders. A DocumentViewModel converts each MobileCredentialPresentation (docType, verification result, claims, and claim errors) into a human-readable format for display.

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

From v7.0.0, OnlinePresentationSessionResult is a sealed interface with Success and Failure variants:

sealed interface OnlinePresentationSessionResult {
    val sessionId: String
    val challenge: String?

    data class Success(
        override val sessionId: String,
        override val challenge: String? = null,
        val mobileCredentialResponse: MobileCredentialResponse?
    ) : OnlinePresentationSessionResult

    data class Failure(
        override val sessionId: String,
        override val challenge: String? = null,
        val error: OnlinePresentationResultError
    ) : OnlinePresentationSessionResult
}

Branch over the result with when/is instead of inspecting nullable fields:

when (onlinePresentationResult) {
    is OnlinePresentationSessionResult.Failure -> {
        println("No response received: ${onlinePresentationResult.error.message}")
    }
    is OnlinePresentationSessionResult.Success -> {
        val receivedCredentials = onlinePresentationResult.mobileCredentialResponse?.credentials.orEmpty()

        // Process the received credentials
        for (credential in receivedCredentials) {
            println("DocType: ${credential.docType}")
            println("Verified: ${credential.verificationResult.verified}")

            credential.claims?.forEach { (namespace, elements) ->
                elements.forEach { (elementId, value) ->
                    println("$namespace.$elementId: ${value.value}")
                }
            }
        }
    }
}

• Success.mobileCredentialResponse : Contains the verified credentials and their claims.
• Failure.error : The error that occurred during the verification process.
• credentials : A list of presented credentials with their data, status, and verification results.

The sample app assigns the result to the _receivedDocuments state flow, which a DocumentView composable then renders. The composable reads the docType and verification result and flattens document.claims into a list of label and value pairs for display.

const session = result.value;
if (!session.isSuccess) {
  console.error(`Verification session failed: ${session.error.message}`);
  return;
}

const response = session.mobileCredentialResponse;
setVerificationResults(response ?? null);

• result.value : The OnlinePresentationSessionResult. Check session.isSuccess to distinguish a successful session from a failed one (session.error).
• mobileCredentialResponse : Contains the verified credentials and their claims.
• credentials : A list of presented credentials with their data, status, and verification results.

The sample app stores the response and renders it in a VerificationResultsModal, which reads each MobileCredentialPresentation (docType, verification result, claims, and claim errors) and displays it in a human-readable format.