Data Structures and Formats

Extended Fields

A list of customisable data fields used to render dynamic content in the card UI or printed representation. Each field consists of a label, value and an optional order that defines the display sequence. If the card type is generic, a type field is also included to map each field to a predefined layout position.

Type

 Description
label

 (Required)
The display name of the field.
value

 (Required)
The actual content shown alongside the label.
type

 (Conditional)
A predefined identifier used to map the field to a specific position in the layout. This field is used only for Generic Card type and must align with layout defined from Partner portal.
order

 (Optional)
Defines the display order of the fields. Lower numbers appear first.

Example

{
  "extendedFields": [
    {
      "label": "Name",
      "value": "Bahadur Bhai",
      "type": "text1",
      "order": 1
    },
    {
      "label": "Role",
      "value": "Graphic Designer",
      "type": "text2",
      "order": 2
    },
    {
      "label": "Contact",
      "value": "+0012349012",
      "type": "text3",
      "order": 3
    },
    {
      "label": "Email",
      "value": "into@email space",
      "type": "text4",
      "order": 4
    },
    {
      "label": "Address",
      "value": "123 Dunny, Lorem ipsum",
      "type": "text5",
      "order": 5
    }
  ]
}

Additional information

Additional information to be delivered to customers can be defined in the following format.

Be careful of the content string length. If an attribute does not allow long content, it is not displayed on the device.

JSON Format

Value

 Description
info[]
Object arrays

 (Required)
Container of information
info[].title
String

 (Required)
Title.
* Need either content or chart.
info[].content[]
String arrays

 (Optional)
Content text
info[].more[]
Object arrays

 (Optional)
The additional information that needs to be checked by pressing the ⓘ button in the contents of the info[].title
info[].more[].title
String

 (Optional)
Title.
* Need either content or chart.
info[].more[].content[]
String arrays

 (Optional)
Content text
info[].chart
Object

 (Optional)
Chart data
info[].chart.headers[]
String arrays

 (Optional)
Header of chart
info[].chart.body[]
Array

 (Required)
Body of chart
info[].chart.metadata[]
String arrays

 (Optional)
Metadata of chart
* Units or additional information of chart

Example

  • Extra information for a boarding pass.
{
  "count": 3,
  "info": [
    {
      "title": "baggageAllowance",
      "content": [
        "15 KG"
      ]
    },
    {
      "title": "boardingPriority",
      "content": [
        "YES"
      ]
    },
    {
      "title": "seatClass",
      "content": [
        "Economy Plus"
      ]
    }
  ]
}
  • Example case of long content being allowed: Movie ticket policy.
{
  "count": 2,
  "info": [
    {
      "title": "REFUNDS AND EXCHANGES",
      "content": [
        "Refunds and exchanges of movie ticket(s) are available in certain limited circumstances.",
        "Movie tickets purchased through the Services include a non-refundable Convenience Fee. Before purchasing your movie ticket(s) we urge you to confirm the title, time, location and quantity of tickets for the movie you wish to see."
      ]
    },
    {
      "title": "CHANGES TO TICKET POLICY",
      "content": [
        "From time to time, we may revise this Ticket Policy. You can determine when this Ticket Policy was last revised by referring to the top of this page. Any changes to this Ticket Policy will become effective upon posting of the revised Ticket Policy on the Internet, accessible through the Services."
      ]
    }
  ]
}
  • Example case of more information included : Reservation-rentalcars
{
  "count": 2,
  "info": [
    {
      "title": "Included",
      "content": [
        "Car Rental Rates LDW-LOSS DAMAGE WAIVER TAX & SURCHARGE"
      ],
      "more": [
        {
          "title": "What's included",
          "content": [
            "Options which is checked --- ",
            "Please note that additional insurance ---"
          ]
        }
      ]
    },
    {
      "title": "Options",
      "content": [
        "N/A"
      ]
    }
  ]
}
  • Example usage of charts
{
  "count": 1,
  "info": [{
      "title": "PAYGO Price guide for usage",
      "chart": {
        "headers": ["Grade", "ROUND", "ONE-WAY"],
        "body": [
          ["Platinum", "$25", "$10"],
          ["Gold", "$30", "$15"],
          ["Silver", "$40", "$20"]
        ],
        "metadata": "Unit : /h"
      }
  }]
}
  • Example usage of html
{
  "count": 2,
  "info": [
    {
      "title": "<b>This is bold text</b>. <font color='red'>This is red text</font>. <a href='https://www.example.com'>This is a link</a>",
      "content": [
        "1. Wear a mask",
        "2. Temperature check before entering the theater",
        "3. Electronic entry registration for all customers using the performance",
        "Please cooperate even if it takes some time before entering.",
        "We kindly ask for your cooperation."
      ]
    },
    {
      "title": "[Parking Information]",
      "content": [
        "<b>This is bold text</b>. <font color='red'>This is red text</font>. <a href='https://www.example.com'>This is a link</a>"
      ]
    }
  ]
}

PAYGO Price guide for usage

Members Grade

 Round

 One-way
Platinum

 $25

 $10
Gold

 $30

 $15
Silver

 $40

 $20
Unit : /h

The above example may differ from what is actually displayed.

Classification

Classification defines different kinds of people who can use the cards.

JSON Format

Value

 Description
person[]
Array of Object

 (Required)
Container of person list who can use the card.
person[].category
String

 (Required)
Category name.
person[].count
String

 (Required)
Number of persons.

Example

  • 3 persons with a ticket
{
  "person": [
    {
      "category": "Adult",
      "count": 2
    },
    {
      "category": "Child",
      "count": 1
    }
  ]
}
  • 1 person with a ticket
{
  "person": [
    {
      "category": "Adult",
      "count": 1
    }
  ]
}

Transactions

Transactions to be delivered to customers can be defined in the following format.
Be careful of the content string length. If an attribute does not allow long content, it will not be displayed on the device.

JSON Format

Value

 Description
[].date
String

 (Required)
Transaction Date.
[].amount
String

 (Optional)
Amount value.
[].description
String

 (Optional)
Description.

Example

  • An example for payasyougo-evcharge-transactions
[
  {
    "date": "2023-09-10 12:00:00",
    "amount": "50,000 WON",
    "description": "Suwon Station Branch"
  },
  {
    "date": "2023-09-20 18:00:00",
    "amount": "70,000 WON",
    "description": "Gangnam Central Branch"
  }
]

Links is a standard data structure that represents a list of actionable links provided by a content provider.

JSON Format

Value

 Description
order
Integer(1~5)

 (Optional)
Display order of the link. Smaller values are displayed first.
If omitted, the array order is used.
Title
String(32)

 (Required)
Primary text shown to the user.
Subtitle
String(32)

 (Optional)
Secondary descriptive text shown below the title.
Link
String(2000)

 (Required)
URL to access the provider’s additional information.
Max 2000 characters (de-facto limit).

Example

{
  "links": [
    {
      "order": 1,
      "title": "Medical consultation",
      "subtitle": "See more information",
      "link": "https://samsung.external.info.link"
    }
  ]
}

Locations

Locations refer to place information that denotes where a card can be used. Using this information, Samsung Wallet can show a map, place name, and address. Additionally, location information can be used to provide Location-Based Services (LBS).

Location information can be represented by a JSON array and up to 10 locations can be specified.

Location information may also be used for Geofence Notification scenarios. In such cases, the partner provides location entries in the locations field of Wallet Card Data (CData), and Samsung Wallet may use additional geofence-related data associated with the location entry to support location-triggered notifications. For more details, see Geofence Notification in the Notification Service chapter.

JSON Format

Value

 Description
[].lat
Double

 (Optional)
Latitude.
[].lng
Double

 (Optional)
Longitude.
[].address
String

 (Required)
String containing the full address.
[].name
String

 (Required)
Branch name.
[].geofenceType
String

 (Required for Geofence Notification)
Geofence radius value for Geofence Notification. Supported values are "100", "200", "300", "400", and "500". Each value indicates the radius in meters.
[].message
String(100)

 (Required for Geofence Notification)
Message associated with the Geofence Notification scenario.

Example

  • Location information for the entrance to Oracle Park
[
  {
    "lat": 37.779337,
    "lng": -122.388755,
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107",
    "name": "Willie Mays Plaza"
  },
  {
    "lat": 37.77814,
    "lng": -122.390836,
    "address": "King St, San Francisco, CA 94107",
    "name": "King St"
  }
]

Itinerary Information

JSON Format

Value

 Description
itineraryInformation[].id
String(32)

 (Optional)
Unique id assigned to each segment of the journey.
itineraryInformation[].order
String(4)

 (Optional)
Order of each segment within the overall itinerary.
itineraryInformation[].providerName
String(32)

 (Conditional)
Provider name.
* Required if subType is etickets.
itineraryInformation[].providerLogo
String(256)

 (Conditional)
URL of the logo image.
* Required if subType is etickets.
itineraryInformation[].providerLogo.darkUrl
String(256)

 (Conditional)
URL of the logo image in dark mode.
* Required if subType is etickets.
itineraryInformation[].providerLogo.lightUrl
String(256)

 (Conditional)
URL of the logo image in light mode.
* Required if subType is etickets.
itineraryInformation[].departure
Object

 (Conditional)
Information about the place of departure.
itineraryInformation[].departure.name
String(32)

 (Conditional)
Name of the departure point.
* Required if subType is etickets
itineraryInformation[].departure.code
String(32)

 (Conditional)
IATA Code for the departure point.
* Required if subType is etickets
itineraryInformation[].departure.airport
String(100)

 (Conditional)
Airport name of the departure point.
* Required if subType is etickets
itineraryInformation[].departure.terminal
String(100)

 (Conditional)
Terminal name of the departure point.
* Required if subType is etickets
itineraryInformation[].departure.platform
String(100)

 (Optional)
Platform name of the departure point.
itineraryInformation[].departure.time
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 etickets.
itineraryInformation[].departure.utcOffset
String(8)

 (Conditional)
UTC offset of time at the departure point.
* Required if subType is etickets.
itineraryInformation[].departure.zoneId
String(64)

 (Optional)
Unique identifier for a time zone as defined by the IANA Time Zone Database. It represents a specific region's time zone, including rules for Daylight Saving Time (DST) and historical changes.
ex) "America/New_York", "Europe/London"
itineraryInformation[].departure.literalValue
String(32)

 (Optional)
Formatted departure time to display on the screen.
format: YYYY-MM-DDThh:mm:ss
ex) 2025-10-30T14:35:00
itineraryInformation[].departure.latitude
Double

 (Optional)
Latitude of the start location.
* Input when timestamp and zoneId information is not known
itineraryInformation[].departure.longitude
Double

 (Optional)
Longitude of the start location.
* Input when timestamp and zoneId information is not known
itineraryInformation[].departure.address
String(256)

 (Optional)
Address of the start location.
* Input when timestamp and zoneId information is not known
itineraryInformation[].arrival
Object

 (Conditional)
Information about the place of arrival.
itineraryInformation[].arrival.name
String(32)

 (Conditional)
Name of the arrival point.
* Required if subType is etickets
itineraryInformation[].arrival.code
String(32)

 (Conditional)
IATA Code for the arrival point.
* Required if subType is etickets
itineraryInformation[].arrival.airport
String(100)

 (Conditional)
Airport name of the arrival point.
* Required if subType is etickets
itineraryInformation[].arrival.terminal
String(100)

 (Conditional)
Terminal name of the arrival point.
* Required if subType is etickets
itineraryInformation[].arrival.platform
String(100)

 (Optional)
Platform name of the arrival point.
itineraryInformation[].arrival.time
Long(13)

 (Conditional)
Arrival 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 etickets
itineraryInformation[].arrival.utcOffset
String(8)

 (Conditional)
UTC offset of time at the arrival point.
* Required if subType is etickets
itineraryInformation[].arrival.zoneId
String(64)

 (Optional)
Unique identifier for a time zone as defined by the IANA Time Zone Database. It represents a specific region's time zone, including rules for Daylight Saving Time (DST) and historical changes.
ex) "America/New_York", "Europe/London"
itineraryInformation[].arrival.literalValue
String(32)

 (Optional)
Formatted arrival time to display on the screen.
format: YYYY-MM-DDThh:mm:ss
ex) 2025-10-30T14:35:00
itineraryInformation[].arrival.latitude
Double

 (Optional)
Latitude of the arrival location.
* Input when timestamp and zoneId information is not known.
itineraryInformation[].arrival.longitude
Double

 (Optional)
Longitude of the arrival location.
* Input when timestamp and zoneId information is not known.
itineraryInformation[].arrival.address
String(256)

 (Optional)
Address of the arrival location.
* Input when timestamp and zoneId information is not known.
itineraryInformation[].boardingTime
Long(13)

 (Optional)
Boarding time.
Epoch timestamp in milliseconds.
itineraryInformation[].vehicleNumber
String(32)

 (Conditional)
Transit or route number
e.g., flight number for an airline
* Required if subType is etickets
itineraryInformation[].coachNumber
String(16)

 (Optional)
Identifier assigned to each individual carriage.
e.g., B4
itineraryInformation[].seatClass
String(32)

 (Conditional)
Seat class.
* Required if subType is etickets
itineraryInformation[].seatNumber
String(16)

 (Optional)
Individual number of the passenger seat.
e.g., A-9, Free
itineraryInformation[].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
itineraryInformation[].baggageAllowance
String(20)

 (Optional)
Baggage allowance.
itineraryInformation[].flightTime
String(8)

 (Optional)
The time required for a flight.
itineraryInformation[].checkInLink
String(256)

 (Optional)
Link to check in.
itineraryInformation[].userType
String(32)

 (Optional)
Passenger type.
e.g., Child or Adult.

Example

{
  "itineraryInformation": [
    {
      "id": "itineraryId",
      "order": 1,
      "departure": {
        "name": "departureName",
        "code": "departureCode",
        "platform": "departurePlatform",
        "time": 1749624040000,
        "utcOffset": "UTC+09:00"
      },
      "arrival": {
        "name": "arrivalName",
        "code": "arrivalCode",
        "platform": "arrivalPlatform",
        "time": 1749624040000,
        "utcOffset": "UTC+09:00"
      },
      "vehicleNumber": "vehicleNumber",
      "coachNumber": "coachNumber",
      "seatClass": "seatClass",
      "seatNumber": "seatNumber",
      "seatFacing": "seatFacing",
      "userType": "userType"
    }
  ]
}

Issuance Status

JSON Format

Value

 Description
issuranceStatus[].ticketNumber
String(256)

 (Optional)
Ticket number
issuranceStatus[].downloadLink
String(32)

 (Optional)
Link for checking the ticket
itineraryInformation[].userType
String(32)

 (Optional)
Passenger type.
e.g., Child or Adult.

 
{
  "card": {
    "type": "reservation",
    "subType": "etickets",
    "data": [
      {
        "refId": "etickets-001",
        "createdAt": 1658385817000,
        "updatedAt": 1658385817000,
        "language": "en",
        "attributes": {
          "title": "Samsung Air",
          "groupingId": "group-001",
          "appLinkLogo": "https://../applinklogo.png",
          "appLinkName": "Samsung Air",
          "appLinkData": "https://www.oohotel.com",
          "mainImg": "https://../logo.png",
          "logoImage": "https://../main.png",
          "logoImage.darkUrl": "https://../logo.png",
          "logoImage.lightUrl": "https://../logo.png",
          "bgColor": "#00FFFF",
          "fontColor": "dark",
          "blinkColor": "#00FFFF",
          "providerName": "OO airline",
          "csInfo": "{\"call\":\"555-123-4567\", \"email\":\"cs@email.com\", \"website\":\"https://homepage.com/cs\"}",
          "startDate": 1735041600000,
          "startDate.zoneId": "Asia/Seoul",
          "endDate": 1735675200000,
          "endDate.zoneId": "Asia/Seoul",
          "noticeDesc": "{\"count\": 2,\"info\": [{\"title\": \"NOTICE 2\",\"content\": [\"DESCRIPTION 1\",\"DESCRIPTION 2\"]},{\"title\": \"NOTICE 2\",\"content\": [\"DESCRIPTION 1\"]}]}",
          "agentName": "Lee",
          "agentContactNumber": "03111112222",
          "reservationNumber": "R123",
          "firstName": "SAMSUNG",
          "lastName": "KIM",
          "fullName": "SAMSUNG KIM",
          "phoneNumber": "+821012345678",
          "membership": "[\"membership1\",\"membership2\"]",
          "organization": "Samsung Electronics",
          "itineraryInformationList": [
            {
              "providerName": "Samsungairline",
              "providerLogo": "https://..logo.png",
              "providerLogo.darkUrl": "https://..logo.png",
              "providerLogo.lightUrl": "https://..logo.png",
              "departure": {
                "name": "Seoul",
                "code": "ICN",
                "airport": "IncheonIntlAirport",
                "terminal": "Terminal2",
                "time": 1735041600000,
                "utcOffset": "UTC+9"
              },
              "arrival": {
                "name": "San Francisco",
                "code": "SFO",
                "airport": "SanFranciscoIntlAirport",
                "terminal": "Terminal1",
                "time": 1735081200000,
                "utcOffset": "UTC+9"
              },
              "boardingTime": 1735038000000,
              "vehicleNumber": "SE123",
              "seatClass": "EconomyPlus",
              "baggageAllowance": "15KG",
              "flightTime": "10h25m",
              "checkInLink": "http://~~"
            },
            {
              "providerName": "Samsungairline",
              "providerLogo": "https://..logo.png",
              "providerLogo.darkUrl": "https://..logo.png",
              "providerLogo.lightUrl": "https://..logo.png",
              "departure": {
                "name": "San Francisco",
                "code": "SFO",
                "airport": "SanFranciscoIntlAirport",
                "terminal": "Terminal1",
                "time": 1735635600000,
                "utcOffset": "UTC+9"
              },
              "arrival": {
                "name": "Seoul",
                "code": "ICN",
                "airport": "IncheonIntlAirport",
                "terminal": "Terminal2",
                "time": 1735675200000,
                "utcOffset": "UTC+9"
              },
              "boardingTime": 1735632000000,
              "vehicleNumber": "SE123",
              "seatClass": "EconomyPlus",
              "baggageAllowance": "15KG",
              "flightTime": "10h25m",
              "checkInLink": "http://~~"
            }
          ],
          "itinerary": "Seoul(ICN)-San Francisco, CA(SFO) San Francisco, CA(SFO)-Seoul(ICN)",
          "passengerNameRecord": "6DDRZE",
          "issuranceStatus": "[{\"ticketNumber\":\"A-9303123959\",\"downloadLink\":\"http://~~~\"},{\"ticketNumber\":\"B-9303123959\",\"downloadLink\":\"http://~~~\"}]"
        }
      }
    ]
  }
}

Card Art Guide

Loyalty

Type

 bgImage + bgColor

 bgImage only
Description

 Display the bgImage and the bgColor in a predefined ratio.

 Display bgImage fully
Example