Common

Supported card types

Select the card type and subtype for your approved use case, then apply the common fields below and the corresponding card-type specification.

Wallet card type

 Wallet card subtype
boardingpass

 airlines, trains, buses, others
ticket

 performances, sports, movies, entrances, others
coupon

 others
giftcard

 others
loyalty

 others
idcard

 employees, nationals, students, drivers, guests, others
digitalkey

 doors, hotels, cars, others
payasyougo

 evcharges, others
generic

 others
reservation

 rentalcars, restaurants, accommodations, etickets, taxis, activities, others
transitcard

 others
clip

 businesstrips, trips, others

Card-type specifications

Common card data

The structure for configuring wallet cards follows the defined specification. Configuring the card data in the specified formatted JSON structure is required.
Card-type-specific constraints, conditional requirements, and unsupported features are defined in the corresponding card type sections below. Partners should review the relevant card type section before finalizing a payload.
For fields marked as Conditional, the trigger condition is defined in the description text (for example, required for a specific card type, subType, state, or flow).

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 subtype
card.data[]
Array of Object

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

 (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)
Timestamp of the most recent data update.
Epoch timestamp in milliseconds.
* UTC±00:00
data[].language
String(8)

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

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

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

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

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

 To display a specific language,
‘data[].attributes’ can be replaced by localised versions.
* Refer to the following chapters for each type
Security components

 confirmationValue
String(256)

 (Optional)
Reference values for authenticating card registration requests
* See Authentication Data Set (Secure Add to Wallet)

Example: Card object (Event Ticket)

{
  "card": {
    "type": "ticket",
    "subType": "movies",
    "data": [{
        "refId": "ref-20230304-001",
        "createdAt": 1612660039000,
        "updatedAt": 1612660039000,
        "language": "en",
        "attributes": {
          "title": "Samsung Wallet",
          "mainImg": "https://../main.png"
          // Add the required attributes for the selected card type and subtype.
        },
        "localization": [{
            "language": "ko",
            "attributes": {
              "title": "삼성 월렛"
            }
        }]
    }]
  }
}

To ensure secure transmission of card data, cdata must be serialized as a JWS-wrapped JWE token rather than a plain JWT. For this purpose, you will require the certificate obtained using the partner's email account when signing up for the partner portal.
For detailed information on secure data tokenization, please refer to the Authentication Data Set (Secure Add to Wallet) section.
*Image resources provided by URLs can be cached. Therefore, for the image resource to be replaced immediately, the corresponding URL path must be changed.