@mattrglobal/verifier-sdk-web 2.1.2-unstable.98 → 2.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 # Table of Contents
 
+- [verifier-sdk-web](#verifier-sdk-web)
+- [Table of Contents](#table-of-contents)
 - [General](#general)
   - [Licensing](#licensing)
   - [Overview](#overview)
@@ -18,6 +20,7 @@
   - [Determine supported presentation flows](#determine-supported-presentation-flows)
   - [Define wallet identifiers](#define-wallet-identifiers)
   - [Configure redirectUri](#configure-redirecturi)
+  - [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state)
   - [Request credentials using the DC API](#request-credentials-using-the-dc-api)
 - [Request credentials examples](#request-credentials-examples)
   - [Request credentials with automatic flow selection](#request-credentials-with-automatic-flow-selection)
@@ -35,15 +38,21 @@ Request or download the
 
 ## Overview
 
-The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/mdocs), supporting both [same-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#same-device-verification-workflow) and [cross-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#cross-device-verification-workflow) verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.
+The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web
+applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/mdocs), supporting
+both [same-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#same-device-verification-workflow)
+and
+[cross-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#cross-device-verification-workflow)
+verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification
+processes.
 
 ## Features
 
-* Simple integration into web applications.
-* Supports both same-device and cross-device presentation flows.
-* Secure handling of mDocs requests and responses.
-* Compliant with [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html).
-* Offers [DC API](https://wicg.github.io/digital-credentials/) support as a **tech-preview**.
+- Simple integration into web applications.
+- Supports both same-device and cross-device presentation flows.
+- Secure handling of mDocs requests and responses.
+- Compliant with [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html).
+- Offers [DC API](https://wicg.github.io/digital-credentials/) support as a **tech-preview**.
 
 > In this SDK mDocs are referred to as Mobile Credentials.
 
@@ -51,8 +60,8 @@ The Verifier Web SDK is a powerful tool for integrating online credential verifi
 
 ## How to get access to the MATTR Pi Verifier Web SDK
 
-Refer to our [SDK Docs landing page](https://learn.mattr.global/guides/get-started-pi) for step-by-step instructions to gain access
-to any of our SDKs.
+Refer to our [SDK Docs landing page](https://learn.mattr.global/guides/get-started-pi) for step-by-step instructions to
+gain access to any of our SDKs.
 
 > Please [reach out](mailto:dev-support@mattr.global) if you need any assistance.
 
@@ -82,25 +91,30 @@ MATTRVerifierSDK.initialize(...);
 <script src="https://cdn.mattr.global/js/verifier-sdk-web/{VERSION}/verifier-js.production.js"></script>
 ```
 
-> This script will automatically pick up any SDK patch updates. You can lock your implementation to a specific patch version by replacing 1.0 with the specific version (e.g. https://cdn.mattr.global/js/verifier-sdk-web/1.0.1/verifier-js.production.js).
+> This script will automatically pick up any SDK patch updates. You can lock your implementation to a specific patch
+> version by replacing 1.0 with the specific version (e.g.
+> https://cdn.mattr.global/js/verifier-sdk-web/1.0.1/verifier-js.production.js).
 
 2. Access SDK functions via global `MATTRVerifierSDK` object.
 
 ```javascript
-<script> 
-   MATTRVerifierSDK.initialize(...);
-</script> 
+<script>MATTRVerifierSDK.initialize(...);</script>
 ```
 
 # Usage
 
-The SDK can make a request to create a presentation session with a configured MATTR VII verifier tenant. This requires the following configurations and settings:
-* Initialize the SDK with the URL of the MATTR VII tenant that will handle the verification request.
-* Prepare a credential query that defines what claims are required for verification.
-* Generate a unique challenge for the presentation session.
-* Determine what presentation flows are supported in the session.
-* Define what wallets can be used to respond to the verification request.
-* Configure the URI the user will be redirected to when the verification workflow is completed (only required for same-device flows).
+The SDK can make a request to create a presentation session with a configured MATTR VII verifier tenant. This requires
+the following configurations and settings:
+
+- Initialize the SDK with the URL of the MATTR VII tenant that will handle the verification request.
+- Prepare a credential query that defines what claims are required for verification.
+- Generate a unique challenge for the presentation session.
+- Determine what presentation flows are supported in the session.
+- Define what wallets can be used to respond to the verification request.
+- Configure the URI the user will be redirected to when the verification workflow is completed (only required for
+  same-device flows).
+- Optionally pass a `state` string to correlate the session with a record in your own system (see
+  [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state)).
 
 ## Initialize the SDK
 
@@ -111,96 +125,231 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 ```
 
 - `apiBaseUrl` (required): URL of the MATTR VII verifier tenant.
-- `applicationId` (required): Unique identifier of the verifier application. This must match the [`id`](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!c=201&path=0/id&t=response) parameter in the response returned when [creating a Verifier application](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication) on the MATTR VII verifier tenant.
+- `applicationId` (required): Unique identifier of the verifier application. This must match the
+  [`id`](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!c=201&path=0/id&t=response)
+  parameter in the response returned when
+  [creating a Verifier application](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication)
+  on the MATTR VII verifier tenant.
 
 ## Prepare a credential query
 
-The following example credential query will request the `given_name`, `family_name`, `birth_date` and `portrait` claims from a `mobile` credential profile with `org.iso.18013.5.1.mDL` as a docType: 
+The following example credential query will request the `given_name`, `family_name`, `birth_date` and `portrait` claims
+from a `mobile` credential profile with `org.iso.18013.5.1.mDL` as a docType:
 
 ```javascript
 const credentialQuery = [
   {
-    "profile": "mobile",
-    "docType": "org.iso.18013.5.1.mDL",
-    "nameSpaces": {
+    profile: "mobile",
+    docType: "org.iso.18013.5.1.mDL",
+    nameSpaces: {
       "org.iso.18013.5.1": {
-        "given_name": {
-          "intentToRetain": false
+        given_name: {
+          intentToRetain: false,
+        },
+        family_name: {
+          intentToRetain: false,
         },
-        "family_name": {
-          "intentToRetain": false
+        birth_date: {
+          intentToRetain: false,
         },
-        "birth_date": {
-          "intentToRetain": false
+        portrait: {
+          intentToRetain: false,
         },
-        "portrait": {
-          "intentToRetain": false
+        resident_postal_code: {
+          intentToRetain: false,
         },
-        "resident_postal_code": {
-          "intentToRetain": false
-        }
       },
-    }
-  }
+    },
+  },
 ];
 ```
-* `profile`: Credential format of the credential that will be verified. Currently only mobile (mDocs) is supported.
-* `docType`: the mDL’s type. Confirm with the certificate issuer for what docType they are issuing. Some common examples include:
-  * Mobile Driver License (`org.iso.18013.5.1.mDL`).
-  * PhotoID (`org.iso.23220.photoid.1`).
-  * Mobile Vehicle Registration Card (`org.iso.7367.1.mVRC`).
-  * Health certificate (`org.micov.vtr.1`).
-* `nameSpaces`: Each namespace corresponds to a group of claims included in the credential. These can be claims that are part of a specific standard, jurisdiction or any other reference. The namespace would usually correspond to the requested `docType`.
-  * `intentToRetain` (Optional): When set to `true`, the holder will be indicated that the verifier intends to retain this claim beyond the verification workflow. Defaults to `false` when not specified.
-  
-> The API supports including multiple query objects in the `credentialQuery` array in a single request. For simplicity, this example only includes a single query object.
 
-In this example the `credentialQuery` query will request for the `birthdate`, `portrait` and `resident_postal_code` claims from any credentials whose `profile` is `mobile` and `docType` is `org.iso.18013.5.1.mDL`.
+- `profile`: Credential format of the credential that will be verified. Currently only mobile (mDocs) is supported.
+- `docType`: the mDL’s type. Confirm with the certificate issuer for what docType they are issuing. Some common examples
+  include:
+  - Mobile Driver License (`org.iso.18013.5.1.mDL`).
+  - PhotoID (`org.iso.23220.photoid.1`).
+  - Mobile Vehicle Registration Card (`org.iso.7367.1.mVRC`).
+  - Health certificate (`org.micov.vtr.1`).
+- `nameSpaces`: Each namespace corresponds to a group of claims included in the credential. These can be claims that are
+  part of a specific standard, jurisdiction or any other reference. The namespace would usually correspond to the
+  requested `docType`.
+  - `intentToRetain` (Optional): When set to `true`, the holder will be indicated that the verifier intends to retain
+    this claim beyond the verification workflow. Defaults to `false` when not specified.
+
+> The API supports including multiple query objects in the `credentialQuery` array in a single request. For simplicity,
+> this example only includes a single query object.
 
-It also sets `intentToRetain` as `false` for all claims, indicating to the holder that the verifier will not retain any of these claims.
+In this example the `credentialQuery` query will request for the `birthdate`, `portrait` and `resident_postal_code`
+claims from any credentials whose `profile` is `mobile` and `docType` is `org.iso.18013.5.1.mDL`.
 
-> While `intentToRetain` defaults to false, it is explicitly set to `false` in the example above for clarity purposes. If there is no intention to retain a claim, it is sufficient to simply exclude `intentToRetain` from the query.
+It also sets `intentToRetain` as `false` for all claims, indicating to the holder that the verifier will not retain any
+of these claims.
+
+> While `intentToRetain` defaults to false, it is explicitly set to `false` in the example above for clarity purposes.
+> If there is no intention to retain a claim, it is sufficient to simply exclude `intentToRetain` from the query.
 
 ## Generate challenge
 
-The Verifier Web SDK passes a unique challenge to the MATTR VII verifier tenant with every request to create a new presentation session. The purpose of the challenge is to ensure the security and integrity of the credential verification process by preventing replay attacks and verifying the authenticity of each request and response. You can either:
-  * Generate this challenge by your backend and pass it to the SDK.
-  * Generate it using the SDK built-in method.
+The Verifier Web SDK passes a unique challenge to the MATTR VII verifier tenant with every request to create a new
+presentation session. The purpose of the challenge is to ensure the security and integrity of the credential
+verification process by preventing replay attacks and verifying the authenticity of each request and response. You can
+either:
+
+- Generate this challenge by your backend and pass it to the SDK.
+- Generate it using the SDK built-in method.
 
-When the challenge is generated by your backend, you should use it to validate the verification results received from the MATTR VII verifier tenant.
+When the challenge is generated by your backend, you should use it to validate the verification results received from
+the MATTR VII verifier tenant.
 
 ## Determine supported presentation flows
 
-The **same-device flow** involves the user completing all steps on a single device, such as their smartphone. They initiate the credential request on the verifier's web app, are redirected to their wallet app to consent and present credentials, and then return to the verifier's web app with the results.
+The **same-device flow** involves the user completing all steps on a single device, such as their smartphone. They
+initiate the credential request on the verifier's web app, are redirected to their wallet app to consent and present
+credentials, and then return to the verifier's web app with the results.
 
-In contrast, the **cross-device flow** starts on one device, like a laptop. When the user initiates the request, the web app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to present matching credentials, and the results are sent back to the verifier's web app. 
+In contrast, the **cross-device flow** starts on one device, like a laptop. When the user initiates the request, the web
+app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to
+present matching credentials, and the results are sent back to the verifier's web app.
 
-The main difference is that the same-device flow uses only one device for the entire process, while the cross-device flow uses two devices for added flexibility.
+The main difference is that the same-device flow uses only one device for the entire process, while the cross-device
+flow uses two devices for added flexibility.
 
 By default, the Verifier Web SDK automatically selects a flow based on the browser's user agent:
-* Same-device flows are used when the agent is a mobile device.
-* Cross-device flows are used in all other cases.
 
-This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the [examples](#usage-examples) below.
+- Same-device flows are used when the agent is a mobile device.
+- Cross-device flows are used in all other cases.
+
+This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the
+[examples](#request-credentials-examples) below.
 
 ## Define wallet identifiers
 
-You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier defined by the SDK in the credential request must match one of the identifiers of a [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request) created on the MATTR VII verifier tenant.
-* If an identifier is provided and matches the `id` of one of the objects in the `walletProviders` array, the verifier tenant will invoke that specific wallet using its corresponding [`authorizationEndpoint`](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=openid4vpConfiguration/authorizationEndpoint&t=request).
-* If an identifier is provided and does not match the `id` of any of the objects in the `walletProviders array`, the request will fail.
-* If an identifier is not provided, the verifier tenant will use `mdoc-openid4vp://` (default OID4VP scheme) to invoke any wallet.
+You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier
+defined by the SDK in the credential request must match one of the identifiers of a
+[wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
+created on the MATTR VII verifier tenant.
+
+- If an identifier is provided and matches the `id` of one of the objects in the `walletProviders` array, the verifier
+  tenant will invoke that specific wallet using its corresponding
+  [`authorizationEndpoint`](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=openid4vpConfiguration/authorizationEndpoint&t=request).
+- If an identifier is provided and does not match the `id` of any of the objects in the `walletProviders array`, the
+  request will fail.
+- If an identifier is not provided, the verifier tenant will use `mdoc-openid4vp://` (default OID4VP scheme) to invoke
+  any wallet.
 
 ## Configure redirectUri
 
-When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of the values defined in the [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request) when creating a verifier application.
+When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete
+the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of
+the values defined in the
+[`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+when creating a verifier application.
+
+## Correlate sessions with your own records using `state`
+
+When you create a presentation session, MATTR VII generates its own `sessionId` (a UUID) to track the session through
+its lifecycle. That identifier is meaningful within MATTR VII, but it does not map to anything in your own system. If
+you need to attach a verification to an existing record on your side, such as an onboarding application, a checkout
+intent, or an account opening flow, pass an optional `state` string to `requestCredentials()`.
+
+`state` is an opaque correlation reference that you generate and control. MATTR VII carries it through the verification
+session and returns it to you with the result, so no additional state management is required in your application or
+backend. The value:
+
+- Travels through the entire session, including the wallet interaction.
+- Is returned in both same-device and cross-device flows.
+- Is available on both successful and failed results.
+
+If you only need to verify a credential and act on the result immediately in the same browser session, `state` is not
+required; the MATTR VII `sessionId` is enough on its own. Use `state` when correlation needs to survive the round-trip
+to the wallet and back.
+
+> The `state` value is transmitted in plain text as a query parameter on the wallet-facing authorization request URI and
+> is stored in session records. It should not contain personally identifiable information (PII), credentials, or
+> anything sensitive. Use an opaque reference, such as an internal record ID or a randomly generated token your system
+> can map back to the underlying record.
+
+> `state` is a correlation reference, not a security mechanism. It does not replace the `challenge` used to detect
+> session replay. Continue to generate a unique `challenge` per session and validate it against the result you receive.
+
+### Setting `state`
+
+Pass `state` alongside the other options when calling `requestCredentials()`:
+
+```typescript
+const options: MATTRVerifierSDK.RequestCredentialsOptions = {
+  credentialQuery: [credentialQuery],
+  challenge: MATTRVerifierSDK.utils.generateChallenge(),
+  state: "onboarding-app-7f3a4e8c", // Your own opaque correlation reference
+  openid4vpConfiguration: {
+    redirectUri: window.location.origin,
+    walletProviderId,
+  },
+};
+
+const results = await MATTRVerifierSDK.requestCredentials(options);
+```
+
+The SDK requires `state` to be a non-empty string. The MATTR VII platform additionally enforces a maximum length of 256
+characters and rejects an empty or over-length value with an HTTP 400 validation error. If your internal identifier is
+longer, store it on your side and pass a shorter reference that maps back to it.
+
+When `state` is not supplied, the OpenID4VP `state` claim falls back to the MATTR VII `sessionId`, no `state` field
+appears in the result, and existing integrations see no change in behavior.
+
+For the complete end-to-end flow across both the MATTR VII platform and the SDK, see the
+[Correlating verification sessions with your system](https://learn.mattr.global/docs/verification/remote-web-verifiers/guides/correlating-verification-sessions)
+guide on MATTR Learn.
+
+### Reading `state` back
+
+`state` is echoed back wherever a session result is exposed. In cross-device flows it is returned on the
+`RequestCredentialsResponse` resolved by `requestCredentials()`:
+
+```typescript
+const results = await MATTRVerifierSDK.requestCredentials(options);
+
+if (results.isOk()) {
+  const { state, result } = results.value; // state === "onboarding-app-7f3a4e8c"
+  // Use state to look up the matching record in your system.
+}
+```
+
+In same-device flows it is returned on the `HandleRedirectCallbackResponse` resolved by `handleRedirectCallback()` on
+your redirect page:
+
+```typescript
+const results = await MATTRVerifierSDK.handleRedirectCallback();
+
+if (results.isOk()) {
+  const { sessionId, state, result } = results.value; // state === "onboarding-app-7f3a4e8c"
+}
+```
+
+> For same-device flows, the SDK persists `state` to `localStorage` before redirecting to the wallet and removes it
+> after `handleRedirectCallback()` completes. This is an implementation detail that guards against frameworks stripping
+> query parameters from redirect URIs; you do not need to read or write this storage entry yourself.
+
+When your verifier application delivers results through the back channel (`resultAvailableInFrontChannel: false`), the
+same `state` field is included in the response from the retrieve presentation session result endpoint, on both success
+and failure shapes.
+
+For the full end-to-end pattern, including a worked onboarding example and the back-channel result flow across both the
+MATTR VII platform and the SDK, see the
+[Correlating verification sessions with your system](https://learn.mattr.global/docs/verification/remote-web-verifiers/guides/correlating-verification-sessions)
+guide on MATTR Learn.
 
 ## Request credentials using the DC API
 
-> DC API support is currently offered as a **tech preview**. As such, functionality may be limited, may not work in all scenarios, and could change or break without prior notice.
+> DC API support is currently offered as a **tech preview**. As such, functionality may be limited, may not work in all
+> scenarios, and could change or break without prior notice.
 
-1. Add the `dcApiConfiguration` object to your MATTR VII [verifier application configuration](https://learn.mattr.global/docs/verification/remote-verification-api-reference/verifier-applications#update-a-verifier-application).
+1. Add the `dcApiConfiguration` object to your MATTR VII
+   [verifier application configuration](https://learn.mattr.global/docs/verification/remote-verification-api-reference/verifier-applications#update-a-verifier-application).
 
-2. Use the SDK's `isDigitalCredentialsApiSupported` method to determine if the user's browser supports the Digital Credentials API:
+2. Use the SDK's `isDigitalCredentialsApiSupported` method to determine if the user's browser supports the Digital
+   Credentials API:
 
 ```typescript
 import * as MattrVerifierSDK from "@mattrglobal/verifier-sdk-web";
@@ -242,10 +391,11 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId }); // Initialize the SD
 const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery, // Define what credential query to use
   challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
+  state: "YOUR-REFERENCE-ID", // Optional: attach your own correlation reference
   openid4vpConfiguration: {
-      walletProviderId, // Define the wallet identifier
-      redirectUri, // Define the redirect URI (not required for cross-device only requests)
-  }
+    walletProviderId, // Define the wallet identifier
+    redirectUri, // Define the redirect URI (not required for cross-device only requests)
+  },
 });
 
 if (result.isErr()) {
@@ -254,12 +404,26 @@ if (result.isErr()) {
   console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.value);
 }
 ```
-* `apiBaseUrl` : Replace with the [`tenant_url`](https://learn.mattr.global/docs/platform-management/authentication) of your MATTR VII verifier tenant.
-* `credentialQuery`: The credential query to be used in the request.
-* `challenge`: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge generated by your backend system.
-* `walletProviderId`: Replace with a wallet identifier that matches one of the identifiers of a [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request) created on the MATTR VII verifier tenant..
-* `mode`: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to `undefined` in the example for clarity).
-* `redirectUri` Replace with a URI that matches one of the values in the [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request) in the MATTR VII tenant's verifier application.
+
+- `apiBaseUrl` : Replace with the [`tenant_url`](https://learn.mattr.global/docs/platform-management/authentication) of
+  your MATTR VII verifier tenant.
+- `credentialQuery`: The credential query to be used in the request.
+- `challenge`: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation
+  session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge
+  generated by your backend system.
+- `walletProviderId`: Replace with a wallet identifier that matches one of the identifiers of a
+  [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
+  created on the MATTR VII verifier tenant..
+- `state` (optional): Your own opaque correlation reference for this presentation session. Do not include personally
+  identifiable information (PII), credentials, or anything sensitive, as the value is transmitted in plain text on the
+  wallet-facing request URI and stored in session records. Returned in the response from `requestCredentials()`
+  (cross-device) or `handleRedirectCallback()` (same-device). See
+  [Correlate sessions with your own records using state](#correlate-sessions-with-your-own-records-using-state).
+- `mode`: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to
+  `undefined` in the example for clarity).
+- `redirectUri` Replace with a URI that matches one of the values in the
+  [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+  in the MATTR VII tenant's verifier application.
 
 ## Request credentials with explicit same-device flow
 
@@ -268,23 +432,25 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery,
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
+  state: "YOUR-REFERENCE-ID", // Optional
   openid4vpConfiguration: {
-      redirectUri,
-      walletProviderId,
-      mode: "sameDevice",
-  }
+    redirectUri,
+    walletProviderId,
+    mode: "sameDevice",
+  },
 });
 
 // result can be retrieved on redirect uri page. for example
 window.addEventListener("load", async () => {
   MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
   const result = await MATTRVerifierSDK.handleRedirectCallback();
+  // result.value contains { sessionId, state, result? }
 });
 ```
 
-* `mode`: When set to `sameDevice`, the SDK will only support same-device flow in this verification workflow.
-* Note that in this case you must define a `redirectUri`.
-* This example shows how you can redirect the user to page that will retrieve and display the verification results.
+- `mode`: When set to `sameDevice`, the SDK will only support same-device flow in this verification workflow.
+- Note that in this case you must define a `redirectUri`.
+- This example shows how you can redirect the user to page that will retrieve and display the verification results.
 
 ## Request credentials with explicit cross-device flow
 
@@ -293,10 +459,11 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery,
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
+  state: "YOUR-REFERENCE-ID", // Optional
   openid4vpConfiguration: {
-      walletProviderId,
-      mode: "crossDevice",
-  }
+    walletProviderId,
+    mode: "crossDevice",
+  },
 });
 
 if (result.isErr()) {
@@ -306,8 +473,10 @@ if (result.isErr()) {
 }
 ```
 
-* `mode`: When set to `crossDevice`, the SDK will only support cross-device flow in this verification workflow.
-* Note that in this case you must define how to handle verification completion and failure.
+- `mode`: When set to `crossDevice`, the SDK will only support cross-device flow in this verification workflow.
+- Note that in this case you must define how to handle verification completion and failure.
 
 # Error Handling
-The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks provide detailed error information to help diagnose and remedy issues.
+
+The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks
+provide detailed error information to help diagnose and remedy issues.