References

Barcodes

Presentation Type and Formats

The barcode display type defines how a serial number, barcode, and/or QR code is shown.

Presentation Types (serialType)

Code name

Description

SERIALNUMBER

Serial Number

BARCODE

Barcode

QRCODE

QR code

Presentation Formats (ptFormat)

Code name

Description

BARCODE

Barcode only

BARCODESERIAL

Barcode with serial number

SERIAL

Serial number only

DUALSERIAL

Dual serial number

DUALBARCODE

Dual barcode

DUALBARCODESERIAL

Dual barcode for each serial numbers

BARCODEPIN

Barcode with PIN

QRCODE

QR code only

QRCODESERIAL

QR code with serial number

Barcode Formats (ptSubFormat)

Below are commonly used barcode formats, supported by the ZXing barcode scanning library.

Code name

Description

APIAZTEC

Aztec 2D barcode format

CODABAR

CODABAR 1D format

CODE_39

Code 39 1D format

CODE_93

Code 93 1D format

CODE_128

Code 128 1D format

DATA_MATRIX

Data Matrix 2D barcode format

EAN_8

EAN-8 1D format

EAN_13

EAN-13 1D format

ITF

ITF (Interleaved Two of Five) 1D format

MAXICODE

MaxiCode 2D barcode format

PDF_417

PDF417 format

QR_CODE

QR Code 2D barcode format

RSS_14

RSS 14

RSS_EXPANDED

RSS EXPANDED

UPC_A

UPC-A 1D format

UPC_E

UPC-E 1D format

UPC_EAN_EXTENSION

UPC/EAN extension format. Not a stand-alone format.

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.

  • Notice: Map services are only available in certain countries.

JSON Format

Key

Type

Requirement

Description

[].lat

Double

Optional

Latitude

[].lng

Double

Optional

Longitude

[].address

String

Required

String containing the full address

[].name

String

Required

Branch name

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"
    }
]

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.

Figure 1: Sample: noticeDesc

JSON Format

Key

Type

Requirement

Description

count

Integer

Required

Size of information

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[].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": "Baggage Allowance",
            "content": [
                "15 KG"
            ]
        },
        {
            "title": "Boarding Priority",
            "content": [
                "YES"
            ]
        },
        {
            "title": "Seat Class",
            "content": [
                "Economy Plus"
            ]
        }
    ]
}

* An 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 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"
        }
    }]
}

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.

Linkable data which provides additional information in the following format.

JSON Format

Key

Type

Requirement

Description

count

Integer

Required

Size of links

info[]

Array of Objects

Required

Container of links

info[].link

String

Required

Link URL

info[].type

String

Required

View type that will run the link
* Allowed values: web, app, browser

info[].text

String

Optional

Text of the link

Example

{
	"count": 1,
	"info": [{
		"link": "https://samsung.external.info.link",
		"type": "web",
		"text": "See more information"
	}]
}

Classification

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

JSON Format

Key

Type

Requirement

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 person

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

Key

Type

Requirement

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"
    }
]

Authentication

Defines the data format to authenticate the user registering/updating the card.
If need a custom user verification process, please get in touch with us via Tech Support.

Authentication Data Set

Case

Type

Value

Description

Connecting Information

ci

User’s CI Value

Identifier of Identity Verification Agency

Samsung Account

sa

User’s Samsung Account

Verifying that the signed-in Samsung account on the user's Galaxy device matches.

Subscriber Identity Module

sim

Sim card information on mobile telephone devices

Verify the SIM information being used on the user's mobile phone.

One-Time Password

otp

Dynamic Password

The temporary password provided by the partner to the user is verified by receiving user input during the Add to Samsung Wallet process.

Access Token

token

Token to verify data retrieval request

Token data included in card data is used as a key accessed when querying a partner server. This tokenized key can be reissued when the partner delivers updated card data.

Example

Type

Sample Data

ci

{
"ci": "HSD0IUF9BEW8UGB7WQEU6I"
}

sa

{
"account": "samsungwallet@samsung.com"
}

sim

[{
"uiccId":"ABCDERWYT",
"telno":"821012345678",
"isPrimary": true
},{
"uiccId":"ABCDERWYS",
"telno":"01012345679",
"isPrimary": false
}]

otp

{
"otp": "947253"
}

token

{
"x-access-token": "7C8D38690D0E3B6AA077198ABD2554A3A7940B52CF86BD690C1"
}

Provisioning

Defines access control data for service providers to configure additional features with user's card.

JSON Format

Key

Type

Requirement

Description

provision.feature

String

Required

A specified feature defined in Wallet Card.
* When setting up a Wallet Card, prior selection or consultation is required.
* Use the value selected when setting up your Wallet Card in the Partner Portal.

provision.type

String

Required

A provisioning type defined in Wallet Card.
* When setting up a Wallet Card, prior selection or consultation is required.
* Use the value selected when setting up your Wallet Card in the Partner Portal.

provision.module

String

Required

A Module defined to use in provisioning process in Wallet Card.
* Use the value selected when setting up your Wallet Card in the Partner Portal.

provision.identifier

String

Optional

A identifier intended to be used in provisioning process.
* Suggestion: {package-name}, {applicationId}, {library}, {promised-identifier}

provision.data

String

Optional

Actual data to be used during the feature provisioning. Promised data fields or format to be passed to the module.
* JSON format must be converted to escape string.

Provision Features (feature)

Attribute Name

Description

NFC

NFC communication feature with designated protocol

Provision Types (type)

Attribute Name

Description

SDK

Service Provider Protocol providing SDK

MESSAGE

Message in a promised format is utilized to convey identifiers, credentials, or any sort of dataset.

Provision Modules (module)

Attribute Name

Description

eSE

Embedded Secure Element in mobile devices to provide security features.
Samsung Wallet App or any authorized agent with access rights can manage the secure element using this corresponding module.
To utilize this corresponding module, the applet to be installed on this module must be provided beforehand, and obtaining authorization for SSD creation and access control might be required. For more detailed requirements, please refer to our technical inquiry.

SE-USIM

Universal Subscriber Identity Module (USIM) functions as a secure data repository, storing essential information including user profiles, contact lists, text messages, and application data. Utilizing advanced security measures like PIN codes and cryptography, the USIM guarantees the integrity and confidentiality of all stored data. Furthermore, it empowers users to securely access network services and authenticate their identities during financial transactions or when handling sensitive information. Consequently, the USIM operates as a trustworthy platform for managing sensitive data and enabling secure communications between users and service providers. However, to utilize this module, an additional Software Development Kit (SDK) may be required for seamless integration and access.

APP

Samsung Wallet Application handles access control data.

Example

  • 'data' field needs to be mutually negotiated with Samsung Wallet team.
Case

feature

type

module

identifier

data

Partner provides APDU bundle for eSE

NFC

MESSAGE

eSE

partner-apdu-01

{
"accessKey":"abcdefg","apdus":"{apdu-bundle}"
}

Partner provides SDK for eSE

NFC

SDK

eSE

partner-sdk-ese-01

{
"appPackageName":"com.partner.wallet","appKey":"abcdefaei;fadaf=","refId":"virehgqerurt932m125215","provider":"SEC","deviceId":"0000000000000000","authcode":"43jkl6h3l4"
}

Partner provides SDK for USIM

NFC

SDK

SE-USIM

partner-sdk-usim-01

{
"appPackageName":"com.partner.wallet","appKey":"abcdefaei;fadaf=","refId":"virehgqerurt932m125215","provider":"KT","msisdn":"01012345678","deviceId":"0000000000000000","authcode":"43jkl6h3l4"
}

Partner provides credential that meet a specific protocol

NFC

MESSAGE

APP

partner-protocol-app-01

{
"publicKey":"{publicKey}","message":"{message}"
}

Partner provides credential that meet a specific protocol for eSE

NFC

MESSAGE

eSE

partner-protocol-ese-01

{
"accessKey":"abcdefg","publicKey":"{publicKey}","message":"{message}"
}

NFC feature using Message on APP

NFC

message

app

com.samsung.wallet.applet

{
"format":"ndef","publicKey":"{publicKey}","message":"{message}"
}

Check Service Available Devices

Check Samsung Pay/Wallet service availability for the devices and countries.

Request

Type

Value

Description

Method

GET

URL

https://api-us3.mpay.samsung.com/wallet/cmn/v2.0/device/available

Header

partnerCode

String

Required

Partner Code.
* Partner Code or ID from Samsung Pay Partner System.

Query parameters

modelName

String

Required

Device model name
Ex) SM-G925K, SM-R730T

serviceType

String

Required

Service type
- WALLET : Samsung Wallet

Example

Response

Type

Value

Description

body

resultCode

String

Required

Result code

resultMessage

String

Required

Result message

available

boolean

Required

Service availability

supportKR

boolean

Required

KR service support for the device

Example (Success)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: xx
{
  "resultCode" : "0",
  "resultMessage" : "SUCCESS",
  "available": "true",
  "supportKR": "true"
}

Example (Error)

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: xx
{
  "resultCode" : " CMN5N9001",
  "resultMessage" : " Internal Server Error"
}

Response

HTTP code

Status code

Description

200

0

Success

400

CMN1N1001

Missing requisite parameter from API request – {0}

400

CMN1N1002

Invalid parameter from API request – {0}

400

CMN1N1003

Invalid parameter length from API request – {0}

400

CMN2N2007

Invalid country code

500

CMN4N8003

DB connection failed

Security Factors

Service Flow

Figure 2: Data security flow

How to Generate Key Factors

OpenSSL is an open-source command-line tool that allows you to perform various SSL-related tasks. This section explains how to create key factors for security with OpenSSL.

Private Key

A private key enables encryption and is the most important component of certificates.

openssl genpkey -out domain.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048

If you want to make it more secure, adding "-des3" on the command will encrypt with password.

Certificate Signing Request (CSR)

Certificate Signing Request (CSR) is a necessary factor to get a signed certificate. The CSR includes the public key and some additional information, such as organization and country.
Let's create a CSR (domain.csr) from the existing private key.

openssl req -out domain.csr -key domain.key -new -sha256

Enter the CSR information to complete the process. The output will look like the following:

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:KR
State or Province Name (full name) []:Seoul
Locality Name (eg, city) [Default City]:Sample City
Organization Name (eg, company) [Default Company Ltd]:Sample Company
Organizational Unit Name (eg, section) []:Sample section
Common Name (eg, your name or your server's hostname) []:domain
Email Address []:email@email.com

Please enter the following 'extra'attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
  • ‘password’ is an optional attribute.
  • The ‘Common Name’ field is important, as it needs to exactly match the Fully Qualified Domain Name (FQDN) of our domain.

For more information, refer to https://www.openssl.org.

Card images

Loyalty Description

Type

bgImage + bgColor

bgImage only

Description

Display the bgImage and the bgColor in a predefined ratio.

Display bgImage fully

Description

Contact Points

[Dev Team]

Name

Address

Wallet technical support

https://developer.samsung.com/dashboard/support