Configure credential branding


This guide will demonstrate how to customise a web credential with your branding using MATTR VII. This includes adding images and nested data that can be displayed by MATTR Mobile Wallet app to improve the user experience for the wallet holder. 


Before you can customise your credential payload. You will need

  1. Your intended brand colour

  2. URLs of images for your logo, icon and watermark

Branding configuration

To apply branding to a web credential, a set of attributes can be optionally included in the credential request payload.

issuer block

Include a logoUrl and iconUrl attribute to define the logo and icon displayed on a credential in the wallet.

These attributes must be a publicly accessible URL to image files that are either .svg files (vector format) or .png/.jpg (raster format). We strongly recommend using vector images. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices. Transparencies are allowed for svg or png images.

Copy to clipboard.
1"issuer": {
2    "id": "{Issuer DID}}",
3    "name": "{{Issuer Name}}", // this is the issuer name not the name of the credential
4    "logoUrl": "{{logo_image_url}}",
5    "iconUrl": "{{icon_image_url}}"

credentialBranding block

Add a credentialBranding block to the credential payload to define the backgroundColor and watermarkImageURL.

Copy to clipboard.
1"credentialBranding": {
2    "backgroundColor": "{{colour_hex_value}}",
3    "watermarkImageUrl": "{{watermark_image_url}}"

The following table outlines the full set of attributes utilised to render the credential branding correctly in the wallet.

The credential name and description are attributes that should be included at the root level of the credential.



Accepted data type and specifications


Credential Type:
To categorise the credential

String [1]


Credential Title:
A short, identifier label

Short string ~120 characters [2]


Brand colour:
Colour of your credential card

Hex code


The pattern to be included in the card

full URL with scheme

245 × 150 px (.svg / .png / .jpg)


– or –


at root when using OIDC issuance

Issuer Logo:
Image of the issuer Logo

full URL with scheme

140 × 42 px (.svg / .png / .jpg)


– or –


at root when using OIDC issuance

Issuer Icon:
Image of the Icon to be displayed in the card

full URL with scheme

32 × 32 px (.svg / .png / .jpg)

[1] 18 characters for 1 line, 36 characters for 2 lines when full array of credential feature icons are showing. Truncation occurs at any greater character string.

[2] 1 line max, 38 characters. Truncation occurs at any greater character string.

Example request

Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/sign
Copy to clipboard.
2   "payload":{
3      "@context":[
4         ""
5      ],
6      "name":"Course Credential",
7      "description":"Diploma in Management",
8      "type":[
9         "VerifiableCredential",
10         "CourseCredential"
11      ],
12      "credentialBranding":{
13         "backgroundColor":"#6303FF",
14         "watermarkImageUrl":""
15      },
16      "issuer":{
17         "id":"",
18         "name":"Zealopia Business Institute",
19         "logoUrl":"",
20         "iconUrl":""
21      },
22      "expirationDate":"2024-02-07T06:44:28.952Z",
23      "credentialSubject":{
24         "id":"did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
25         "givenName":"Chris",
26         "familyName":"Shin",
27         "educationalCredentialAwarded":"Diploma in Management"
28      }
29   },
30  "persist":false,
31  "revocable":false

Here is what the credential card looks like with and without branding in the MATTR Wallet:

Branded (left) and Unbranded (right) Credentials

Generate a web credential

The above branding configuration can be applied to Web Credentials generated through the MATTR VII platform.

Follow one of these tutorials alongside the branding configuration above to issue a Web Credential that includes your chosen branding: