Controlling wallet interactions with URI schemes

Overview

When implementing an online verification workflow using OID4VP, your MATTR VII verifier tenant generates verification request URIs that invoke wallet applications to present credentials. These request URIs can be presented to users as QR codes (for cross-device flows) or deep links (for same-device flows).

As a verifier, you can control which wallet applications can interact with your verification requests and influence the user experience through URI schemes. This involves both user experience considerations and business requirements where you may want to work with specific wallet providers.

Controlling which wallets can respond to verification requests

The mechanism for controlling which wallets can interact with your verification requests is through URI schemes and trusted wallet configurations. When you create a presentation session on your MATTR VII tenant, you can specify which wallet provider should handle the request, and MATTR VII will generate the verification request URI using that wallet's configured URI scheme.

Understanding URI schemes

A URI scheme is the protocol part at the beginning of a URI (such as https://, mailto:, or custom schemes like mdoc-openid4vp://). The URI scheme you choose affects:

• Which wallet apps can respond to the request: Some schemes allow any compatible wallet app, while others target specific wallet applications.
• User experience: How smoothly users can present credentials and whether they see app selection prompts.
• Business alignment: Your ability to work with specific wallet providers that align with your requirements.

Several URI scheme types can be used for verification requests:

1. ISO 18013-7 default scheme (mdoc-openid4vp://): Defined by ISO/IEC 18013-7:2025. A wallet that handles this scheme declares support for the static wallet metadata parameters defined in ISO 18013-7. Any wallet app registered to handle this scheme can respond to the verification request.
2. Private-use URI scheme (com.example.wallet://): A unique custom scheme using reverse-domain notation. This makes it less likely (but not impossible) for other wallet apps to handle the request. Unlike the default schemes above, a private-use scheme carries no implied protocol configuration — you must either know the wallet's supported capabilities out-of-band, or discover them dynamically via wallet metadata.
3. Claimed HTTPS scheme (https://wallet.example.com/...): Uses domain-verified App Links (Android) or Universal Links (iOS) to ensure only the verified wallet app can handle verification requests from that domain.

Choosing the right URI scheme

Select a URI scheme based on your requirements:

Implementing URI schemes

The following sections show you how to implement each URI scheme type as a verifier.

ISO 18013-7 default scheme (mdoc-openid4vp://)

The mdoc-openid4vp:// scheme is defined by ISO/IEC 18013-7:2025. By using this scheme, you signal to wallets that your verification request expects ISO 18013-7 protocol compliance — including support for ECDH-ES as authorization_encryption_alg_values_supported. Any wallet registered to handle this scheme can respond.

When to use:

• You are verifying ISO 18013-7 credentials (such as mobile driving licences).
• You want to support any wallet that claims ISO 18013-7 compliance.
• You're developing or testing an ISO 18013-7 verification flow.

How it works:

MATTR VII generates verification request URIs using this scheme when you configure a wallet provider with this authorization endpoint.

Implementation:

1. Create a supported wallet configuration using the MATTR Portal or API (optional - this is the default behavior):

POST /v2/presentations/wallet-providers

{
  "name": "MATTR GO Hold", 
  "openid4vpConfiguration": {
    "authorizationEndpoint": "mdoc-openid4vp://"
  }
}

{
  "id": "99890c34-e4b7-4a23-84d6-e5de57114c00",  
  "name": "MATTR GO Hold",
  "openid4vpConfiguration": {
    "authorizationEndpoint": "mdoc-openid4vp://"
  }
}

2. Start a presentation session using the Verifier Web SDK or API, optionally referencing the wallet provider ID:

const options: MATTRVerifierSDK.RequestCredentialsOptions = {
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  openid4vpConfiguration: {
    redirectUri: window.location.origin,
    walletProviderId: "99890c34-e4b7-4a23-84d6-e5de57114c00" // Optional
  },
};

const results = await MATTRVerifierSDK.requestCredentials(options);

3. The SDK will return a verification request URI and automatically render it as a QR code (cross-device flows) or deep link (same-device flows).

Trade-offs:

• ✅ Works with any ISO 18013-7 compliant wallet.
• ✅ Standards-compliant for ISO-based credential flows.
• ⚠️ Users may see multiple wallet options if they have several installed.
• ⚠️ Cannot target a specific wallet application.

Requirements for wallet applications:

For wallet apps to respond to these requests, they must be configured to handle the mdoc-openid4vp:// scheme and meet the full ISO 18013-7 protocol requirements. See the holder guide for implementation details.

Private-use URI scheme

A private-use URI scheme uses reverse-domain notation (e.g., com.example.wallet://) to target a specific wallet application. This allows you to direct verification requests to a particular wallet provider that uses a custom URI scheme.

When to use:

• You want to work with a specific wallet provider that uses a custom URI scheme.
• You're partnering with a wallet provider and want to direct users to their application.
• You need better targeting than the standard scheme but the wallet doesn't support domain-verified links.

How it works:

You configure the wallet provider's custom URI scheme as their authorization endpoint on your MATTR VII tenant. When you create a presentation session and reference that wallet provider, MATTR VII generates the verification request URI using the configured scheme.

Implementation:

1. Create a supported wallet configuration with the wallet provider's custom URI scheme. You can do this via the MATTR Portal or by making an API request:

POST /v2/presentations/wallet-providers

{
  "name": "Partner Wallet App", 
  "openid4vpConfiguration": {
    "authorizationEndpoint": "com.example.wallet://"
  }
}

{
  "id": "99890c34-e4b7-4a23-84d6-e5de57114c00",  
  "name": "Partner Wallet App",
  "openid4vpConfiguration": {
    "authorizationEndpoint": "com.example.wallet://"
  }
}

2. Start a presentation session and reference the wallet provider ID:

const options: MATTRVerifierSDK.RequestCredentialsOptions = {
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  openid4vpConfiguration: {
    redirectUri: window.location.origin,
    walletProviderId: "99890c34-e4b7-4a23-84d6-e5de57114c00"
  },
};

const results = await MATTRVerifierSDK.requestCredentials(options);

3. The SDK will return a verification request URI and automatically render it as a QR code (cross-device flows) or deep link (same-device flows).

Trade-offs:

• ✅ Better targeting of a specific wallet application.
• ✅ Enables partnerships with specific wallet providers.
• ✅ Simple configuration on the verifier side.
• ⚠️ Requires coordination with the wallet provider to know their custom scheme.
• ⚠️ Users must have the specific wallet app installed.
• ⚠️ Other apps could potentially register the same scheme.

Requirements for wallet applications:

The wallet app must:

• Register to handle their custom URI scheme (e.g., com.example.wallet://).
• Support the OID4VP specification for processing verification requests.
• Handle the verification request URI and present credentials accordingly.

Because private-use schemes carry no implied protocol configuration, you must either know the wallet's supported capabilities out-of-band, or discover them dynamically via wallet metadata.

See the holder guide for implementation details.

Claimed HTTPS scheme (App Links / Universal Links)

HTTPS schemes use domain-verified App Links (Android) or Universal Links (iOS) to direct verification requests to wallet applications that support these technologies. The wallet provider must configure their domain verification to enable this.

When to use:

• You want to work with wallet providers that support Universal/App Links.
• You're partnering with professional wallet providers that have domain-verified schemes.
• You want the smoothest user experience with no app selection prompts for users of those wallets.

How it works:

The wallet provider configures their domain with the necessary verification files and provides their HTTPS authorization endpoint. You configure this endpoint on your MATTR VII tenant. When you create a presentation session and reference that wallet provider, MATTR VII generates the verification request URI using the HTTPS scheme, which the operating system directs to the verified wallet app.

Implementation:

1. Obtain the wallet provider's HTTPS authorization endpoint. The wallet provider must have already set up domain verification files on their web server (see the holder guide for details on what wallet providers need to configure).

2. Create a supported wallet configuration with the wallet provider's HTTPS authorization endpoint. You can do this via the MATTR Portal or by making an API request:

POST /v2/presentations/wallet-providers

{
  "name": "Partner Wallet with Universal Links", 
  "openid4vpConfiguration": {
    "authorizationEndpoint": "https://wallet.example.com/verify"
  }
}

{
  "id": "99890c34-e4b7-4a23-84d6-e5de57114c00",  
  "name": "Partner Wallet with Universal Links",
  "openid4vpConfiguration": {
    "authorizationEndpoint": "https://wallet.example.com/verify"
  }
}

3. Start a presentation session and reference the wallet provider ID:

const options: MATTRVerifierSDK.RequestCredentialsOptions = {
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  openid4vpConfiguration: {
    redirectUri: window.location.origin,
    walletProviderId: "99890c34-e4b7-4a23-84d6-e5de57114c00"
  },
};

const results = await MATTRVerifierSDK.requestCredentials(options);

4. The SDK will return a verification request URI and automatically render it as a QR code (cross-device flows) or deep link (same-device flows).

Trade-offs:

• ✅ Smoothest user experience with no app selection prompts.
• ✅ Professional appearance with branded domain links.
• ✅ Works with reputable wallet providers that have domain verification.
• ✅ Operating system validates the domain association.
• ⚠️ Requires wallet providers to have set up domain verification.
• ⚠️ Users must have the specific wallet app installed.
• ⚠️ Requires coordination with wallet providers to obtain their authorization endpoint.

Requirements for wallet applications:

The wallet app must:

• Have configured Associated Domains (iOS) or intent filters with autoVerify="true" (Android).
• Host the necessary domain verification files on their web server.
• Handle HTTPS URLs from their domain.
• Support the OID4VP specification for processing verification requests.

See the holder guide for implementation details.

Security considerations

When working with URI schemes for verification, it's important to understand the role they play in the overall security of your verification workflow:

URI schemes and user experience:

URI schemes primarily serve as a user experience mechanism to:

• Make it easier to scan a QR code or follow a deep link and have the OS open the intended wallet app.
• Reduce confusion by limiting which apps are presented as options.
• For HTTPS schemes, leverage operating system domain verification to ensure a specific wallet app is the default handler.

Verification security:

The security of the verification workflow relies on the cryptographic verification of presented credentials, not on URI schemes. MATTR VII verifies:

• The credential's cryptographic signature using the trusted issuer's certificate.
• The credential's validity period and status.
• That the presented claims match what was requested.
• The device binding (for mDocs) to ensure the credential is being presented from the legitimate holder's device.

These cryptographic checks ensure that even if a different wallet application responds to the verification request, the credential itself must still be legitimate and cryptographically valid.

Choosing wallet providers:

While URI schemes don't enforce which wallet can respond at a protocol level, they enable you to:

• Direct users to specific wallet applications through targeted URI schemes.
• Build business relationships with specific wallet providers.
• Provide a better user experience by reducing ambiguity about which app to use.

For stronger guarantees about which wallets can interact with your verification system, consider additional mechanisms such as wallet attestation or business agreements with wallet providers.

For questions about advanced security configurations, please contact us.