Handling verification results

When a holder responds to an in-person (proximity) verification request, the mDocs Verifier SDK returns structured data containing the verification outcome. This guide explains the response structure and how to interpret it.

What gets verified

Before working through the response structure, it is worth being clear about what is actually being verified. The credential itself, the full mDoc as issued and stored in the holder's wallet, never leaves the wallet and is never shared with a verifier. What the holder shares is a credential presentation: a subset of the credential's data, accompanied by the issuer's signature over the released items and a device authentication that proves the holder's device authorized this specific presentation.

This model is grounded in ISO/IEC 18013-5, which defines the mDL/mDoc data model and the proximity presentation flow used here. The standard treats what the holder shares as a presentation derived from the credential rather than the credential itself, and the presentation carries the same cryptographic proof and integrity guarantees as the credential it is drawn from.

When you verify a response, you are verifying the credential presentation. The cryptographic trust checks (issuer signature, issuer trust, validity, revocation, device key binding) apply to that presented slice, not to the credential as a whole on the holder's device. The MATTR VII verificationResult.verified flag reflects whether this presented credential passed those checks.

The rest of this guide uses "credential" as shorthand for the presented credential when the context makes clear we are talking about what was returned in the response.

How results are delivered

In a proximity presentation flow, the holder's device communicates directly with your verifier application. After the holder responds to the presentation request, the SDK returns a MobileCredentialResponse object.

Your application receives the result inline and is responsible for parsing and acting on it according to your business logic.

Understanding the response

A MobileCredentialResponse contains two optional fields:

• credentials: An array of MobileCredentialPresentation objects representing credentials that were successfully returned by the holder.
• credentialErrors: An array of CredentialError objects representing credentials that couldn't be returned.

When a holder responds to a verification request, several outcomes are possible, often in combination. Each one is described along two independent axes: whether the requested credential itself verified, and whether the requested claims within it were provided.

1. Requested credential not presented: The holder doesn't have the requested credential, so there is nothing to verify. The credential appears under credentialErrors with an error code of notReturned, and no verificationResult is produced.
2. Presented credential not verified: A credential was provided but the credential-level trust checks failed. The credentials array contains the credential with verified: false and a reason.type explaining why. Even if claims were returned, they should not be relied on while the credential itself did not verify.
3. Presented credential verified, all claims provided: The credential-level checks pass (verified: true with no reason) and every requested claim is returned (no claimErrors). Both layers are clean.
4. Presented credential verified, some claims missing: The credential-level checks pass (verified: true), but one or more requested claims were not returned and appear under claimErrors. The credential is trustworthy; the data payload is incomplete. How to handle the missing data is up to the relying party, depending on its use case. Options include failing the flow, falling back to collecting the required data through another channel, or proceeding if the missing claim is not essential.

Detailed result structure

Credential-level information

Each MobileCredentialPresentation in the credentials array contains:

• docType: The credential type (e.g., org.iso.18013.5.1.mDL for a mobile driver's license).
• claims: Verified claims organized by namespace.
• claimErrors: Errors for individual claims that couldn't be verified or were not returned.
• validityInfo: Credential validity period timestamps (signed, validFrom, validUntil, expectedUpdate).
• verificationResult: Verification status containing:
  • verified: Boolean indicating if verification succeeded. This is a high-level result; individual claim errors may still exist.
  • reason (optional): Object explaining verification failures when verified is false. Contains a type value from the following:
    • DeviceKeyInvalid: Device key is not valid. This can occur if the credential was not properly bound to the device or if the device's secure element is compromised.
    • InvalidSignerCertificate: Invalid signer certificate. This can occur if the credential's signing certificate is not valid or has been tampered with.
    • IssuerNotTrusted: Credential was issued by a certificate that is not trusted by the verifier. This can occur if the issuer's certificate is not included in the verifier's trusted issuer list.
    • MobileCredentialExpired: Credential expired. This can occur if the current date is after the credential's validUntil date.
    • MobileCredentialInvalid: Credential is not valid. This can occur for various reasons such as failing signature verification, containing invalid data, or not conforming to expected formats.
    • MobileCredentialNotYetValid: Credential not yet valid. This can occur if the current date is before the credential's validFrom date.
    • StatusRevoked: Credential has been revoked. This can occur if the issuer has revoked the credential after it was issued, which is typically checked through a revocation mechanism provided by the issuer.
    • StatusUnknown: Credential status could not be determined. This can occur if the verifier is unable to check the revocation status of the credential due to network issues or if the issuer does not provide a revocation mechanism.
    • TrustedIssuerCertificateExpired: Trusted issuer certificate expired. This can occur if the certificate of the trusted issuer has passed its expiration date, which may affect the trustworthiness of credentials issued by that issuer.
    • TrustedIssuerCertificateNotYetValid: Trusted issuer certificate not yet valid. This can occur if the certificate of the trusted issuer is not yet valid (i.e., the current date is before the certificate's validFrom date), which may affect the trustworthiness of credentials issued by that issuer.
    • UnsupportedCurve: Credential object contains an unsupported curve. This can occur if the credential uses cryptographic curves that are not supported by the verifier's cryptographic library, which may prevent successful verification of the credential's signatures.
• issuerInfo (optional): Issuer details including commonName and trustedIssuerId.
• branding (optional): Visual information for displaying the credential (name, description, colors, logos). You can use this to create a rich user interface when showing credential details in your application.

Claim-level information

Claims are organized by namespace within the claims object. For example, for an mDL, claims appear under the org.iso.18013.5.1 namespace:

"claims": {
	"org.iso.18013.5.1": {
		"family_name": { "value": "Smith" },
		"given_name": { "value": "Jane" },
		"birth_date": { "value": "1990-05-15" },
		"address": { "value": "123 Main Street, Springfield" }
	}
}

If specific claims couldn't be verified or weren't provided, they appear in the claimErrors object with the same namespace structure and an error code of notReturned:

"claimErrors": {
	"org.iso.18013.5.1": {
		"portrait": "notReturned"
	}
}

Credential errors

When a requested credential wasn't provided by the holder, it appears in the credentialErrors array with a docType and an errorCode of notReturned:

"credentialErrors": [
	{
		"docType": "org.iso.18013.5.1.mDL",
		"errorCode": "notReturned"
	}
]

Understanding the verified flag

With the structure in mind, it is worth being explicit about what verificationResult.verified does and does not tell you, because it is the single most important field for deciding whether to trust a presentation.

verified is the pass/fail flag for the presented credential. It applies to the slice of credential data the holder released in this session, together with its associated issuer signature and device authentication, not to the credential as a whole as stored on the holder's device. When verified: true, what the holder presented has passed MATTR VII's cryptographic and trust checks: the issuer signature on the released items is intact, the credential was issued by a trusted issuer, it is not expired or revoked, and the device key binding holds. In plain terms, the presented mDoc is genuine, has not been tampered with, and is currently valid.

What verified: true does not mean is that every claim you requested came back. verified is a high-level result on the credential as a whole, and individual claim errors may still exist. A credential can return verified: true while a specific requested claim (for example, portrait) is missing and surfaces under claimErrors with an error code of notReturned. The credential is trustworthy; the data payload may still be incomplete.

The mirror image is verified: false. When the credential layer fails, MATTR VII surfaces a reason.type explaining why (for example, expired, revoked, untrusted issuer, invalid signer certificate, or broken device key binding). The reason field is typed as optional, so defensive code should handle the case where it is absent. See the credential-level information section above for the full list of reason.type values.

Two layers of checks

A relying party's business logic needs to check two distinct things:

1. Is the credential real and valid? Look at verificationResult.verified on each credential in the credentials array. This is the objective trust check, and it should not be overridden by business logic.
2. Did we get all the data we asked for? Look at claimErrors on each credential, and at credentialErrors on the top-level result. Whether a missing claim or credential is acceptable is a business-logic decision specific to your use case.

In other words, verified is the objective measure of what can or cannot be accepted at all. Everything else, including claimErrors, credentialErrors, and the specific claim values returned, feeds your business logic about whether to accept the presentation for your particular use case.

Treating verified: true as a green light to proceed without inspecting claimErrors is a common integration mistake. The credential may be cryptographically valid while still missing a field your use case requires. For example, an age-restricted purchase flow needs birth_date, but if only family_name came back the relying party cannot make an age decision even though the credential itself returned verified: true. Conversely, bypassing a verified: false result with business logic (for example, accepting an expired or revoked credential because the claims look correct) defeats the trust model and should not be done.

Complete examples

Requested credential not presented

Neither layer of the check produces a result here. The holder did not provide a matching mDL, so the credential layer has nothing to verify (no verificationResult is returned) and the claims layer is not applicable. The missing credential is reported under credentialErrors, and the relying party's business logic must decide how to handle it.

{
	"credentialErrors": [
		{
			"docType": "org.iso.18013.5.1.mDL",
			"errorCode": "notReturned"
		}
	]
}

Presented credential not verified

The credential layer fails. The holder provided an mDL but the credential-level trust checks failed (in this example, because the credential has expired): verified: false, with reason.type identifying why. Even if claims were returned, they should not be relied on while the credential itself did not verify. The credential should not be accepted regardless of business logic.

{
	"credentials": [
		{
			"docType": "org.iso.18013.5.1.mDL",
			"verificationResult": {
				"verified": false,
				"reason": {
					"type": "MobileCredentialExpired",
					"message": "Credential has expired"
				}
			},
			"validityInfo": {
				"signed": "2024-01-15T10:00:00Z",
				"validFrom": "2024-01-15T10:00:00Z",
				"validUntil": "2025-01-15T10:00:00Z",
				"expectedUpdate": "2026-01-15T10:00:00Z"
			}
		}
	]
}

Presented credential verified, all claims provided

Both layers pass. The credential layer returns verified: true with no reason, confirming the mDL is genuine, current, and from a trusted issuer. The claims layer returns every requested claim with no claimErrors, so the relying party has the complete data payload it asked for.

{
	"credentials": [
		{
			"docType": "org.iso.18013.5.1.mDL",
			"claims": {
				"org.iso.18013.5.1": {
					"family_name": { "value": "Smith" },
					"given_name": { "value": "Jane" },
					"birth_date": { "value": "1990-05-15" },
					"address": { "value": "123 Main Street, Springfield" }
				}
			},
			"validityInfo": {
				"signed": "2024-01-15T10:00:00Z",
				"validFrom": "2024-01-15T10:00:00Z",
				"validUntil": "2027-01-15T10:00:00Z",
				"expectedUpdate": "2028-01-15T10:00:00Z"
			},
			"verificationResult": {
				"verified": true
			},
			"issuerInfo": {
				"commonName": "State Department of Motor Vehicles",
				"trustedIssuerId": "d4a6e9f2-3b1c-4d8e-a5f7-9c2b0e8d1a3f"
			},
			"branding": {
				"name": "Driver License",
				"description": "State-issued driver license",
				"backgroundColor": "#1E3A8A",
				"issuerLogo": {
					"format": "svg",
					"data": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjwvc3ZnPg=="
				}
			}
		}
	]
}

Presented credential verified, some claims missing

The credential layer passes but the claims layer is incomplete. The mDL itself returns verified: true and is trustworthy, while one requested claim (portrait) was not released and appears under claimErrors as notReturned. What is missing here is data, not trust, and the relying party's business logic must decide whether the missing claim is acceptable for its use case.

{
	"credentials": [
		{
			"docType": "org.iso.18013.5.1.mDL",
			"claims": {
				"org.iso.18013.5.1": {
					"family_name": { "value": "Smith" },
					"given_name": { "value": "Jane" },
					"birth_date": { "value": "1990-05-15" }
				}
			},
			"claimErrors": {
				"org.iso.18013.5.1": {
					"portrait": "notReturned"
				}
			},
			"validityInfo": {
				"signed": "2024-01-15T10:00:00Z",
				"validFrom": "2024-01-15T10:00:00Z",
				"validUntil": "2027-01-15T10:00:00Z",
				"expectedUpdate": "2028-01-15T10:00:00Z"
			},
			"verificationResult": {
				"verified": true
			},
			"issuerInfo": {
				"commonName": "State Department of Motor Vehicles",
				"trustedIssuerId": "d4a6e9f2-3b1c-4d8e-a5f7-9c2b0e8d1a3f"
			}
		}
	]
}

Recommended handling flow

When processing a MobileCredentialResponse, follow these steps:

1. Check for credential errors: Inspect credentialErrors to determine if any requested credentials were not returned by the holder. Handle these based on whether the credential is required for your use case.
2. Iterate through credentials: For each MobileCredentialPresentation in the credentials array:
   • Check verificationResult.verified. If false, inspect verificationResult.reason to understand why.
   • If verified is true, proceed to extract claim values from the claims object.
   • Check claimErrors for any claims that were requested but not returned. Decide whether to proceed based on which claims are missing.
3. Apply business logic: Use the verified claims, issuer information, and branding data to make authorization decisions and present results in your application.

Next steps

• Review the mDocs Verifier SDK API reference for iOS or Android for complete type definitions
• See the in-person verification quickstart for building a proximity verifier
• Learn how to configure revocation status checks for in-person verification flows