Wallet Cards

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

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}

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": "ticket",
    "subType": "movies",
        "data": [{
        "refId": "ref-20230304-001",
        "createdAt": 1612660039000,
        "language": "en",
            "attributes": {
            "title": "Samsung Wallet",
            "mainImg": "https://../main.png"

            *Refer to the following chapters for each type

            },
            "localization": [{
            "language": "ko",
                "attributes": {
                "title": "삼성 월렛"
                }
            }]
        }]
    }
}

To ensure secure transmission of card data, it must be tokenized in JWT format. 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 Security chapter.

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

Boarding Pass

'Boarding pass' cards support one-off transit types such as airlines, trains, buses, ferries, and etc.

Boarding passes in Wallet can remind the user of boarding time and help during check-in. Depending on the integration level, it can provide status information updates related to flights, and journeys, such as boarding gate changes or cancellations.

Wallet card type

Wallet card subtype

boardingpass

airlines, trains, buses, others

-Airlines

Figure 1: Sample UI: Boarding pass - Airlines

-Buses

Figure 2: Sample UI: Boarding Pass - Buses

-Trains

Figure3: Sample UI: Boarding Pass - Buses

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title.
e.g., 'BOARDING PASS'.

2

transitType

String (16)

Optional

Transit type.
* This will be deprecated.

3

groupingId

String (32)

Optional

Identifier used to group related cards

4

orderId

String (32)

Optional

Unique identifier for an order

5

providerLogo

String (256)

Required

URL of the logo image.
The file size should not exceed than 256 kB.

6

providerLogo.darkUrl

String (256)

Required

URL of the logo image in dark mode.
The file size should not exceed 256 kB.

7

providerLogo.lightUrl

String (256)

Required

URL of the logo image in light mode.
The file size should not exceed 256 kB.

8

providerName

String (32)

Required

Display name of the boarding pass provider

9

user

String (64)

Conditional

Passenger Name.
* Required if subType is airlines

10

userType

String (32)

Optional

Passenger type
i.e., Classification of passengers, like Child, Adult.

11

transitOperator

String (64)

Optional

Operator name

12

vehicleNumber

String (32)

Conditional

Transit or route number
i.e., Flight number on airlines.
* Required if subType is airlines.

13

transitClass

String (32)

Optional

Transit class
i.e., Premium class for buses.

14

transitFare

String (32)

Optional

General fare or purchase fare

15

coachNumber

String (16)

Optional

Identifier assigned to each individual carriage.
e.g., B4.

16

seatClass

String (32)

Conditional

Seat class.
* Required if subType is airlines

17

seatNumber

String (16)

Required

Individual number of the passenger seat.
e.g., A-9, Free.

18

seatFacing

String (16)

Optional

Direction in which the seat is oriented within a carriage.
It indicates whether the seat is positioned to face the direction of travel or face the opposite direction.
e.g., Forward, Backward.

19

reservationNumber

String (32)

Required

Number of the transit reservation

20

boardingPriority

String (32)

Optional

Information on whether entitles the passenger to board before others.
i.e., if the passengers are pregnant.

21

boardingSeqNo

String (32)

Optional

Boarding sequence number

22

boardingGroup

String (8)

Optional

Value of boarding group or zone.
e.g., B.

23

boardingTime

Long (13)

Optional

Boarding time.
Epoch timestamp in milliseconds.

24

boardingTime.utcOffset

String (8)

Conditional

UTC offset of boarding time at the departure point.
* Required if boardingTime exist

25

gateClosingTime

Long (13)

Optional

Boarding gate closing time.
Epoch timestamp in milliseconds.

26

gateClosingTime.utcOffset

String (8)

Conditional

UTC offset of gate closing time at the departure point.
* Required if gateClosingTime exist

27

baggageAllowance

String (16)

Optional

Baggage allowance

28

departName

String (32)

Conditional

Name of the departure point.
* Required if subType is airlines.

29

departCode

String (8)

Conditional

Code for the departure point.
* Required if subType is airlines.

30

departTerminal

String (8)

Conditional

Terminal name of the departure point.
* Required if subType is airlines.

31

departGate

String (8)

Optional

Gate name of the departure point

32

estimatedOrActualStartDate

Long (13)

Conditional

Departure time.
Epoch timestamp in milliseconds, i.e., the estimated time the aircraft plans to pull from the gate, or the actual time the aircraft already pulled from the gate.
* Required if subType is airlines.

33

estimatedOrActualStartDate. utcOffset

String (8)

Conditional

UTC offset of time at the departure point.
* Required if estimatedOrActualStartDate exists.

34

arriveName

String (32)

Conditional

Name of the arrival point.
* Required if subType is airlines.

35

arriveCode

String (8)

Conditional

Code for the arrival point.
* Required if subType is airlines.

36

arriveTerminal

String (8)

Optional

Terminal name of the arrival point

37

arriveGate

String (8)

Optional

Gate name of the arrival point

38

estimatedOrActualEndDate

Long (13)

Conditional

Arrival time.
Epoch timestamp in milliseconds, i.e., the estimated time the aircraft plans to reach the destination gate (not the runway), or the actual time it reached the gate.
* Required if subType is airlines.

39

estimatedOrActualEndDate. utcOffset

String (8)

Conditional

UTC offset of time at the arrival point.
* Required if estimatedOrActualEndDate exists.

40

locations

String (1024)

Optional

List of locations where the card can be used.
* See Location format.

41

bgColor

String (8)

Required

Color of the card art.
e.g., #00FFFF.

42

fontColor

String (8)

Optional

Color of the font on the card art.
Acceptable values: dark, light.

43

blinkColor

String (8)

Optional

Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

44

appLinkLogo

String (256)

Required

App link image URL.
The file size should not exceed 256 kB.

45

appLinkName

String (32)

Required

App link name.

46

appLinkData

String (256)

Required

Information about the partner app link.

47

extraInfo

String (512)

Optional

Additional information to be delivered to customers.
* See Additional Information format.

48

noticeDesc

String (5000)

Optional

Text of the notice.
* Long content is allowed.
* See Additional Information format.

49

csInfo

String (512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, or website
* See below for an example.

50

displayTSAPreCheckYn

String (1)

Optional

Flag whether to display the TSA PreCheck image. Either ‘Y’ or ‘N’.
Image size: 68x20 / 140x20

51

membershipStatusLevel

String (256)

Optional

Image URL for the status level of the airline alliance or own membership.
i.e., Airline: SkyTeam, Star Alliance.
Image size: 68x20 / 140x20

52

barcode.value

String (4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.

53

barcode.serialType

String (32)

Optional

Presentation type.
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

54

barcode.ptFormat

String (32)

Optional

Presentation format.
e.g., BARCODE, QRCODE, SERIAL, ...
*See Barcode format.

55

barcode.ptSubFormat

String (32)

Optional

Presentation sub-format.
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

56

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

Example

Airline boarding pass
{
    "card":{
        "type": "boardingpass",
        "subType": "airlines",
        "data": [
            {
                "refId": "SE16138353212584800001",
                "createdAt": 1612660039000,
                "updatedAt": 1612660039000,
                "language": "en",
                "attributes": {
                    "title": "OO AIR BOARDING PASS",
                    "transitType": "Airline",
                    "groupingId": "SE867132687321",
                    "providerLogo": "https://../logoImage.png",
                    "providerLogo.darkUrl": "https://../logoImage.png",
                    "providerName": "OO AIR",
                    "user": "GIL DONG HONG",
                    "vehicleNumber": "SE123",
                    "seatClass": "Economy Plus",
                    "seatNumber": "A15",
                    "reservationNumber": "A238473-1",
                    "boardingSeqNo": "32",
                    "boardingTime": 1612660039000,
                    "boardingTime.utcOffset": "UTC+09:00",
                    "baggageAllowance": "15KG",
                    "departName": "SEOUL/INCHEON",
                    "departCode": "INC",
                    "departTerminal": "C",
                    "departGate": "1",
                    "estimatedOrActualStartDate": 1612660039000,
                    "estimatedOrActualStartDate.utcOffset": "UTC+09:00",
                    "arriveName": "SAN FRANCISCO",
                    "arriveCode": "SFO",
                    "arriveTerminal": "A",
                    "arriveGate": "11",
                    "estimatedOrActualEndDate": 1612660039000,
                    "estimatedOrActualEndDate.utcOffset": "UTC-08:00",
                    "bgColor": "#FF00FF",
                    "fontColor": "dark",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkName": "OO Airline",
                    "appLinkData": "https://www.ooairline.com",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"webSite\":\"https://www.samsungwallet.com/cs/\"}",
                    "barcode.value": "CS16138353212584806754FG1802",
                    "barcode.serialType": "BARCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "OO 항공 탑승권",
                            "providerName": "OO 항공",
                            "user": "홍 길동"
                        }
                    }
                ]
            }
        ]
    }
}

Grouped Bus boarding passes
{
    "card": {
        "type": "boardingpass",
        "subType": "buses",
        "data": [
            {
                "refId": "ref-202211300001",
                "createdAt": 1669782394000,
                "updatedAt": 1669782394000,
                "language": "en",
                "attributes": {
                    "title": "Samsung Bus Boarding Pass",
                    "transitType": "Bus",
                    "groupingId": "grp-20221130001",
                    "providerLogo": "https://../logoImage.png",
                    "providerLogo.darkUrl": "https://../logoImageDark.png",
                    "providerName": "SAMSUNG BUS",
                    "user": "GALAXY KIM",
                    "userType": "Adult",
                    "transitOperator": "Samsung Transport Co.",
                    "seatNumber": "7-A",
                    "reservationNumber": "RSVNO-202211300001",
                    "transitClass": "Premium",
                    "transitFare": "12,500 WON",
                    "boardingTime": 1671926400000,
                    "boardingTime.utcOffset": "UTC+09:00",
                    "departName": "EAST-SEOUL Bus Terminal",
                    "departGate": "14",
                    "estimatedOrActualStartDate": 1671928200000,
                    "estimatedOrActualStartDate.utcOffset": "UTC+09:00",
                    "arriveName": "SUWON Bus Terminal",
                    "bgColor": "#F1C232",
                    "fontColor": "dark",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkName": "Samsung Bus",
                    "appLinkData": "https://www.samsung-bus.com",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"webSite\":\"https://www.samsungwallet.com/cs/\"}",
                    "barcode.value": "161383532125848067541802",
                    "barcode.serialType": "BARCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "삼성버스 탑승권",
                            "providerName": "삼성버스",
                            "user": "김 은하",
                            "transitFare": "12,500 원"
                        }
                    }
                ]
            },
            {
                "refId": "ref-202211300002",
                "createdAt": 1669782394000,
                "updatedAt": 1669782394000,
                "language": "en",
                "attributes": {
                    "title": "Samsung Bus Boarding Pass",
                    "transitType": "Bus",
                    "groupingId": "grp-20221130001",
                    "providerLogo": "https://../logoImage.png",
                    "providerLogo.darkUrl": "https://../logoImageDark.png",
                    "providerName": "SAMSUNG BUS",
                    "user": "SAMSUNG SAM",
                    "userType": "Child",
                    "transitOperator": "Samsung Transport Co.",
                    "seatNumber": "7-B",
                    "reservationNumber": "RSVNO-202211300002",
                    "transitClass": "Preminum",
                    "transitFare": "9,000 WON",
                    "boardingTime": 1671926400000,
                    "boardingTime.utcOffset": "UTC+09:00",
                    "departName": "EAST-SEOUL Bus Terminal",
                    "departGate": "14",
                    "estimatedOrActualStartDate": 1671928200000,
                    "estimatedOrActualStartDate.utcOffset": "UTC+09:00",
                    "arriveName": "SUWON Bus Terminal",
                    "bgColor": "#F1C232",
                    "fontColor": "#000000",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkName": "Samsung Bus",
                    "appLinkData": "https://www.samsung-bus.com",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"webSite\":\"https://www.samsungwallet.com/cs/\"}",
                    "barcode.value": "161383532125848067541802",
                    "barcode.serialType": "BARCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "삼성버스 탑승권",
                            "providerName": "삼성버스",
                            "user": "사만다 삼성",
                            "transitFare": "9,000 원"
                        }
                    }
                ]
            }
        ]
    }
}

Event Ticket

'Event Ticket' cards support event commodities for performances, sports, movies, entrances, and etc.

Event tickets in Wallet can provide additional information about the event and an alarm before the event time and expiration. Ticket cards support event commodities for Performances, Sports, Movies, and Entrance.

Wallet card type

Wallet card subtype

ticket

performances, sports, movies, entrances, others

-Performances

Figure4: Sample UI: Ticket - Performances

-Movies

Figure 5: Sample UI: Ticket - Movies

-Sports

Figure 6: Sample UI: Ticket - Sports

-Entrances

Figure 7: Sample UI: Ticket - Entrances

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title.
e.g., MLB Ticket.

2

category

String (16)

Optional

Ticket category.
* This will be deprecated.

3

eventId

String (32)

Optional

If full cancelation of the event occurs, find and process all tickets with this ID

4

groupingId

String (32)

Optional

Identifier used to group related cards

5

orderId

String (32)

Optional

A unique identifier for an order

6

mainImg

String (256)

Required

URL for main ticket image.
The file size should not exceed 512 kB.

7

subtitle1

String (32)

Optional

The auxiliary field which displays supporting information.

8

logoImage

String (256)

Required

Logo image URL to be displayed in the Card item.
The file size should not exceed 256 kB.

9

logoImage.darkUrl

String (256)

Required

Logo image URL in dark mode.
The file size should not exceed 256 KB.

10

logoImage.lightUrl

String (256)

Required

Logo image URL in light mode.
The file size should not exceed 256 KB.

11

wideImage

String (256)

Optional

Wide horizontal image URL displayed on the Card information screen.
The file size should not exceed 256 kB.

12

providerName

String (32)

Required

Ticket provider name

13

providerViewLink

String (512)

Optional

Link to additional information from the provider
* See Links format.

14

classification

String (16)

Optional

Classification of tickets.
Use ONETIME, REGULAR, or ANNUAL.
* Default: ONETIME.

15

holderName

String (64)

Optional

Name of card holders

16

idPhoto

String (200000)

Optional

Holder’s photo image data encoded Base64

17

idPhoto.format

String (32)

Optional

Image file format
e.g., jpeg, png.
* Unsupported image formats may exist.

18

idPhoto.status

String(16))

Optional

Status of the data
Allowed value: UNCHANGED

19

grade

String (32)

Optional

Ticket grade

20

seatClass

String (32)

Optional

Seat class

21

entrance

String (64)

Optional

Entrance gate

22

seatNumber

String (256)

Optional

Seat location

23

seatLayoutImage

String (256)

Optional

URL of the seat layout image.
The file size should not exceed 512 KB.

24

issueDate

Long (13)

Required

Issue date.
Epoch timestamp in milliseconds.

25

reservationNumber

String (32)

Required

Reservation number

26

user

String (64)

Optional

Name of person who made the reservation

27

certification

String (16)

Optional

Ticket certification.
e.g.,R, as a film rating.

28

reactivatableYn

String (1)

Optional

Flag whether the card is able to activate an expired ticket temporarily.
Either 'Y' or 'N'.
* Default: 'N'

29

preventCaptureYn

String (1)

Optional

Flag whether this wallet card view prevents screen capture.
Either 'Y' or 'N'
* Default: 'N'

30

noNetworkSupportYn

String (1)

Optional

Set whether to support to open the wallet card under 'No Network' Status.
Either 'Y' or 'N'.
* Default: 'N'

31

startDate

Long (13)

Required

Start date (Displayed Start date).
Epoch timestamp in milliseconds.

32

endDate

Long (13)

Optional

End date (Displayed End date).
Epoch timestamp in milliseconds.
* If null, the card will expire in 10 hours from startDate.

33

person1

String (512)

Optional

Number of persons by category.
* See Classification format.

34

locations

String (1024)

Optional

List of locations where the card can be used.
* See Location format.

35

noticeDesc

String (5000)

Required

Text of the notice.
* Long content is allowed.
* See Additional Information format.

36

groupInfo1

String (64)

Optional

The first common information with the same groupingId.

37

groupInfo2

String (64)

Optional

The second common information with the same groupingId.
*It is recommended to set groupInfo1 first.

38

groupInfo3

String (64)

Optional

The third common information with the same 'groupingId'.
*It is recommended to set groupInfo1, groupInfo2 first.

39

csInfo

String (512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, website, facebook, youtube, or instagram
* See the example below.

40

privacyModeYn

String (1)

Optional

Whether or not to require user authentication when using the card
Either ‘Y’ or ‘N’
* Default: ‘N’

41

appLinkLogo

String (256)

Required

App link image URL.
The file size should not exceed 256 KB.

42

appLinkName

String (32)

Required

App link name

43

appLinkData

String (256)

Required

Information about the partner app link

44

bgColor

String (8)

Optional

Color of the card art.
e.g., #00FFFF.

45

fontColor

String (8)

Optional

Color of the font on the card art.
Acceptable values: dark, light.

46

blinkColor

String (8)

Optional

Color of the blinking effect in the Indicator area
e.g., #00FFFF

47

barcode.value

String (4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.

48

barcode.serialType

String (32)

Optional

Presentation type.
e.g., SERIALNUMBER, BARCODE....
* See Barcode format.

49

barcode.ptFormat

String (32)

Optional

Presentation format.
e.g., BARCODE, QRCODE, SERIAL....
* See Barcode format.

50

barcode.ptSubFormat

String (32)

Optional

Presentation sub-format.
e.g., CODE_128, QR_CODE....
* See Barcode format.

51

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

52

barcode.Interval

String (4)

Optional

Update interval if support for dynamic updates
Epoch timestamp in milliseconds.

Example

{
    "card": {
        "type": "ticket",
        "subType": "entrances",
        "data": [
            {
                "refId": "ent-ticket-0613001",
                "createdAt": 1686657600000,
                "updatedAt": 1686657600000,
                "language": "en",
                "attributes": {
                    "title": "Galaxy Land Entrance Ticket",
                    "subtitle1": "Standard",
                    "classification": "ANNUAL",
                    "groupingId": "group-0613001",
                    "orderId": "ent-0613001",
                    "mainImg": "https://../main.png",
                    "logoImage": "https://../logo.png",
                    "providerName": "Galaxy Entertainment",
                    "logoImage.darkUrl": "https://../logo-dark.png",
                    "issueDate": 1686657600000,
                    "reservationNumber": "GLX-0613-001",
                    "startDate": 1686657600000,
                    "endDate": 1718280000000,
                    "holderName": "Kim Eunha",
                    "idPhoto.data": "Base64-encoded{image-file-data}",
                    "idPhoto.format": "png",
                    "grade": "Family",
                    "person1": "{\"person\" : [{\"category\" : \"Adult\", \"count\": 1 }]}",
                    "locations": "[{\"lat\": 37.256518, \"lng\": 127.053516, \"address\": \"Samsung-ro Yeongtong-gu, Suwon\", \"name\": \"Galaxy Land: Central Park\"}]",
                    "noticeDesc": "{\"count\": 2,\"info\": [{\"title\": \"NOTICE 1\",\"content\": [\"DESCRIPTION 1-1\",\"DESCRIPTION 1-2\"]},{\"title\": \"NOTICE 2\",\"content\": [\"DESCRIPTION 2-1\"]}]}",
                    "groupInfo1": "Adult 1",
                    "groupInfo2": "Standard",
                    "groupInfo3": "Family",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"website\":\"https://www.samsungwallet.com/cs/\",\"instagram\":\"https://www.instagram.com/samsungwallet\",\"youtube\":\"https://www.youtube.com/@samsungwallet\",\"facebook\":\"https://www.facebook.com/samsungwallet\" }",
                    "appLinkName": "Galaxy ticket",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkData": "https://www.applinkdata.com",
                    "bgColor": "#E86D1F",
                    "fontColor": "light",
                    "blinkColor": "#E86D1F",
                    "barcode.value": "serial-0613-001",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "갤럭시 랜드 입장권",
                            "holderName": "김은하",
                            "person1": "{\"person\" : [{\"category\" : \"어른\", \"count\": 1 }]}",
                            "locations": "[{\"lat\": 37.256518, \"lng\": 127.053516, \"address\": \"Samsung-ro Yeongtong-gu, Suwon\", \"name\": \"갤럭시 랜드 센트럴 파크\"}]",
                            "noticeDesc": "{\"count\": 2,\"info\": [{\"title\": \"공지사항 1\",\"content\": [\"설명 1-1\",\"설명 1-2\"]},{\"title\": \"공지사항 2\",\"content\": [\"설명 2-1\"]}]}",
                            "groupInfo1": "어른 1"
                        }
                    }
                ]
            }
        ]
    }
}

Coupon

'Coupon' cards support digitized redeemable voucher.

Coupons in Wallet for various channels can provide alarms before expiration and update usage status.

Wallet card type

Wallet card subtype

coupon

others

Figure 8: Sample UI: Coupon

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title.
e.g., Free coupon.

2

orderId

String (32)

Optional

Unique identifier for an order

3

mainImg

String (256)

Required

URL for the main coupon image.
The file size should not exceed 512 KB.

4

logoImage

String(256)

Optional

Logo image URL to be displayed in the Card item.
The file size should not exceed 256 kB.

5

logoImage.darkUrl

String(256)

Optional

Logo image URL in dark mode.
The file size should not exceed 256 kB.

6

logoImage.lightUrl

String(256)

Optional

Logo image URL in light mode.
The file size should not exceed 256 kB.

7

brandName

String (32)

Optional

Brand name

8

expiry

Long (13)

Required

Expiration date in timestamp format. Issued data is cleaned up after it expires.
Epoch timestamp in milliseconds.

9

issueDate

Long (13)

Required

Issue date.
Epoch timestamp in milliseconds.

10

redeemDate

Long (13)

Optional

Date when the coupon is used.
Epoch timestamp in milliseconds.

11

noticeDesc

String (5000)

Optional

Text of notice.
* HTML is supported.

12

editableYn

String (1)

Required

Flag whether the coupon can be modified.
Either 'Y' or 'N'.

13

deletableYn

String (1)

Required

Flag whether the coupon can be deleted.
Either 'Y' or 'N'.

14

displayRedeemButtonYn

String (1)

Required

Flag whether the use completion button is displayed.
Either 'Y' or 'N'.

15

notificationYn

String (1)

Required

Flag whether a notification related to the coupon is delivered.
Either 'Y' or 'N'.

16

appLinkLogo

String (256)

Required

App link image URL.
The file size should not exceed 256 KB.

17

appLinkName

String (32)

Required

App link name.

18

appLinkData

String (256)

Required

Information about the partner app link.

19

preventCaptureYn

String (1)

Optional

Flag whether this wallet card view prevents screen capture
Either 'Y' or 'N'
* Default: 'N'

20

barcode.value

String (4096)

Conditional

Actual data that is delivered when the barcode/QR code is scanned.

21

barcode.value2

String (4096)

Conditional

The secondary barcode data.
* Required if ptFormat is DUALBARCODE or DUALBARCODESERIAL.

22

barcode.serialType

String (32)

Optional

Presentation type.
e.g.,SERIALNUMBER, BARCODE....
* See Barcode format.

23

barcode.ptFormat

String (32)

Optional

Presentation format.
e.g., BARCODE, QRCODE, SERIAL....
* See Barcode format.

24

barcode.ptSubFormat

String (32)

Optional

Presentation sub-format.
e.g.,CODE_128, QR_CODE....
* See Barcode format.

25

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

26

balance

String(50)

Optional

Initial balance.
This is going to be shown as received.
It is recommended to use a one letter currency symbol.
e.g., $1,000, 1,000P.

27

summaryUrl

String(256)

Optional

Webpage url that show details, such as balance.

28

userMessage

String (256)

Optional

Message to forward.

29

sender

String (64)

Optional

Name of sender.

30

redeemUrl

String (256)

Optional

Link to redeem coupons

Example

{
    "card": {
        "type": "coupon",
        "subType": "others",
        "data": [
            {
                "refId": "ref-230712-0001",
                "createdAt": 1612660039000,
                "updatedAt": 1612660039000,
                "language": "en",
                "attributes": {
                    "title": "Free Coupon",
                    "mainImg": "https://../main.png",
                    "brandName": "Samsung Coupon",
                    "expiry": 1637802725000,
                    "issueDate": 1637457125000,
                    "editableYn": "N",
                    "deletableYn": "N",
                    "displayRedeemButtonYn": "Y",
                    "notificationYn": "Y",
                    "appLinkName": "OO Voucher",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkData": "https://www.oocoupon.com",
                    "barcode.value": "CS16138353212584806754FG1802 ",
                    "barcode.serialType": "BARCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                }
            }
        ]
    }
}

Gift Card

'Gift Card' cards support enrolling prepaid cards also known as gift certificate, gift voucher or gift token.

Links (URLs) to get balance and transactions history in real time is provided in the Partners Portal. If a partner needs to integrate communication between Samsung Wallet server and the partner’s server to support the feature, the partner has to set the links in Partners Portal.

Wallet card type

Wallet card subtype

giftcard

others


Figure 9: Sample UI: Gift card

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title.
e.g., Samsung Gift Card.

2

eventId

String (36)

Optional

If full cancelation of the event occurs, find and process all gift cards with this ID

3

orderId

String (36)

Optional

A unique identifier for an order.

4

subtitle1

String (32)

Optional

The auxiliary field which displays supporting information

5

logoImage

String (256)

Optional

Logo image URL to be displayed in the card item.
The file size should not exceed 256 KB.

6

logoImage.darkUrl

String (256)

Optional

Logo image URL in dark mode.
The file size should not exceed 256 KB.

7

logoImage.lightUrl

String (256)

Optional

Logo image URL in light mode.
The file size should not exceed 256 KB.

8

providerName

String (32)

Required

Gift card provider name

9

user

String (64)

Optional

Name of person who holds the gift card

10

preventCaptureYn

String (1)

Optional

Flag whether this wallet card view prevents screen capture.
Either 'Y' or 'N', the default value is 'N'.

11

startDate

Long (13)

Optional

Start date (Display Start date).
Epoch timestamp in milliseconds.

12

endDate

Long (13)

Optional

End date (Display End date).
Epoch timestamp in milliseconds.

13

locations

String (1024)

Optional

List of locations where the gift card can be used.
* See Location format.

14

noticeDesc

String (5000)

Optional

Text of the notice.
* Long content is allowed.
* See Additional Information format.

15

csInfo

String (512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, or website
* See the example below.

16

appLinkLogo

String (256)

Required

App link image URL.
The file size should not exceed 256 KB.

17

appLinkName

String (32)

Required

App link name

18

appLinkData

String (256)

Required

Information about the partner app link

19

bgImage

String (256)

Optional

URL for card art (background) image.
The recommended size for image resources is 888 x 555 px

20

mainImg

String (256)

Optional

URL for gift card image.
The file size should not exceed 512 KB.

21

bgColor

String (8)

Optional

Color of the card art.
e.g.,#00FFFF.

22

fontColor

String (8)

Optional

Color of the font on the card art.
Acceptable values: dark, light.

23

blinkColor

String (8)

Optional

Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

24

barcode.value

String (4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.

25

barcode.serialType

String (32)

Optional

Presentation type.
e.g., SERIALNUMBER, BARCODE....
*See Barcode format.

26

barcode.ptFormat

String (32)

Optional

Presentation format.
e.g., BARCODE, QRCODE, SERIAL....
*See Barcode format.

27

barcode.ptSubFormat

String (32)

Optional

Presentation sub-format.
e.g., CODE_128, QR_CODE....
* See Barcode format.

28

barcode.pin

String (16)

Optional

PIN to show with a barcode

29

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

30

merchantId

String (36)

Optional

Merchant identifier

31

merchantName

String (32)

Optional

Merchant name to display

32

amount

String (32)

Optional

Initial balance.
This is going to be shown as received.
e.g., $1,000.

33

balance

String (32)

Optional

Remaining balance.
This is going to be shown as received.
e.g., $1,000.

34

summaryUrl

String (256)

Optional

Web url that show details, such as balance or transactions history.

Example

{
    "card": {
        "type": "giftcard",
        "subType": "others",
        "data": [
            {
                "refId": "b3fdc982-28c9-47a3-b02f-d484779698a7",
                "createdAt": 1672574400000,
                "updatedAt": 1672574400000,
                "language": "en",
                "attributes": {
                    "title": "Samsung Gift Card",
                    "eventId": "event-001",
                    "logoImage": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "logoImage.darkUrl": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "providerName": "Samsung Gift Card Provider",
                    "user": "MS. Jane Doe",
                    "noticeDesc": "<ul><li>Gift Card Test</li></ul>",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"webSite\":\"https://www.samsungwallet.com/cs/\" }",
                    "appLinkLogo": "https://play-lh.googleusercontent.com/ZnFa1roZ7hpv9j-jIAcBjmjuDl2x-FnuwTE0OYvbbcwvf5VPzOQQiKBXGK7d-APTvag=w240-h480-rw",
                    "appLinkName": "Gift Card Link",
                    "appLinkData": "https://www.samsung.com/",
                    "bgColor": "#0A1A4F",
                    "fontColor": "light",
                    "blinkColor": "#00FFFF",
                    "barcode.value": "CS16138353212584806754FG1802",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                }
            }
        ]
    }
}

Loyalty

'Loyalty' cards support enrolling loyalty cards also known as membership.

Links (URLs) to get points in real time can be provided in the Partners Portal. If a partner needs to integrate communication between Samsung Wallet server and the partner’s server to support the feature, the partner has to set the links in the Partners Portal.

Wallet card type

Wallet card subtype

loyalty

others


Figure 10: Sample UI: Loyalty

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title.
e.g.,Samsung Loyalty Card.

2

eventId

String (36)

Optional

If full cancelation of the event occurs, find and process all loyalty cards with this ID

3

groupingId

String (36)

Optional

Identifier used to group related cards

4

orderId

String (36)

Optional

A unique identifier for an order

5

subtitle1

String (32)

Optional

The auxiliary field which displays supporting information

6

logoImage

String (256)

Optional

Logo image URL to be displayed in the card item.
The file size should not exceed 256 KB.

7

logoImage.darkUrl

String (256)

Optional

Logo image URL in dark mode.
The file size should not exceed 256 KB.

8

logoImage.lightUrl

String (256)

Optional

Logo image URL in light mode.
The file size should not exceed 256 KB.

9

providerName

String (32)

Required

Loyalty card provider name

10

startDate

Long (13)

Optional

Start date (Display Start date).
Epoch timestamp in milliseconds.

11

endDate

Long (13)

Optional

End date (Display End date).
Epoch timestamp in milliseconds.

12

locations

String (1024)

Optional

List of locations where the card can be used.
* See Location format.

13

noticeDesc

String(5000)

Optional

Text of notice.
*HTML supported

14

csInfo

String (512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, website, facebook, pinterest, x, or instagram
* See the example below.

15

appLinkLogo

String (256)

Required

App link image URL.
The file size should not exceed 256 KB.

16

appLinkName

String (32)

Required

App link name

17

appLinkData

String (256)

Required

Information about the partner app link

18

bgImage

String (256)

Optional

Background image for a card art.
The recommended size for image resources is 888 x 555 px

19

bgColor

String (8)

Optional

Color of the card art.
e.g., #00FFFF.

20

fontColor

String (8)

Optional

Color of the font on the card art.
Acceptable values: dark, light.

21

blinkColor

String (8)

Optional

Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

22

barcode.value

String (4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.

23

barcode.serialType

String (32)

Optional

Presentation type.
e.g., SERIALNUMBER, BARCODE....
* See Barcode format.

24

barcode.ptFormat

String (32)

Optional

Presentation format.
e.g., BARCODE, QRCODE, SERIAL....
* See Barcode format.

25

barcode.ptSubFormat

String (32)

Optional

Presentation sub-format.
e.g., CODE_128, QR_CODE....
*See Barcode format.

26

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

27

merchantId

String (36)

Optional

Merchant identifier

28

merchantName

String (32)

Optional

Merchant name to display

29

amount

String(32)

Optional

Total amount of points or initial balance. This is going to be shown as received.
It is recommended to use a one letter currency symbol.
e.g., $ 1,000, 1,000P

30

balance

String(32)

Optional

Available points or remaining balance.
This is going to be shown as received.
It is recommended to use a one letter currency symbol.
e.g., $ 1,000, 1,000P

31

summaryUrl

String(256)

Optional

Webpage URL that shows details, such as balance or transactions history

Example

{
    "card": {
        "type": "loyalty",
        "subType": "others",
        "data": [
            {
                "refId": "b3fdc982-28c9-47a3-b02f-d484779698a8",
                "createdAt": 1672574400000,
                "updatedAt": 1672574400000,
                "language": "en",
                "attributes": {
                    "title": "Samsung Loyalty Card",
                    "eventId": "event-001",
                    "logoImage": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "logoImage.darkUrl": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "providerName": "Samsung Loyalty Card Provider",
                    "noticeDesc": "<ul><li>Loyalty Card Test</li></ul>",
                    "csInfo": " {\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"website\":\"https://www.samsungwallet.com/cs/\",\"instagram\":\"https://www.instagram.com/samsungwallet\",\"pinterest\":\"https://www.pinterest.com/samsungwallet\",\"x\":\"https://www.twitter.com/samsungwallet\",\"facebook\":\"https://www.facebook.com/samsungwallet\" }",
                    "appLinkLogo": "https://play-lh.googleusercontent.com/ZnFa1roZ7hpv9j-jIAcBjmjuDl2x-FnuwTE0OYvbbcwvf5VPzOQQiKBXGK7d-APTvag=w240-h480-rw",
                    "appLinkName": "Loyalty Card Link",
                    "appLinkData": "https://www.samsung.com/",
                    "bgColor": "#0A1A4F",
                    "barcode.value": "CS16138353212584806754FG1802",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE",
                    "amount": "1,000P",
                    "balance": "500P"
                }
            }
        ]
    }
}

Digital IDs

'Digital ID' cards are used to present identification for employees, students, drivers, guests, etc.

Wallet card type

Wallet card subtype

idcard

employees, nationals, students, drivers, guests, others

-Employees

Figure 11: Sample UI: Digital IDs - Employees

-Nationals

Figure 12: Sample UI: Digital IDs - Nationals

-Students

Figure 13: Sample UI: Digital IDs - Students

-Drivers

Figure 14: Sample UI: Digital IDs - Drivers

Type

Value

Description

attributes.{fields}

1

title

String (32)

Required

Main title of cards
e.g., Commercial Access, Employee badge

2

holderName

String (64)

Required

Name of card holders

3

secondHolderName

String (64)

Optional

Second Name of card holders

4

organization

String (64)

Optional

Organization of card holders belonging
i.e., name of department, division, affiliation, association or team

5

position

String (64)

Optional

Position of card holders

6

identifier

String (64)

Required

Unique ID value

7

idNumber

String(64)

Optional

Representative value for an ID
i.e., ID number, Document number

8

address

String(256)

Optional

Address of card holders

9

placeOfLocation

String (64)

Optional

Place of location associated with the cardholder

10

idPhoto

String(128k)

Optional

Holder’s photo image data encoded Base64
The file size should not be greater than 128 kB

11

idPhoto.format

String (32)

Optional

Image file format
e.g., jpeg, png
* Unsupported image formats may exist

12

idPhoto.status

String (16)

Optional

Status of the data
Allowed value: UNCHANGED

13

document

String(1024k)

Optional

First document of identity

14

document.format

String (32)

Optional

Document format
- Allowed value: pdf, jpeg, png

15

document.status

String (16)

Optional

Status of the data
Allowed value: UNCHANGED

16

issueDate

Long(13)

Required

Issue date
Epoch timestamp in milliseconds

17

birthdate

String(16)

Optional

Date of birth

18

gender

String (16)

Optional

Gender of card holders

19

classification

String(16)

Optional

Classified identity type

20

expiry

Long(13)

Optional

Expiry date in timestamp format Issued data is cleaned up after it expires
Epoch timestamp in milliseconds

21

contacts

String(32)

Optional

Personal contact information such as phone number

22

logoImage

String(256)

Optional

Logo image URL to be displayed in card item
The file size should not exceed 256 kB

23

logoImage.darkUrl

String (256)

Optional

Logo image URL in dark mode
The file size should not exceed 256 kB
* If this value does not exist, logoImage will be substituted

24

logoImage.lightUrl

String(256)

Optional

Logo image URL in light mode
The file size should not exceed 256 kB
* If this value does not exist, logoImage will be substituted

25

logoText

String (16)

Optional

Text as an alternative to logoImage

26

providerName

String(32)

Required

Content provider name

27

issuerName

String(32)

Optional

Place of issue or Issuing authority name

28

extraInfo

String (512)

Optional

Additional information
* See Additional Information format

29

noticeDesc

String (1024)

Optional

Text of the notice
* Long content is allowed
* See Additional Information format

30

csInfo

String (512)

Required

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, or website
* See the example below.

31

privacyModeYn

String(1)

Optional

Whether or not to require user
authentication when using the card Either ‘Y’ or ‘N’
* Default: ‘N’

32

appLinkLogo

String(256)

Optional

App link image URL
The file size should not exceed 256 kB

33

appLinkName

String(32)

Optional

App link name

34

appLinkData

String(256)

Optional

Information about the partner app link

35

locations

String(1024)

Optional

List of locations where the card can be used
* See Location format

36

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

37

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

38

bgColor

String(8)

Optional

Color of the card art Support Hex color code
e.g., #015AAA

39

fontColor

String(8)

Optional

Color of the font on the card art
Allowed value: black, white

40

blinkColor

String(8)

Optional

Color of the blinking effect in the Indicator area
Support Hex color code
e.g., #015AAA

41

preventCaptureYn

String(1)

Optional

Flag whether this wallet card view prevents screen capture
Either 'Y' or 'N'
* Default: 'N'

42

barcode.value

String(4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.

43

barcode.serialType

String(32)

Optional

Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format

44

barcode.ptFormat

String(32)

Optional

Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format

45

barcode.ptSubFormat

String(32)

Optional

Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format

46

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

47

barcode.Interval

String(4)

Optional

Update interval if support for dynamic updates
Epoch timestamp in milliseconds.

48

authentication

String(64)

Optional

Authentication data which meets choose options.
* See Authentication for details

49

provision.data

String(512)

Optional

Elements to complete provisioning
* See Provisioning for details

Example

{
    "card": {
        "type": "idcard",
        "subType": "employees",
        "data": [
            {
                "refId": "IdentityCard-bpo1r3e5-3313-0991-z404-sq12994414u8",
                "createdAt": 1658385817000,
                "updatedAt": 1658385817000,
                "language": "en",
                "attributes": {
                    "title": "Employee ID Card",
                    "holderName": "Kim Samsung",
                    "secondHolderName": " Samsung ",
                    "organization": "Digital Wallet, MX",
                    "position": "Professional",
                    "identifier": "2306070003",
                    "idPhoto": "{base64 encoded image data}",
                    "idPhoto.format": "jpeg",
                    "document": "{base64 encoded pdf data}",
                    "document.format": "pdf",
                    "issueDate": "1658385817000",
                    "expiry": "1765855665000",
                    "logoImage": "https://../logo.png",
                    "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": "dark",
                    "barcode.value": "5728306720836720763017601",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODE",
                    "barcode.ptSubFormat": "QR_CODE",
                    "barcode.interval": "300000",
                    "authentication": "samsung@samsung.com",
                    "provision.data": "{\"appKey\":\"abcdefaei;fadaf=\",\"telno\":\"01012345678\",\"provider\":\"SEC\",\"id\":\"0000000000000000\",\"authKey\":\"a3b7fgj0ea\"}"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "사원증",
                            "holderName": "김삼성",
                            "secondHolderName": "Kim Samsung",
                            "providerName": "삼성전자"
                        }
                    }
                ]
            }
        ]
    }
}

Pay As You Go

'Pay As You Go' card supports a system that pays just before using the cost for the service.

Wallet card type

Wallet card subtype

payasyougo

evcharges, others


Figure 15: Sample UI: Pay As You Go Type

Type

Value

Description

attributes.{fields}

1

title

String(32)

Required

Main title of cards
e.g., Samsung Charge Card.

2

subtitle1

String(32)

Optional

The auxiliary field which displays supporting information.

3

logoImage

String(256)

Optional

Logo image URL to be displayed in the Card item
The file size must not be greater than 256 kB

4

logoImage.darkUrl

String(256)

Optional

Logo image URL in dark mode
The file size should not exceed 256 kB
* If this value does not exist, logoImage will be substituted

5

logoImage.lightUrl

String(256)

Optional

Logo image URL in light mode. The file size must not be greater than 256 kB
* If this value does not exist, logoImage will be substituted

6

providerName

String(32)

Optional

Content provider name

7

holderName

String(64)

Optional

Name of card holders

8

preventCaptureYn

String(1)

Optional

Flag whether this wallet card view prevents screen capture.
Either ‘Y’ or ‘N’, the default value is ‘N’.

9

startDate

Long(13)

Optional

Start date (Display Start date).
Epoch timestamp in milliseconds.

10

endDate

Long(13)

Optional

End date (Display End date).
Epoch timestamp in milliseconds.

11

locations

String(1024)

Optional

List of locations where the card can be used.
* See Location format.

12

noticeDesc

String(5000)

Required

Text of the benefits.
Using data in JSON format converted to escape string
* See Additional Information Information format.

13

csInfo

String(512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, website, youtube, instagram, privacyNotice, or termsAndCondition
* See the example below.

14

appLinkLogo

String(256)

Required

App link image URL.
The file size must not be greater than 256 kB.

15

appLinkName

String(32)

Required

App link name.

16

appLinkData

String(256)

Required

Information about the partner app link.

17

bgImage

String(256)

Optional

URL for card art (background) image.

18

bgColor

String(8)

Optional

Color of the card art.
e.g., #00FFFF.

19

fontColor

String(8)

Optional

Color of the font on the card art.
Supported colors are white or black. (#000000 or #FFFFFF)

20

blinkColor

String(8)

Optional

Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

21

barcode.value

String(4096)

Conditional

Barcode data, serial number.
* Required if serialType isn’t 'None'.

22

barcode.serialType

String(32)

Required

Presentation Type
(Barcode/QR/Serial/None).
* See Barcode format.

23

barcode.ptFormat

String(32)

Conditional

Presentation Format.
* See Barcode format
* Required if serialType isn’t 'None'.

24

barcode.ptSubFormat

String(32)

Conditional

25

barcode.pin

String(16)

Optional

Pin to show with a barcode.

26

identifier

String(64)

Optional

Unique ID Value such as a membership number.

27

grade

String(32)

Optional

Grade Value

28

authentication

String(64)

Optional

Authentication data which meets choose options.
* See Authentication for details

29

provision.data

String(512)

Optional

Elements to complete provisioning
* See Provisioning for details

30

transactions

String(4096)

Optional

Transaction history.
* Long content is allowed.
* See Transactions format.

31

summaryUrl

String(256)

Optional

Webpage url that show details, such as transactions

Example

{
    "card": {
        "type": "payasyougo",
        "subType": "evcharges",
        "data": [
            {
                "refId": "b3fdc982-28c9-47a3-b02f-d484779698a7",
                "createdAt": 1672574400000,
                "updatedAt": 1672574400000,
                "language": "en",
                "attributes": {
                    "title": "EV Charge card",
                    "logoImage": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "logoImage.darkUrl": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "providerName": "EV-SAMSUNG",
                    "holderName": "MS. Jane Doe",
                    "preventCaptureYn": "Y",
                    "endDate": 1772574400000,
                    "noticeDesc": "{\"count\": 2,\"info\": [{\"title\": \"포인트 적립\",\"content\": [\"결제금액 1000원당 포인트가 적립됩니다.\"]},{\"title\": \"포인트 사용방법\",\"content\": [\"적립하신 포인트의 유효기간은 발생일로부터 5년입니다.\",\"유효기간이 지난 포인트는 소멸됩니다.\"]}]}",
                    "csInfo": " {\"call\":\"0000-0000\",\"website\":\"https://www.samsungwallet.com/cs/\",\"instagram\":\"https://www.instagram.com/samsungwallet\",\"youtube\":\"https://www.youtube.com/@samsungwallet\",\"privacyNotice\":\"https://privacy.samsungwallet.com/\",\"termsAndCondition\":\"https://www.samsungwallet.com/tnc\" }",
                    "appLinkLogo": "https://play-lh.googleusercontent.com/ZnFa1roZ7hpv9j-jIAcBjmjuDl2x-FnuwTE0OYvbbcwvf5VPzOQQiKBXGK7d-APTvag=w240-h480-rw",
                    "appLinkName": "EV Charge Link",
                    "appLinkData": "https://www.samsungEV.com/",
                    "bgColor": "#0A1A4F",
                    "fontColor": "#FFFFFF",
                    "blinkColor": "#00FFFF",
                    "barcode.value": "1234000067890000",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE",
                    "barcode.pin": "1234",
                    "identifier": "ev-001",
                    "grade": "Prime",
                    "authentication": "SDAIWEGJHEWOGHEWOIHGEWO",
                    "provision.data": "ASD2HFIH9GWEJDAHGI4UAEWHGEO6WHGO12EWHGOEWAHG1IAWPRIUQ7HG5WEL",
                    "transactions": "{\"transactions\": [{\"date\": \"2023-09-10 12:00:00\",\"description\": \"ev-samsung Suwon\"},{\"date\": \"2023-09-20 18:00:00\",\"description\": \"ev-samsung Gangnam\"}]}"
                }
            }
        ]
    }
}

Generic Card

'Generic Card' is defined for registering various forms of cards that aren't defined as other types. Partners can customize the items on the Generic Card to display by connecting them with card data.

Wallet card type

Wallet card subtype

generic

others


Figure 16: Sample UI: Generic Card Type1
Figure 17: Sample UI: Generic Card Type2
Figure 18: Sample UI: Generic Card Type3

Type

Value

Description

attributes.{fields}

1

title

String(32)

Required

Main title

2

subtitle

String(32)

Optional

The auxiliary field which displays supporting information.

3

providerName

String(32)

Required

Provider name.

4

eventId

String(32)

Optional

Event Identifier

5

groupingId

String(32)

Optional

Identifier used to group related cards.

6

startDate

Long(13)

Required

Start date (Display Start date)
Epoch timestamp in milliseconds.

7

startDate.relativeNotiTime

String(4)

Optional

The relative time from startDate
in minutes to provide a notification to the user
e.g., 5, 10, 15, 30, 60, and up to 2880

8

endDate

Long(13)

Optional

End date (Display End date)
Epoch timestamp in milliseconds.

9

endDate.relativeNotiTime

String(4)

Optional

The relative time from endDate
in minutes to provide a notification to the user
e.g., 5, 10, 15, 30, 60, and up to 2880

10

mainImg

String(256)

Required

URL for main image.
The file size should not exceed 512 kB.

11

logoImage

String(256)

Optional

Logo image URL to be displayed
in card item
The file size should not exceed 256 kB

12

logoImage.darkUrl

String(256)

Optional

Logo image URL in dark mode
The file size should not exceed 256 kB
* If this value does not exist, logoImage will be substituted

13

logoImage.lightUrl

String(256)

Optional

Logo image URL in light mode
The file size should not exceed 256 kB
* If this value does not exist, logoImage will be substituted

14

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

15

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

16

text{i}

String(64)

Optional

Text item
i: 1~15

17

image{i}

String(128k)

Optional

Image item
i: 1~5

18

image{i}.lightUrl

String(256)

Optional

Image item in light mode

19

image{i}.darkUrl

String(256)

Optional

Image item in dark mode

20

image{i}.status

String(16)

Optional

Image item status

21

serial{i}.value

String(4096)

Optional

Actual data that is delivered when the barcode/QR code is scanned.
i: 1~2

22

serial{i}.serialType

String(32)

Optional

Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format

23

serial{i}.ptFormat

String(32)

Optional

Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format

24

serial{i}.ptSubFormat

String(32)

Optional

Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format

25

serial{i}.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

26

noticeDesc

String(1024)

Required

Notice description
* Long content is allowed.
* See Additional Information format.

27

csInfo

String(512)

Optional

Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: calls, emails, or websites

28

providerViewLink

String(512)

Optional

Link to additional information from the provider
* See Links format

29

privacyModeYn

String(1)

Optional

Whether or not to require user
authentication when using the card
Either ‘Y’ or ‘N’
* Default: ‘N’

30

bgColor

String(8)

Optional

Color of the card art.
e.g., #00FFFF.

31

fontColor

String(8)

Optional

Color of the font on the card art
Acceptable values: dark, light

32

blinkColor

String(8)

Optional

Color of the blinking effect
in the Indicator area
e.g., #00FFFF

33

preventCaptureYn

String(1)

Optional

Flag whether this wallet card
view prevents screen capture
Either 'Y' or 'N'
* Default: 'N'

34

noNetworkSupportYn

String(1)

Optional

Sets whether to support to open
the wallet card under 'No Network' Status.
Either 'Y' or 'N'
* Default: 'N'

35

appLinkLogo

String(256)

Required

App link image URL.
The file size should not exceed 256 kB.

36

appLinkName

String(32)

Required

App link name.

37

appLinkData

String(256)

Required

Information about the partner app link.

38

locations

String(1024)

Optional

List of locations where the card can be used.
* See Location format.

Example

{
    "card": {
        "type": "generic",
        "subType": "others",
        "data": [
            {
                "createdAt": 1661745824345,
                "updatedAt": 1661745824345,
                "language": "en",
                "refId": "REFID-012345",
                "attributes": {
                    "title": "Samsung Generic Card",
                    "subtitle": "Personal Members",
                    "providerName": "Samsung",
                    "startDate": 1661751274000,
                    "startDate.utcOffset": "UTC+9",
                    "endDate": 1761778000000,
                    "endDate.utcOffset": "UTC+9",
                    "endDate.relativeNotiTime": "1440",
                    "text1": "13047623",
                    "text2": "Silver",
                    "text3": "Suwon Station Branch",
                    "text4": "031)000-1235",
                    "timestamp1": 1761751274000,
                    "timestamp1.utcOffset": "UTC+9",
                    "mainImg": "https://www.samsung.com/images/main.png",
                    "image1": "https://www.samsung.com/images/image1.png",
                    "image1.darkUrl": "https://www.samsung.com/images/dark.png",
                    "image1.lightUrl": "https://www.samsung.com/images/light.png",
                    "serial1.value": ">1180MM2241B7C 0000000000000298060000000000 0 090870907 ",
                    "serial1.serialType": "QRCODE",
                    "serial1.ptFormat": "QRCODE",
                    "serial1.ptSubFormat": "QR_CODE",
                    "bgColor": "#FF5000",
                    "fontColor": "dark",
                    "noticeDesc": "{\"count\":2,\"info\":[{\"title\":\"NOTICE1\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]},{\"title\":\"NOTICE2\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]}]}",
                    "csInfo": "{\"calls\":[{\"key\":\"Emergency\",\"value\":\"82) 123-4567\"},{\"key\":\"Customer Service\",\"value\":\"82) 123-9876\"}],\"emails\":[{\"key\":\"CS Team\",\"value\":\"cs@atwsample.com\"}],\"websites\":[{\"key\":\"FAQ\",\"value\":\"https://atwhomepage.com/faq\"},{\"key\":\"Support\",\"value\":\"https://atwhomepage.com/support\"}]}",
                    "providerViewLink": "{\"count\":1,\"info\":[{\"link\":\"https://samsung.external.info.link/REFID-012345\",\"type\":\"web\",\"text\":\"See more information\"}]}",
                    "appLinkData": "https://www.samsung.com/",
                    "appLinkLogo": "https://www.samsung.com/logo.png",
                    "appLinkName": "Samsung"
                },
                "localization": [
                    {
                        "language": "ko",
                        "attributes": {
                            "title": "삼성 제네릭 카드",
                            "subtitle": "개인 멤버스",
                            "providerName": "삼성",
                            "text2": "실버 등급",
                            "text3": "수원역점"
                        }
                    }
                ]
            }
        ]
    }
}