Wallet Cards

This chapter defines data fields for attributes object by each Wallet card types.

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 Sub Type
boardingpass airlines, trains, buses, ferries, others

- Airlines

Sample UI: Boarding Pass-Airlines
Boarding Pass UI-Attribute mapping: Numbers are matched to attributes below.

- Buses

Sample UI: Boarding Pass-Buses
Boarding Pass UI-Attribute mapping: Numbers are matched to attributes below.

Type Value Description
attributes.{fields} 1 designType String(32) Required Wallet card design type.
2 title String(32) Required Main title.
e.g., 'BOARDING PASS'.

3 transitType String(16) Optional Transit type.
* This will be deprecated

4 groupingId String(32) Optional Identifier used to group related cards.
5 orderId String(32) Optional Unique identifier for an order.
6 providerLogo String(256) Required URL of the logo image.
The file size should not exceed 256 kB.

7 providerLogo.darkUrl String(256) Required URL of the logo image in dark mode.
The file size should not exceed 256 kB.

8 providerLogo.lightUrl String(256) Required URL of the logo image in light mode.
The file size should not exceed 256 kB.

9 providerName String(32) Required Display name of the boarding pass provider.
10 user String(64) Conditional Passenger Name
* Required if subType is airlines

11 userType String(32) Optional Passenger type
i.e., Classification of passengers like Child, Adult

12 transitOperator String(64) Optional Operator name
13 vehicleNumber String(32) Conditional Transit or route number
i.e., Flight number on airlines
* Required if subType is airlines

14 transitClass String(32) Optional Transit class
i.e., Premium class for buses

15 transitFare String(32) Optional General fare or purchase fare
16 coachNumber String(16) Optional Identifier assigned to each individual carriage.
e.g., B4

17 seatClass String(32) Conditional Seat class.
* Required if subType is airlines

18 seatNumber String(16) Required Individual number of the passenger seat.
e.g., A-9, Free

19 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

20 reservationNumber String(32) Required Number of the transit reservation.
21 boardingPriority String(32) Optional Information on whether entitles the passenger to board before others.
i.e., if the passengers are pregnant.

22 boardingSeqNo String(32) Optional Boarding sequence number
23 boardingGroup String(8) Optional Value of boarding group or zone.
e.g., B.

24 boardingTime Long(13) Optional Boarding time.
Epoch timestamp in milliseconds.

25 boardingTime.utcOffset String(8) Conditional UTC offset of boarding time at the departure point.
* Required if boardingTime exist

26 gateClosingTime Long(13) Optional Boarding gate closing time.
Epoch timestamp in milliseconds.

27 gateClosingTime.utcOffset String(8) Conditional UTC offset of gate closing time at the departure point.
* Required if gateClosingTime exist

28 baggageAllowance String(16) Optional Baggage allowance.
29 departName String(32) Conditional Name of the departure point.
* Required if subType is airlines

30 departCode String(8) Conditional Code for the departure point.
* Required if subType is airlines

31 departTerminal String(8) Conditional Terminal name of the departure point.
* Required if subType is airlines

32 departGate String(8) Optional Gate name of the departure point.
33 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

34 estimatedOrActualStartDate. utcOffset String(8) Conditional UTC offset of time at the departure point.
* Required if estimatedOrActualStartDate exist

35 arriveName String(32) Conditional Name of the arrival point.
* Required if subType is airlines

36 arriveCode String(8) Conditional Code for the arrival point.
* Required if subType is airlines

37 arriveTerminal String(8) Optional Terminal name of the arrival point.
38 arriveGate String(8) Optional Gate name of the arrival point.
39 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

40 estimatedOrActualEndDate. utcOffset String(8) Conditional UTC offset of time at the arrival point.
* Required if estimatedOrActualEndDate exist

41 locations String(1024) Optional List of locations where the card can be used.
* See Location format.

42 bgColor String(8) Required Color of the card art.
e.g., #00FFFF.

43 fontColor String(8) Optional Color of the font on the card art Acceptable values: dark, light.
44 blinkColor String(8) Optional Color of the blinking effect in the Indicator area.
e.g., #00FFFF.

45 appLinkLogo String(256) Required App link image URL. The file size should not exceed 256 kB.
46 appLinkName String(32) Required App link name.
47 appLinkData String(256) Required Information about the partner app link.
48 extraInfo String(512) Optional Additional information to be delivered to customers.
* See Additional Information format.

49 noticeDesc String(1024) Optional Text of the notice.
* Long content is allowed.
* See Additional Information format.

50 csInfo String(512) Optional Set value to JSON Object (call or email or website)
* See the below example

51 displayTSAPreCheckYn String(1) Optional Flag whether to display the TSA PreCheck image. Either ‘Y’ or ‘N’.
Image size: 68x20 / 140x20

52 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

53 barcode.value String(4296) Optional Barcode data, serial number.
54 barcode.serialType String(32) Optional Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

55 barcode.ptFormat String(32) Optional Presentation Format.
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

56 barcode.ptSubFormat String(32) Optional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

57 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+9",
                    "baggageAllowance": "15KG",
                    "departName": "SEOUL/INCHEON",
                    "departCode": "INC",
                    "departTerminal": "C",
                    "departGate": "1",
"estimatedOrActualStartDate": 1612660039000,
"estimatedOrActualStartDate.utcOffset": "UTC+9",
                    "arriveName": "SAN FRANCISCO",
                    "arriveCode": "SFO",
                    "arriveTerminal": "A",
                    "arriveGate": "11",
                    "estimatedOrActualEndDate": 1612660039000,
"estimatedOrActualEndDate.utcOffset": "UTC-8",
                    "bgColor": "#FF00FF",
                    "fontColor": "dark",
                    "appLinkLogo": "https://../applinklogo.png",
                    "appLinkName": "OO Airline",
                    "appLinkData": "https://www.ooairline.com",
                    "csInfo": "{\"call\":\"555) 123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.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\":\"555) 123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.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\":\"555) 123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.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 Sub Type
ticket performances, sports, movies, entrances, others

- Movies

Sample UI: Ticket-Movies
Ticket UI-Attribute mapping: Numbers are matched to attributes below.

- Sports

Sample UI: Ticket-Sports
Ticket UI-Attribute mapping: Numbers are matched to attributes below.

- Entrances

Sample UI: Ticket-Entrances
Ticket UI-Attribute mapping: Numbers are matched to attributes below.

Type Value Description
attributes.{fields} 1 designType String(32) Required Wallet card design type.
2 title String(32) Required Main title.
e.g., MLB Ticket.

3 category String(16) Optional Ticket category
* This will be deprecated

4 eventId String(32) Optional If full cancelation of the event occurs, find and process all tickets with this ID.
5 groupingId String(32) Optional Identifier used to group related cards.
6 orderId String(32) Optional A unique identifier for an order.
7 mainImg String(256) Required URL for main ticket image.
The file size should not exceed 512 kB.

8 subtitle1 String(32) Optional The auxiliary field which displays supporting information.
9 logoImage String(256) Required Logo image URL to be displayed in the Card item.
The file size should not exceed 256 kB.

10 logoImage.darkUrl String(256) Required Logo image URL in dark mode.
The file size should not exceed 256 kB.

11 logoImage.lightUrl String(256) Required Logo image URL in light mode.
The file size should not exceed 256 kB.

12 providerName String(32) Required Ticket provider name.
13 classification String(16) Optional Classifications of tickets
Use ONETIME or REGULAR or ANNUAL
* Default: ONETIME.

14 holderName String(64) Optional Name of card holders.
15 idPhoto String(200000) Optional Holder’s photo image data encoded Base64.
16 idPhoto.format String(32) Optional Image file format
i.e., jpeg, png
* Unsupported image formats may exist.

17 grade String(32) Optional Ticket grade.
18 seatClass String(32) Optional Seat class.
19 entrance String(64) Optional Entrance gate.
20 seatNumber String(256) Optional Seat location.
21 seatLayoutImage String(256) Optional URL of the seat layout image.
The file size should not exceed 512 kB.

22 issueDate Long(13) Required Issue date. Epoch timestamp in milliseconds.
23 reservationNumber String(32) Required Reservation number.
24 user String(64) Optional Name of person who made the reservation.
25 certification String(16) Optional Ticket certification.
e.g., R as a film rating.

26 reactivatableYn String(1) Optional Flag whether the card is able to activate an expired ticket temporarily.
Either ‘Y’ or ‘N’
* Default: N

27 preventCaptureYn String(1) Optional Flag whether this wallet card view prevents screen capture.
Either ‘Y’ or ‘N’
* Default: N

28 noNetworkSupportYn String(1) Optional Sets whether to support to open the wallet card under 'No Network' Status.
Either 'Y' or 'N'
* Default: 'N'

29 startDate Long(13) Required Start date (Display Start date).
Epoch timestamp in milliseconds.

30 endDate Long(13) Optional End date (Display End date).
Epoch timestamp in milliseconds.
* If null, the card will expired in 10 hours from startDate

31 person1 String(512) Optional Number of persons by category.
* See Classification format.

32 locations String(1024) Optional List of locations where the card can be used.
* See Location format.

33 noticeDesc String(1024) Required Text of the notice.
* Long content is allowed.
* See Additional Information format.

34 groupInfo1 String(64) Optional The first common information with the same groupingId.
35 groupInfo2 String(64) Optional The second common information with the same groupingId.
*It is recommended to set groupInfo1 first.

36 groupInfo3 String(64) Optional The third common information with the same groupingId.
*It is recommended to set groupInfo1, groupInfo2 first.

37 csInfo String(512) Optional Partners’ customer service Information
Set value to JSON Object. (call, email, website, sns).
*See the example below

38 appLinkLogo String(256) Required App link image URL.
The file size should not exceed 256 kB.

39 appLinkName String(32) Required App link name.
40 appLinkData String(256) Required Information about the partner app link.
41 bgColor String(8) Optional 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) Required Color of the blinking effect in the Indicator area.
e.g., #00FFFF.

44 barcode.value String(4296) Optional Barcode data, serial number.
45 barcode.serialType String(32) Optional Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

46 barcode.ptFormat String(32) Optional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

47 barcode.ptSubFormat String(32) Optional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

48 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

If coupons are provided together. Samsung Wallet can show up to two coupons per ticket.

49 relCoupon1.title String(32) Conditional 1st coupon title.
* Required if this ticket has a related coupon

50 relCoupon1.subtitle String(32) Optional 1st coupon subtitle.
51 relCoupon1.providerName String(32) Conditional 1st coupon provider name.
* Required if this ticket has a related coupon

52 relCoupon1.imageFileSrc String(256) Optional 1st coupon image URL.
The file size should not exceed 256 kB.

53 relCoupon1.noticeDescription String(1024) Optional Text of the notice.
* Long content is allowed.
* See Additional Information format.

54 relCoupon1.notificationTime Long(13) Optional Coupon exposure time.
Epoch timestamp in milliseconds.

55 relCoupon1.value String(4296) Conditional Barcode data, serial number.
56 relCoupon1.serialType String(32) Required Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

57 relCoupon1.ptFormat String(32) Conditional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

58 relCoupon1.ptSubFormat String(32) Conditional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

59 relCoupon1.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

60 relCoupon2.title String(32) Conditional 2nd coupon title.
* Required if this ticket has a related 2nd coupon

61 relCoupon2.subtitle String(32) Optional 2nd coupon subtitle
62 relCoupon2.providerName String(32) Conditional 2nd coupon provider name.
* Required if this ticket has a related 2nd coupon

63 relCoupon2.imageFileSrc String(256) Optional 2nd coupon image URL.
The file size should not exceed 256 kB.

64 relCoupon2.noticeDescription String(1024) Optional Text of the notice.
* Long content is allowed.
* See Additional Information format.

65 relCoupon2.notificationTime Long(13) Optional Coupon exposure time.
Epoch timestamp in milliseconds.

66 relCoupon2.value String(4296) Conditional Barcode data, serial number.
67 relCoupon2.serialType String(32) Required Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

68 relCoupon2.ptFormat String(32) Conditional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

69 relCoupon2.ptSubFormat String(32) Conditional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

70 relCoupon2.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

{
       "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\":\"555) 123-4567\",\"email\":\"cs@email.com\",\"website\":\"https://homepage.com/cs\",\"facebook\":\"https://facebook.com/cs\",\"instagram\":\"https://instagram.com/cs\",\"youtube\":\"https://youtube.com/cs\"}",
                "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": "BARCODE",
                "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 Sub Type
coupon others

Sample UI: Coupon
Coupon UI-Attribute mapping: Numbers are matched to attributes below.

Type Value Description
attributes.{fields} 1 designType String(32) Required Wallet card design type.
2 title String(32) Required Main title.
e.g., Free coupon.

3 orderId String(32) Optional Unique identifier for an order.
4 mainImg String(256) Required URL for the main coupon image.
The file size should not exceed 512 kB.

5 brandName String(32) Optional Brand name.
6 expiry Long(13) Required Expiry date in timestamp format. Issued data is cleaned up after it expires.
Epoch timestamp in milliseconds.

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

8 redeemDate Long(13) Optional Date when the coupon is used.
Epoch timestamp in milliseconds.

9 noticeDesc String(1024) Optional Text of notice.
* HTML supported

10 editableYn String(1) Required Flag whether the coupon can be modified. Either ‘Y’ or ‘N’.
11 deletableYn String(1) Required Flag whether the coupon can be deleted. Either ‘Y’ or ‘N’.
12 displayRedeemButtonYn String(1) Required Flag whether the use completion button is displayed.
Either ‘Y’ or ‘N’.

13 notificationYn String(1) Required Flag whether a notification related to the coupon is delivered.
Either ‘Y’ or ‘N’.

14 appLinkLogo String(256) Required App link image URL.
The file size should not exceed 256 kB.

15 appLinkName String(32) Required App link name.
16 appLinkData String(256) Required Information about the partner app link.
17 bannerImage String(256) Optional Image URL for banner provision
Must be below 512kB in size.
*Aspect ratio - 2.85:1
*Ideal size - 1080x379

18 bannerLink String(256) Optional URL linked to bannerImage
19 barcode.value String(4296) Conditional Barcode data, serial number.
* Required if serialType isn’t 'None'.

20 barcode.value2 String(4296) Conditional The secondary barcode data.
* Required if ptFormat is DUALBARCODE or DUALBARCODESERIAL

21 barcode.serialType String(32) Optional Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

22 barcode.ptFormat String(32) Optional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

23 barcode.ptSubFormat String(32) Optional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

24 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

25 balance String 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,000 P

26 summaryUrl String Optional Webpage url that show details, such as balance

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",
                "bannerImage": "https://../banners/ref-230712-0001/image.jpg",
                "bannerLink": "https://../banners/ref-230712-0001/link",
                "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 Partner 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 Partner portal.

Wallet Card Type Wallet Card Sub Type
giftcard others

Sample UI: Giftcard
Giftcard UI-Attribute mapping: Numbers are matched to attributes below.

Type Value Description
attributes.{fields} 1 designType String(32) Required Wallet card design type.
2 title String(32) Required Main title.
e.g., ‘Samsung Gift Card’.

3 eventId String(36) Optional If full cancelation of the event occurs, find and process all gift cards with this ID.
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 Gift Card provider name.
10 user String(64) Optional Name of person who holds the gift card.
11 preventCaptureYn String(1) Optional Flag whether this wallet card view prevents screen capture.
Either ‘Y’ or ‘N’, the default value is ‘N’.

12 startDate Long(13) Optional Start date (Display Start date).
Epoch timestamp in milliseconds.

13 endDate Long(13) Optional End date (Display End date).
Epoch timestamp in milliseconds.

14 locations String(1024) Optional List of locations where the card can be used.
* See Location format.

15 noticeDesc String(1024) Optional Text of the notice.
* Long content is allowed.
* See Additional Information format.

16 csInfo String(512) Optional Set value to JSON Object.
(call, email, website).
* See the example below.

17 appLinkLogo String(256) Required App link image URL.
The file size should not exceed 256 kB.

18 appLinkName String(32) Required App link name.
19 appLinkData String(256) Required Information about the partner app link.
20 bgImage String(256) Optional URL for card art (background) image.
21 mainImg String(256) Optional URL for gift card image.
The file size should not exceed 512 kB.

22 bgColor String(8) Optional Color of the card art.
e.g., #00FFFF.

23 fontColor String(8) Optional Color of the font on the card art.
Acceptable values: dark, light.

24 blinkColor String(8) Optional Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

25 barcode.value String(4296) Optional Barcode data, serial number.
26 barcode.serialType String(32) Optional Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

27 barcode.ptFormat String(32) Optional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

28 barcode.ptSubFormat String(32) Optional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

29 barcode.pin String(16) Optional Pin to show with a barcode.
30 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

31 merchantId String(36) Optional Merchant Identifier.
32 merchantName String(32) Optional Merchant Name to display.
33 amount String(50) Optional Initial balance.
This is going to be shown as received.
e.g., $ 1,000

34 balance String(50) Optional Remainin balance.
This is going to be shown as received.
e.g., $ 1,000

35 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\":\"555) 123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.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 Partner 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 Partner portal.

Wallet Card Type Wallet Card Sub Type
loyalty others

Sample UI: Loyalty
Loyalty UI-Attribute mapping: Numbers are matched to attributes below.

Type Value Description
attributes.{fields} 1 designType String(32) Required Wallet card design type.
2 title String(32) Required Main title.
e.g., ‘Samsung Loyalty Card’.

3 eventId String(36) Optional If full cancelation of the event occurs, find and process all loyalty cards with this ID.
4 groupingId String(36) Optional Identifier used to group related cards.
5 orderId String(36) Optional A unique identifier for an order.
6 mainImg String(256) Optional URL for main loyalty card 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) Optional Logo image URL to be displayed in the Card item. The file size should not exceed 256 kB.
9 logoImage.darkUrl String(256) Optional Logo image URL in dark mode.
The file size should not exceed 256 kB.

10 logoImage.lightUrl String(256) Optional Logo image URL in light mode.
The file size should not exceed 256 kB.

11 providerName String(32) Required Loyalty Card provider name.
12 preventCaptureYn String(1) Optional Flag whether this wallet card view prevents screen capture.
Either ‘Y’ or ‘N’, the default value is ‘N’.

13 startDate Long(13) Optional Start date (Display Start date).
Epoch timestamp in milliseconds.

14 endDate Long(13) Optional End date (Display End date).
Epoch timestamp in milliseconds.

15 locations String(1024) Optional List of locations where the card can be used.
* See Location format.

16 noticeDesc String(1024) Optional Text of the notice.
* Long content is allowed.
* See Additional Information format.

17 csInfo String(512) Optional Set value to JSON Object.
(call, email, website).
* See the example below.

18 appLinkLogo String(256) Required App link image URL.
The file size should not exceed 256 kB.

19 appLinkName String(32) Required App link name.
20 appLinkData String(256) Required Information about the partner app link.
21 bgImage String(256) Optional Background image for a card art.
22 bgColor String(8) Optional Color of the card art.
e.g., #00FFFF.

23 fontColor String(8) Optional Color of the font on the card art
Acceptable values: dark, light.

24 blinkColor String(8) Optional Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.

25 barcode.value String(4296) Optional Barcode data, serial number.
26 barcode.serialType String(32) Optional Presentation Type
e.g., SERIALNUMBER, BARCODE, ...
* See Barcode format.

27 barcode.ptFormat String(32) Optional Presentation Format
e.g., BARCODE, QRCODE, SERIAL, ...
* See Barcode format.

28 barcode.ptSubFormat String(32) Optional Presentation Sub-format
e.g., CODE_128, QR_CODE, ...
* See Barcode format.

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 Optional Initial balance.
This is going to be shown as received.
e.g., $ 1,000

33 balance String 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,000 P

34 summaryUrl String Optional Webpage url that show 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\":\"555) 123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.com/cs\"}",
          "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"
        }
      }
    ]
  }
}