Digital Keys

A Digital Key securely and conveniently grants access to homes, vehicles, and other entry points.

Wallet card type

 Wallet card subtype
digitalkey

 doors, hotels, cars, others

Device Compatibility

For supported devices of the Home key, refer to Device Compatibility section.

doors

hotels

cars

Wallet Card data fields

Attributes

Type

 Value

 Description
attributes.{fields}

 title
String(32)

 (Required)
Main title of cards.
e.g., Multifamily Housing.
holderName
String(64)

 (Optional)
Name of the cardholder.
userGroup
String(64)

 (Optional)
Group to which the cardholder belongs.
e.g., the name of a multifamily housing community.
identifier
String(64)

 (Optional)
Unique identifier.
keyId
String(64)

 (Optional)
Representative identifier for the key.
keyStatus
String(16)

 (Conditional)
Key
keyInfo
String(64)

 (Optional)
Key Information.
i.e., Unique house number.
issueDate
Long(13)

 (Required)
Issue date
Epoch timestamp in milliseconds.
expiry
Long(13)

 (Optional)
Expiry date in timestamp format.
Issued data is cleaned up after it expires.
Epoch timestamp in milliseconds.
address
String(256)

 (Optional)
Address of the cardholder.
providerName
String(32)

 (Required)
Content provider name.
issuerName
String(32)

 (Optional)
Place of issue or Issuing authority name.
extraInfo
String(512)

 (Optional)
Additional information.
* See Additional information
noticeDesc
String(5000)

 (Optional)
Text of the notice
* Long content is allowed.
* See Additional information
csInfo
String(4096)

 (Required)
Provider customer service information.
Provide the value as an escaped JSON string.
* Allowed items: call, email, or website.
* See the example below.
appLinkLogo
String(256)

 (Optional)
App link image URL.
The file size should not exceed 256 kB.
appLinkName
String(32)

 (Optional)
App link name.
appLinkData
String(256)

 (Optional)
Information about the partner app link.
locations
String(1024)

 (Optional)
List of locations where the card can be used.
* See Locations
logoImage
String(256)

 (Optional)
Logo image URL to be displayed on the card item
The file size should not exceed 256 kB
logoImage.darkUrl
String(256)

 (Optional)
Logo image URL in dark mode.
This is a flat key name, not a nested object path.
The file size should not exceed 256 kB.
* If this value does not exist, logoImage will be substituted.
logoImage.lightUrl
String(256)

 (Optional)
Logo image URL in light mode.
This is a flat key name, not a nested object path.
The file size should not exceed 256 kB.
* If this value does not exist, logoImage will be substituted.
logoText
String(16)

 (Optional)
Text as an alternative to logoImage.
coverImage
String(256)

 (Optional)
Card cover image URL.
The file size should not exceed 512 kB.
The recommended size for image resources is 888 x 555 px.
bgImage
String(256)

 (Optional)
Card background image URL.
The file size should not exceed 512 kB.
The recommended size for image resources is 888 x 555 px.
bgColor
String(8)

 (Optional)
Colour of the card art.
Supports hexadecimal colour codes.
e.g., #015AAA
fontColor
String(8)

 (Optional)
Colour of the text on the card art.
Allowed values: black, white.
blinkColor
String(8)

 (Optional)
Colour of the blinking effect in the indicator area.
Supports hexadecimal colour codes.
e.g., #015AAA
privacyModeYn
String(1)

 (Optional)
Whether user authentication is required when using the card.
Either ‘Y’ or ‘N’.
* Default: ‘N’
preventCaptureYn
String(1)

 (Optional)
Flag whether this wallet card view prevents screen capture.
Either 'Y' or 'N'.
* Default: 'N'
authentication
String(64)

 (Optional)
Authentication data that satisfies the selected authentication method.
* See Authentication Data Set (Secure Add to Wallet)
provision.data
String(512)

 (Optional)
Elements to complete provisioning
* Refer to Access Integration Guide. Samsung approval required. Contact Technical Support.
provision.interval
String(16)

 (Optional)
Update interval for dynamic provisioning, in milliseconds.
* Refer to Access Integration Guide. Samsung approval required. Contact Technical Support.
barcode.value
String(4096)

 (Optional)
Actual data that is delivered when the barcode/QR code is scanned.
barcode.serialType
String(32)

 (Optional)
Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode & QR Code Presentation
barcode.ptFormat
String(32)

 (Optional)
Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode & QR Code Presentation
barcode.ptSubFormat
String(32)

 (Optional)
Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode & QR Code Presentation
barcode.errorCorrectionLevel
String(4)

 (Optional)
Amount of redundancy or error correction data included in the code.
There are four error correction levels available in QR codes.
Code options: L/M/Q/H
* Default: L
barcode.interval
String(11)

 (Conditional)
Refresh interval for dynamic barcode updates, in milliseconds.
* Required when barcode.generationType is INTERVAL.

Example: doors

{
  "card": {
    "type": "digitalkey",
    "subType": "doors",
    "data": [{
        "refId": "doorkey-gh3ytr82gbf8v3-32u5y2-283bgnkd",
        "createdAt": 1658385817000,
        "updatedAt": 1658385817000,
        "language": "en",
        "attributes": {
          "title": "Samsung MFH Doorlock",
          "identifier": "128768375901",
          "keyId": "128768375901",
          "keyStatus": "LOCKED",
          "keyInfo": "Samsung Multi-Family House",
          "issueDate": 1765855665000,
          "providerName": "Samsung Electronics",
          "csInfo": "{\"call\":\"555-123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.com/cs\"}",
          "bgImage": "https://../card/background.png",
          "extraInfo": "{\"count\":1,\"info\":[{\"title\":\"shortCode\",\"content\":[\"404457\"]}]}",
          "noticeDesc": "{\"count\":2,\"info\":[{\"title\":\"NOTICE1\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]},{\"title\":\"NOTICE2\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]}]}",
          "authentication": "838645",
          "provision.data": "{provisioning data}"
        },
        "localization": [{
            "language": "ko",
            "attributes": {
              "title": "삼성 멀티 패밀리 하우스 도어키",
              "providerName": "삼성전자"
            }
        }]
    }]
  }
}

Example: hotels

{
  "card": {
    "type": "digitalkey",
    "subType": "hotels",
    "data": [
      {
        "refId": "b3fdc982-28c9-47a3-b02f-d484779698a8",
        "createdAt": 1672574400000,
        "updatedAt": 1672574400000,
        "language": "en",
        "attributes": {
          "title": "Samsung Hotel Key",
          "userGroup": "Guest",
          "identifier": "2306070003",
          "issueDate": 1658385817000,
          "expiry": 1765855665000,
          "logoImage": "https://../logo.png",
          "logoText": "Samsung",
          "providerName": "Samsung Electronics",
          "extraInfo": "{\"count\":1,\"info\":[{\"title\":\"shortCode\",\"content\":[\"404457\"]}]}",
          "noticeDesc": "{\"count\":2,\"info\":[{\"title\":\"NOTICE1\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]},{\"title\":\"NOTICE2\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]}]}",
          "csInfo": "{\"call\":\"555-123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.com/cs\"}",
          "appLinkName": "Samsung Electronics",
          "appLinkLogo": "https://../applinklogo.png",
          "appLinkData": "https://www.applinkOrWebLink.com",
          "coverImage": "https://../card/cover.png",
          "bgImage": "https://../card/background.png",
          "fontColor": "black",
          "barcode.value": "5728306720836720763017601",
          "barcode.serialType": "QRCODE",
          "barcode.ptFormat": "QRCODE",
          "barcode.ptSubFormat": "QR_CODE",
          "barcode.interval": "300000"
        }
      }
    ]
  }
}