Learn

Send a presentation request

After you create a presentation request, you need to send it to the holder so that they can accept it and send back a verifiable presentation. You can send the request in one of the following available methods:

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • Available DID that can be used for messaging (i.e. a DID with a keyType of ed25519).

  • If you intend to send the offer as a MATTR VII message, you will need the subject DID. This is a did:key that identifies the intended holder of the credential. This DID is usually retrieved from the intended holder's digital wallet. Refer to create a did:key if you need assistance in creating one for testing this feature. In production environments you must have a secure way to obtain it:

    • Use DID Auth for any new interactions.

    • Ask the user to share their wallet DID (MATTR Showcase wallet or MATTR GO users can do this by navigating to Settings > Advanced > Public DID).

    • Request an existing credential as part of a verification workflow, and extract the DID from that interaction.

Send as a QR code

Use the didcommUri value from the presentation request to generate a QR code using your preferred QR code service. Here is an example using the free QR Server API:

http
Copy to clipboard.
1https://api.qrserver.com/v1/create-qr-code?&size=400x400&data=didcomm://https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/requests/38d9ca70-8b61-48c3-9efc-b67d97410743/didcommuri

https://www.datocms-assets.com/38428/1693372000-screenshot-2023-08-30-at-5-00-46-pm.png?auto=format

1. Begin by base64 encoding the didcommUri value from the presentation request. This can be achieved either programmatically or using available online tools:

bash
Copy to clipboard.
1base64url "didcomm://https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/requests/38d9ca70-8b61-48c3-9efc-b67d97410743/didcommuri"

2. Take the base64url string and append it to a deeplink URL of the following structure:

global.mattr.wallet://accept/{base64urlString}

When sending a deep link to a MATTR GO Wallet, replace the scheme with your app bundle ID. The following example shows a deep link for a MATTR GO Wallet that has com.example.wallet as its app bundle ID:

com.example.wallet://accept/{base64urlString}

3. Send this URL using any existing communication channels, as long as the message can be opened on a mobile device (e.g. email, Slack message etc).

For MATTR Pi Wallet SDK customers, refer to your own implementation for deep linking requirements and best practices.

Send as a MATTR VII message

To send the request as a MATTR VII message, you must first encrypt it.

Encrypt the message

Request

Make a request of the following structure to encrypt the verification request:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v1/messaging/encrypt
json
Copy to clipboard.
1{
2    "senderDidUrl": "did:web:organization.com#CU6dJt9p8t",
3    "recipientDidUrls": [
4      "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
5    ],
6    "payload": {
7      "id": "38d9ca70-8b61-48c3-9efc-b67d97410743",
8      "type": "https://mattr.global/schemas/verifiable-presentation/request/QueryByExample",
9      "from": "did:web:example.com",
10      "created_time": 1607300517863,
11      "body": {
12        "uri": "didcomm://https://YOUR_TENANT_URL/v2/credentials/web-semantic/presentations/requests/38d9ca70-8b61-48c3-9efc-b67d97410743/didcommuri"
13    }
14  }
15}

  • senderDidUrl: The sender's DID URL, obtained from the id field of the first keyAgreement entry in the DID document. Refer to our DID tutorial for more information.

  • recipientDidUrls: Use the holder's Subject DID.

  • payload: These detailed are obtained when you create a presentation request:

    • id: Request identifier.

    • type: Offer type.

    • from: Verifier DID.

    • created_time: Time of creation (Unix time). Note that the value must be a number and not a string, otherwise the holder will not be able to accept the credential offer.

    • body:

Response

json
Copy to clipboard.
1{
2  "jwe": {
3    "protected": "eyJhbGciOiJYQzIwUCJ9",
4    "recipients": [
5      {
6        "header": {
7          "alg": "ECDH-1PU+A256KW",
8          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
9          "epk": {
10            "kty": "OKP",
11            "crv": "X25519",
12            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
13          },
14          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
15        },
16        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
17      }
18    ],
19    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
20    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
21    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
22  }
23}

The result is an encoded message payload constructed using the JWM format.

Send the message

Request

Make a request of the following structure to send the encrypted verification request to the holder's digital wallet:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v1/messaging/send
json
Copy to clipboard.
1{
2"to": "{SUBJECT_DID}",
3"message": {
4    "protected": "eyJhbGciOiJYQzIwUCJ9",
5    "recipients": [
6      {
7        "header": {
8          "alg": "ECDH-1PU+A256KW",
9          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
10          "epk": {
11            "kty": "OKP",
12            "crv": "X25519",
13            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
14          },
15          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
16        },
17        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
18      }
19    ],
20    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
21    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
22    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
23  }
24}

  • to: Use the holder's Subject DID.

  • message: Use the content of the jwe object obtained in the previous step response. Note that you do not need to include the preceding jwe attribute, only the content of the object.

Response

A 200 response indicates that the message payload was sent to the service endpoint of the dereferenced DID Document (or the default MATTR service endpoint).

What's next?

The holder will now receive the presentation request. They can review it and must consent to sharing their information. This will enable the wallet to send a verifiable presentation with the required claims for verification.