How to create an OID4VCI credential offer

The offer URI can be created either via the MATTR Portal or the MATTR VII Platform APIs.

POST /v1/openid/offers

{
  "credentials": ["20d6bbe6-a978-447c-b5bd-f33b6dca19e2"],
  "request_parameters": {
    "login_hint": "user@example.com",
    "prompt": "login"
  }
}

{
  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Ftenant.vii.mattr.global%22%2C%22credentials%22%3A%5B%2220d6bbe6-a978-447c-b5bd-f33b6dca19e2%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"
}

Make a request of the following structure to generate a new credential offer for an OID4VCI Pre-authorized Code flow:

POST /v1/openid/offers/pre-authorized

{
  "credentials": ["707e920a-f342-443b-ae24-6946b7b5033e"],
  "userId": "b7e2c8f4-1a2b-4c3d-9e5f-8a7b6c5d4e3f",
  "transactionCodeConfiguration": {
    "inputMode": "numeric",
    "description": "Please enter the one-time code that was sent to you via email."
  },
  "claims": {
    "givenName": "John",
    "familyName": "Doe",
    "email": "john.doe@example.com",
    "userId": "e7b8c2f1-4a3d-4e6b-9c2a-1f5d8e7a9b3c"
  },
  "claimsToPersist": ["userId"],
  "expiresIn": {
    "minutes": 5,
    "seconds": 0
  }
}

• credentials : This array includes a list of identifiers for mDoc credential configurations that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a Credential configuration.

  To issue multiple credential formats of the same credential in a single flow, include all the required credential configuration id elements in the request payload.

  Providing an identifier of a non-mDoc credential configuration will result in an error.

• userId : Unique system generated identifier to reference the user for this offer. This can be obtained by searching for a user. If not provided, a new user entity will be created.

• transactionCodeConfiguration : This object contains the configuration for the transaction code that will be associated with this credential offer and must be provided by the holder when claiming the credential. It includes the following properties:

  • inputMode : The input mode for the transaction code. Currently only numeric is supported.
  • description : A description of the transaction code that will be sent to the user as part of the credential offer.

• claims : This object contains the claims that will be included in the issued credential. The claims must match the mapping defined in the Credential configuration. By default, claims data is only stored for the lifetime of the offer, unless you specify them in the optional claimsToPersist array.

• claimsToPersist : This array includes a list of claims that will be persisted in the MATTR VII database. By default no claims are persisted.

• expiresIn : Specifies when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated. The expiration period can include any combination of minutes and seconds. By default, the offer expires in 5 minutes, and the maximum allowed duration is 10 minutes.

Response

{
  "id": "b1a7c9e2-4d5f-4a6b-9e8c-2f3d4b5a6c7e", 
  "userId": "b7e2c8f4-1a2b-4c3d-9e5f-8a7b6c5d4e3f",
  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fexample.com%22%2C%22credentials%22%3A%5B%222edaf985-fcc2-4448-9c8e-a04c6c7351c2%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22stukD6lg9c9tQ3jUCa32wVi1HI%2BQIVsFK%2FQPvC2CHRs%3D%22%2C%22tx_code%22%3A%7B%22length%22%3A6%2C%22input_mode%22%3A%22numeric%22%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20via%20e-mail%22%7D%7D%7D%7D", 
  "expiresAt": "2025-05-01T00:01:00.000Z", 
  "transactionCode": 493536
}

• id : Unique system generated identifier to reference this offer.
• uri : This is the URI that should be used by the intended holder to claim the credential. For a Pre-authorized Code flow credential offers this URI includes the pre-authorized code which enables the wallet to retrieve the credential without requiring the user to provide any additional authentication.
• expiresAt : The date and time when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated.
• transactionCode : This is the transaction code that must be provided by the user when claiming the credential. This code must be shared by the issuer with the holder via a separate and secure channel.

A common way to allow a digital wallet user to claim a credential is to encode the offer URI into a QR code. You could even print out the QR code.

You can use a tool similar to the following to convert the URI to a QR code (make sure you use the Plain text option where available):

• https://www.the-qrcode-generator.com/

• http://goqr.me/api/

• https://www.qr-code-generator.com/

  MATTR is not affiliated with any of these service providers and cannot vouch for their offerings.

Once the QR code is created, you can send it to the intended holder via your preferred communication channel.

Best practices

• Make sure the QR code is large enough in size to be resolvable by a phone camera; 200px square is generally sufficient.

You can enable the intended holder to open the offer URI directly from their mobile device by creating a deep link.

1. Perform base64url encoding of the offer URI.
   You can use Base64 Guru or any similar tool.
2. Use the output (the offer URI encoded as base64url) to create a link of the following structure:

global.mattr.wallet://accept/{base64Url(openid-credential-offer://...)}

For example:

global.mattr.wallet://accept/b3BlbmlkLWNyZWRlbnRpYWwtb2ZmZXI6Ly8_Y3JlZGVudGlhbF9vZmZlcj0lN0IlMjJjcmVkZW50aWFsX2lzc3VlciUyMiUzQSUyMmh0dHBzJTNBJTJGJTJGdGVuYW50LnZpaS5tYXR0ci5nbG9iYWwlMjIlMkMlMjJjcmVkZW50aWFscyUyMiUzQSU1QiUyMjIwZDZiYmU2LWE5NzgtNDQ3Yy1iNWJkLWYzM2I2ZGNhMTllMiUyMiU1RCU3RA

3. Once the deep link is created, you can send it to the recipient via your preferred communication channel.

MATTR GO deep-links

When sending a deep link to a MATTR GO Hold, 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, as shown in the example below:

com.example.wallet://accept/b3BlbmlkLWNyZWRlbnRpYWwtb2ZmZXI6Ly8_Y3JlZGVudGlhbF9vZmZlcj0lN0IlMjJjcmVkZW50aWFsX2lzc3VlciUyMiUzQSUyMmh0dHBzJTNBJTJGJTJGdGVuYW50LnZpaS5tYXR0ci5nbG9iYWwlMjIlMkMlMjJjcmVkZW50aWFscyUyMiUzQSU1QiUyMjIwZDZiYmU2LWE5NzgtNDQ3Yy1iNWJkLWYzM2I2ZGNhMTllMiUyMiU1RCU3RA

MATTR Pi deep-links

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

To send the Credential offer as a DID message you must first encrypt it and then send it as an encrypted message.

Step 1: Encrypt a Credential offer

Make a request of the following structure to encrypt the Credential offer:

POST /v1/messaging/encrypt

{
  "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
  "recipientDidUrls": [
    "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
  ],
  "payload": {
    "id": "731961f2-bdc3-4f1e-8d59-cc308fd60ec8",
    "type": "https://mattr.global/schemas/verifiable-credential/offer/OidcCredentialProvider",
    "from": "did:web:organization.com",
    "created_time": 1616466734,
    "body": {
      "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Ftenant.vii.mattr.global%22%2C%22credentials%22%3A%5B%2220d6bbe6-a978-447c-b5bd-f33b6dca19e2%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"
    }
  }
}

• senderDidUrl : Use the Issuer DID.
• recipientDidUrls : Use the Subject DID.
• payload :
  • id : Use the Credential configuration id.
  • type : Use the https://mattr.global/schemas/verifiable-credential/offer/OidcCredentialProvider to indicate that this message includes a Credential offer.
  • from : Use the Issuer DID.
  • created_time : Time of creation (Epoch Unix timestamp). The value must be a number and not a string, otherwise the holder will not be able to accept the Credential offer.
• body :
  • uri : Use the credential offer URI, obtained when the offer was created.

Response

{
  "jwe": {
    "protected": "eyJhbGciOiJYQzIwUCJ9",
    "recipients": [
      {
        "header": {
          "alg": "ECDH-1PU+A256KW",
          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
          "epk": {
            "kty": "OKP",
            "crv": "X25519",
            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
          },
          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
        },
        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
      }
    ],
    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
  }
}

Step 2: Send an encrypted Credential offer

Make a request of the following structure to send the encrypted Credential offer:

POST /v1/messaging/send

{
  "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  "message": {
    "protected": "eyJhbGciOiJYQzIwUCJ9",
    "recipients": [
      {
        "header": {
          "alg": "ECDH-1PU+A256KW",
          "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
          "epk": {
            "kty": "OKP",
            "crv": "X25519",
            "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
          },
          "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
        },
        "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
      }
    ],
    "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
    "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
    "tag": "u8kT0VAAtTswjGXxNpuX0g=="
  }
}

• to : Use the intended holder's Subject DID.
• message : Use the content of the jwe object from the previous step's response (do not include the jwe property name, just its content).

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