Remote mobile verification quickstart guide

1. Log into the MATTR Portal.
2. Navigate to Credential Verification > Applications.
3. Select Create new.
4. Enter a meaningful name for your application.
5. Select the application type (e.g., iOS or Android).
6. Enter your Team ID (iOS) or Package Name (Android).
7. Enter your application Bundle ID (iOS) or SHA-256 fingerprint (Android).
8. In the OID4VP Configuration section, enter your Redirect URI (e.g., {your_app_bundleId}://my/path).
9. Select Create.
10. Make note of the generated application ID. You will need this value to initialize the SDK in your mobile application.

1. Log in to the MATTR Portal.
2. In the navigation panel on the left-hand side, expand the Credential Verification menu.
3. Select Applications.
4. Select Create new.
5. Enter a meaningful Name for your application (e.g. "My Android Mobile Verifier Application").
6. Use the Type dropdown to select Android as you are building an Android application.
7. In the Package Name field, enter your Android application package name. This is the unique identifier of your Android application, which must match the package name you set later in this tutorial.
8. In the Signing certificate thumbprints field, enter a temporary placeholder value (e.g. 3A9F6C1D4E8B72F0A5C3D6E19B4F8A2C7D1E0B9F3A6C5D4E7B8F2A1C9D0E3F5B). MATTR VII uses this to verify requests come from your signed app. You will update the placeholder value after you retrieve the signing certificate in Step 1: Environment setup.
9. In the OID4VP configuration section, enter a redirect URI in the Redirect URI field. This is the URI used to return the user to your app after the wallet presents the credential. It must resolve to a path your app can handle (via custom URI scheme or web page). In this tutorial you'll use a custom scheme based on your package name: {your_app_packageName}://oid4vp-callback.
10. Select Create.
11. Make note of the generated application ID. You will need this value to initialize the SDK in your mobile application.

Since React Native targets both iOS and Android, you must create a verifier application configuration for each platform:

iOS verifier application

1. Log into the MATTR Portal.
2. Navigate to Credential Verification > Applications.
3. Select Create new.
4. Enter a meaningful name for your application (e.g. "My React Native Verifier - iOS").
5. Use the Type dropdown to select iOS.
6. Enter your Team ID and Bundle ID for the iOS target of your React Native project.
7. In the OID4VP Configuration section, enter your Redirect URI (e.g., {your_app_bundleId}://oid4vp-callback).
8. Select Create.
9. Make note of the generated application ID.

Android verifier application

1. Select Create new again.
2. Enter a meaningful name for your application (e.g. "My React Native Verifier - Android").
3. Use the Type dropdown to select Android.
4. Enter your Package Name for the Android target of your React Native project.
5. In the Signing certificate thumbprints field, enter the SHA-256 fingerprint of your Android signing certificate.
6. In the OID4VP Configuration section, enter your Redirect URI (e.g., {your_app_packageName}://oid4vp-callback).
7. Select Create.
8. Make note of the generated application ID.

You will use the platform-specific application ID when calling requestMobileCredentials depending on which platform your app is running on.

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

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

• tenantHost : URL of your MATTR VII tenant.

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

MobileCredentialVerifier.initialize(context, platformConfiguration)

• tenantHost : URL of your MATTR VII tenant.

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

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

const 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 : 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],
    challenge: UUID().uuidString,
    applicationId: "your-application-id"
)

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

This method starts a presentation session with the MATTR VII tenant and redirects the user to a matching wallet application.

val onlinePresentationResult = mobileCredentialVerifier.requestMobileCredentials(
    activity = activity,
    request = listOf(mobileCredentialRequest),
    applicationId = "your-application-id"
)

• activity : Defines the current activity context.
• request : List of MobileCredentialRequest objects defining what information to request.
• applicationId : The id returned when you created the verifier application configuration.

This method starts a presentation session with the MATTR VII tenant and redirects the user to a matching wallet application.

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

const result = await requestMobileCredentials({
    request: [mobileCredentialRequest],
    applicationId: "your-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. Use the iOS or Android application ID depending on the platform your app is running on.
• challenge : A unique string to identify this presentation session and prevent replay attacks. Generate a new challenge for every request.

This method starts a presentation session with the MATTR VII tenant and redirects the user to a matching wallet application. Behavior differs between platforms:

• iOS: Initiates an online presentation flow. Requires a deep link handler to be registered (see Handle the redirect from the wallet).
• Android: Starts a remote app-to-app verification flow using either an OID4VP Redirect or Digital Credentials API (DC API) session, depending on the device capabilities and verifier application configuration.

To handle redirects back to your application after credential presentation, register a custom URL scheme.

1. Open your project in Xcode and select your application target.
2. Select the Info tab.
3. Expand the URL Types section.
4. Select the plus button.
5. Enter your bundle identifier in both the Identifier and URL Schemes fields.

This must match the redirectUri configured in your verifier application configuration.

To handle redirects back to your application after credential presentation, configure an intent filter in your AndroidManifest.xml:

<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="your-package-name"
        android:host="oid4vp-callback" />
</intent-filter>

This must match the redirectUri configured in your verifier application configuration.

Since React Native targets both iOS and Android, you must configure URL scheme handling for each platform.

iOS

1. Open the ios/ directory of your React Native project in Xcode and select your application target.
2. Select the Info tab.
3. Expand the URL Types section.
4. Select the plus button.
5. Enter your bundle identifier in both the Identifier and URL Schemes fields.

This must match the redirectUri configured in your iOS verifier application configuration.

Android

Add an intent filter to your AndroidManifest.xml (located at android/app/src/main/AndroidManifest.xml) to declare the SDK callback activity for handling OID4VP redirects:

<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="your-package-name"
            android:host="oid4vp-callback" />
    </intent-filter>
</activity>

The scheme and host values must match the redirectUri configured in your Android verifier application configuration.

.onOpenURL { url in
    mobileCredentialVerifier.handleDeepLink(url)
}

Add this modifier to your SwiftUI view to handle the redirect from the wallet application. The SDK processes the response and updates your application with the verification results.

The SDK processes the response with the verification results.

How you handle the redirect depends on the platform:

• iOS: You must call handleDeepLink to pass the redirect URL back to the SDK. Register a URL event listener in your app (e.g. using React Native's Linking API):

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

Linking.addEventListener("url", async (event) => {
    await handleDeepLink({ url: event.url });
});

• Android: The SDK handles the redirect automatically via the Openid4VpCallbackActivity declared in your AndroidManifest.xml. No additional code is required.

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:

public struct OnlinePresentationSessionResult {
    public let mobileCredentialResponse: MobileCredentialResponse?
    public let error: OnlinePresentationResultError?
    public let challenge: String?
    public let sessionId: String
}

guard let receivedCredentials = onlinePresentationSessionResult.mobileCredentialResponse?.credentials else {
    let errorMessage = onlinePresentationSessionResult.error?.message ?? "No error message"
    print("No response received: \(errorMessage)")
    return
}

// Process the received credentials
for credential in receivedCredentials {
    print("DocType: \(credential.docType)")
    print("Verified: \(credential.verificationResult.verified)")
    
    if let claims = credential.claims {
        for (namespace, elements) in claims {
            for (elementId, value) in elements {
                print("\(namespace).\(elementId): \(value)")
            }
        }
    }
}

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

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:

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

val receivedCredentials = onlinePresentationResult.mobileCredentialResponse?.credentials
if (receivedCredentials == null) {
    val errorMessage = onlinePresentationResult.error?.message ?: "No error message"
    println("No response received: $errorMessage")
    return
}

// 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}")
        }
    }
}

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

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

type OnlinePresentationSessionResult = {
    sessionId: string;
    challenge?: string;
    mobileCredentialResponse?: MobileCredentialResponse;
    error?: OnlinePresentationResultError;
};

if (result.isErr()) {
    console.error("Request failed:", result.error);
    return;
}

const sessionResult = result.value;
const credentials = sessionResult.mobileCredentialResponse?.credentials;

if (!credentials) {
    const errorMessage = sessionResult.error?.message ?? "No error message";
    console.error(`No response received: ${errorMessage}`);
    return;
}

// Process the received credentials
for (const credential of credentials) {
    console.log(`DocType: ${credential.docType}`);
    console.log(`Verified: ${credential.verificationResult.verified}`);

    if (credential.claims) {
        for (const [namespace, elements] of Object.entries(credential.claims)) {
            for (const [elementId, value] of Object.entries(elements)) {
                console.log(`${namespace}.${elementId}: ${JSON.stringify(value)}`);
            }
        }
    }
}

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