4.5 Card Specs

4.5.1 Common

This chapter defines Wallet Card data fields for the attributes object of each wallet card type.

The structure for configuring wallet cards follows the defined specification. Configuring the card data in the specified formatted JSON structure is required. See the details for each card type.

Type

 Value

 Description
Card object

 card
Object

 (Required)
Card information.
card.type
String(16)

 (Required)
Wallet Card type
card.subType
String(16)

 (Required)
Wallet Card sub type
card.data[]
Array of Object

 (Required)
Wallet card data container
Allows up to 6 objects at once
data[].refId
String(32)

 (Required)
A unique content identifier defined
by the content provider
data[].createdAt
Long(13)

 (Required)
Data creation timestamp.
Epoch timestamp in milliseconds.
* UTC±00:00
data[].updatedAt
Long(13)

 (Required)
Data creation timestamp.
Epoch timestamp in milliseconds.
* UTC±00:00
data[].language
String(8)

 (Required)
Default content language code.
e.g., en, ko
data[].attributes
Object

 (Required)
Card data attributes.
* Refer to the following chapters for each type
data[].attributes.{fields}

 Attribute fields by card type.
data[].localization[]
Array of Object

 (Conditional)
Information for multilingual support.
localization[].language
String(8)

 (Required)
Multilingual content language code.
e.g., en, ko, etc
localization[].attributes.{fields}

 For displaying a given language,
‘data[].attributes’ can be replaced by
localized versions.
* Refer to the following chapters for each type

[Example]
Example: Card object

{
	"card": {
		"type": "relyingparty",
		"subType": "others",
		"data": [
			{
				"refId": "ref-20230304-001",
				"createdAt": 1612660039000,
				"language": "en",
				"attributes": {
					"title": "Samsung Wallet",
					"mainImg": "https://../main.png"
					
				//** Please refer to the details of the following each card. **
					
				},
				"localization": [
					{
						"language": "ko",
						"attributes": {
							"title": "삼성 월렛"
						}
					}
				]
			}
		]
	}
}

To ensure secure card data transmission, it must be tokenized in JWT format. For this purpose, partner will need the certificate obtained using the partner's email account when signing up for the partner portal.

For detailed information on secure data tokenization, partners can refer to the Security
chapter.

*Image resources provided by URLs can be cached. Therefore, for the image resource to be replaced immediately, the corresponding URL path must be changed.

4.5.2 Relying Party

‘relyingparty’ cards are used for verifier authentication.

When partners create the Verify with Samsung Wallet button, they will need to create cdata.
This is the data spec included when creating the cdata of relayingparty type.

Wallet Card type

Wallet card type

 Wallet card subtype
relyingparty

 Others

Others

Wallet Card data fields

Attributes

Type

 Value

 Description
attributes{fields}

 logoImage
String(256)

 (Required)
URL of the logo image.
The file size must not be greater than 256 KB.
logoImage.darkUrl
String(256)

 (Required)
URL of the logo image.
The file size must not be greater than 256 KB.
logoImage.lightUrl
String(256)

 (Required)
URL of the logo image.
The file size must not be greater than 256 KB.
fontColor
String(8)

 (Optional)
Display Color of the font during user authentication.
providerName
String(32)

 (Required)
Display name during user authentication
clientType
String(32)

 (Required)
Information on whether the client operates as an application or Web.
clientPackageName
String(32)

 (Required)
If the client is operating as an app, enter the package name, If it works on the web, enter a service name.

[Example]

{
	"card": {
		"type": "relyingparty",
		"subType": "others",
		"data": [
			{
				"refId": "0613001",
				"createdAt": 1686657600000,
				"updatedAt ": 1686657600000,
				"language": "en",
				"attributes": {
					"logoImage": "https://samsung.com",
					"logoImage.darkUrl": "https://dark.samsung.com",
					"logoImage.lightUrl": "https://light.samsung.com",
					"fontColor": "black",
					"providerName": "Company Name",
					"clientType": "app",
					"clientPackageName": "com.companyName.app"
				}
			}
		]
	}
}