Add to Samsung Wallet

'Add to Samsung Wallet' service also known as ATW, defines interfaces for users to conveniently add digital contents to Samsung Wallet.

Service flow

Figure 1: Add to Samsung Wallet

Data Transmit Link

The most common and straightforward method is the Data Transmit Link approach, which securely includes tokenized data in the ATW link. The ATW link format for this method is as follows.

  • The name Data Transmit Link has been changed from Typical flow.
Type

Value

Description

URL

https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}

Path parameters

cardId

String

Required

Wallet card identifier issued from Partner portal when the partner manager signs up for partner services and registers the wallet card they want to service.

Hash path parameters

#Clip

String

Required

Parameters for the Hash link
* The first letter is capitalized

Query parameters

cdata

String

Required

Actual payload data in basic JSON format to communicate between partners and Samsung Wallet.
This must be secured in JWT(JSON Web Token) format.
* Refer to Security for more details.

Example

https://a.swallet.link/atw/v3/1656147182764415319#Clip?cdata=eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0ZWQgdGltZSIsInBhcnRuZXJJRCI6InBhcnRuZXIgSUQifQ.
… … … …
Dn0_oZ3xcr0JuQ3mlSzLIUTxFoTewnZ0MQj7kiNjysNm5Xfwqt5vcN20PeebeLgUx8VJXLy4_9G4BHQ-hd4O9POYuTuAWew.YzdlMTFhO -NYCeL3T0YzNzAD2KcK_HrtwIGEErHLGn6ydaq_fpFdSlxsA3ZJtNpg3wcuqEw5cIdpbPFswbQLropqEpNawg5nlm3DKAA4a1dzaZMbSR1BGZHrH_vIKnx3CY5MO0jNBexl_YIZ5_wB379UYSwumQiPiTZVg2IjYvfht17I4

Data Fetch Link

In cases involving sensitive data or when providing static links, Data Fetch Link method is highly recommended. Links using this approach include only a unique reference ID, and Wallet Cards are added by querying data through Get Card Data path as specified in Partner portal.
The name Data Fetch Link has been changed from Slim data flow.

  • Please be aware that if the link is exposed to unintended users, it can be exploited. Please prepare the integration with this in mind.
  • It is crucial to ensure that the refId, used for a reference value, is generated in a manner that is not easily deducible by potential attackers.
Type

Value

Description

URL

https://a.swallet.link/atw/v3/{CertificateId}/{cardId}#Clip?pdata={pdata}

Path parameters

certificateId

String

Required

Certificate identifier based on a CSR during onboarding.
4 digits alphanumeric.
* Must be generated from Partner Portal

cardId

String

Required

Wallet card identifier.
* It must be generated from Partners Portal.

Hash path parameters

#Clip

String

Required

Parameters for the Hash link

Query parameter

pdata

String

Required

Unique ID defined by content providers. This has identification for each user's Wallet Card contents.
* For secure transactions, a Reference ID(refId) must be in a form that cannot be inferred.

Example

https://a.swallet.link/atw/v3/YMtt/1656147182764415319#Clip?pdata=sIgHCzIwM9g

Provider-Initiated API

Register Card API

This is an API that allows partners to provide wallet cards to users. Request payload must include user information. Then the user device is notified of card registration through a push notification.

Card Data Specification

Card ID
{Card Id} is an ID issued when the partner manager signs up for partner services and register the wallet card they want to service. Refer to Partner Onboarding guide document for details.

cdata
Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. See the details on the below sheet.

Card Data Token
The specific wallet card data mentioned as cdata must be secured in JWT(JSON Web Token) format. See a chapter Security for details.

Request

Type

Value

Description

Method

POST

URL

/atw/v1/cards/{cardId}

Headers

Authorization

String(1024)

Required

Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer
* See Authorization Token

x-smcs-partner-id

String(32)

Required

Partner ID.

x-request-id

String(32)

Required

Request identifier.
Random generated UUID string.

x-smcs-cc2

String(2)

Required

Country Code (ISO-3166-1 alpha-2) of User Account

Path Parameters

cardId

String(32)

Required

Wallet card identifier granted from Partner Portal

Body Parameters

cdata

Object

Required

Actual payload data in basic JSON format to communicate between partners and Samsung Wallet.
This must be secured in JWT(JSON Web Token) format.
* See the chapter Security for more details.

payload object

card

Object

Required

Wallet card object

card.type

String(16)

Required

Wallet Card type.
*See Wallet Cards

card.subType

String(16)

Required

Wallet Card sub type.
*See *Wallet Cards

card.data[]

Array of Object

Required

Wallet card data container

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 update timestamp.
Epoch timestamp in milliseconds.
*UTC±00:00

data[].language

String(8)

Required

Default card language code.
e.g. en, ko

data[].attributes

Object

Required

Container of attributes

data[].attributes.{fields}

Required

Attributes fields by card.
type *See Wallet Cards

data[].localization[]

Array of Object

Optional

Container of localizationed language
*See Wallet Cards

localization[].language

String(8)

Required

Multilingual contenct language code.
e.g. en, ko

localization[].attributes.{fields}

For displaying a given language, ‘data[].attributes’ can be replaced by localized versions.
*See Wallet Cards

account

Object

Conditional

User Account object

account .type

String

Required

Type of User identifier
e.g. phoneNumber, email

account .value

String

Required

User identifier

Example (Success)

* 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 Wallet Cards
                                                        },
                                "localization": [{
                                "language": "ko",
                                "attributes": {
                                "title": "삼성 월렛"
                                }
            }]
  }]
},
"account": {
"type": "phoneNumber",
"value": "+821012345678”
}
}
* Example
POST /atw/v1/cards/1656147182764415319
[Headers] Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O... x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR
[Payload]
{
“cdata” : “eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…”
}

Response

Type

Value

Description

HTTP Status

200 OK

Payload

N/A

Example

200 OK

Result

HTTP Status Code

Description

200

200 OK

400

400 Bad Request

Requests cannot or will not be processed the request due to something that is perceived to be a client error

401

401 Unauthorized

Authorization token is invalid or expired.

500

500 Internal Server Error

503

503 Service Unavailable