API Guidelines

Adding Wallet Card Specs

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.
* See Security

[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

 escription
URL

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

 certificateId
String(4)

 (Conditional)
Certificate identifier based on a CSR during onboarding.
4 digits alphanumeric.
* Must be generated from Partner Portal
cardId
String(32)

 (Required)
Wallet card identifier.
* It must be generated from Partners Portal.
Hash path parameters

 #Clip
String(5)

 (Required)
Parameters for the Hash link
Query parameter

 pdata
String(2048)

 (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]

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

Updating Wallet Card Specs

The added users’ cards allow updating its data using server interactions. Find the card details to configure API on Partner portal if partners want to manage the added cards.

  1. Samsung server will notify the result of 'Add to Wallet' via Send Card State.
  2. Partners get the callback URL for Samsung Server API from Send Card State payload.
  3. Using the callback URL, partners can make actions for the added cards via Samsung Server API.
  4. Depending on the interfaces, Samsung Server triggers specific operations. For example, when Update Notification is called, Samsung server calls partners' server to look up the updated contents.

Figure 1: Server interaction

Partner Server API

Samsung server can call the following API by using endpoint on the registered card information.
If the partner server manages an inbound allow list, contact us to register Samsung server IP address.

Get Card Data

Returns the current information of the card.

[Request]

Type

 Value

 Description
Method

 GET
URL

 {Partner server URL}/cards/{cardId}/{refId}?fields={fields}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* see Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String (32)

 (Required)
Wallet card identifier.
* See the "Add to Wallet" Interfaces
refId
String (32)

 (Required)
A unique content identifier defined by the content provider
Query Parameter

 fields
String(128)

 (Optional)
Attributes which intended to retrieve.
Can be specified using commas(,) as separators.
e.g. balance,barcode.value
Payload

 N/A
Example

 GET /cards/12584806754/ref-20230304-0003

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload(Option1)

 cdata
String(4096)

 (Conditional)
Card object (JSON).
* This field needs to be encrypted.
* see Security
Payload(Option2)

 card
Object

 (Conditional)
Card information.
* Card object as an alternative to cdata.
* If the card includes sensitive data, it is highly recommended to use cdata.
card.type
String (16)

 (Required)
Wallet Card 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)
Timestamp of data.
Epoch timestamp in milliseconds.
data[].updatedAt
Long (13)

 (Required)
Timestamp of data.
Epoch timestamp in milliseconds.
data[].state
String (16)

 (Required)
Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, CANCELED, PENDING, SUSPENDED.
* See Card States for details
data[].language
String (8)

 (Required)
Default content language code.
e.g., en, ko
data[].attributes
Object

 (Required)
Card data attributes
data[].attributes. {fields}

 Attribute fields by card type.
*See Wallet Cards
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.
*See Wallet Cards

[Example(Option1)]

{
	"cdata": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

[Example(Option2)]

{
       "card": {
        "type": "ticket",
        "subType": "movies",
        "data": [{
            "refId": "ref-20230304-001",
            "createdAt": 1612660039000,
            "language": "en",
            "attributes": {
                "title": "Samsung Wallet"

                    *See Wallet Cards

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

[Example(filtered using select parameter)]

GET /cards/12584806754/ref-20230304-0003?select=idPhoto
{
	"card": {
		"type": "ticket",
		"subType": "entrances",
		"data": [{
			"refId": "ref-20230304-0003",
			"createdAt": 1612660039000,
			"language": "en",
			"attributes": {
				"idPhoto": "{idPhoto data}"
			}
		}]
	}
}

/** OR **/
{
	"cdata": tokenize{data}
}

[Result]

HTTP status code

 Description
200 OK

 Success.
204 No Content

 Card doesn't exist.
400 Bad Request

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

 Authorization token is invalid or expired.
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from
fulfilling the request.
503 Service Unavailable

 Server is not ready to handle the request.

Send Card State

Partners can manage the state or history of the card using this API.
If the Card state is changed on the Samsung device, Samsung calls this API using a refId.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {Partner server URL}/cards/{cardId}/{refId}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token(/wallet/api_new/references/security.html)
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String (32)

 (Required)
Wallet card identifier.
* See the ["Add to Wallet" Interfaces]["Add to Wallet" Interfaces_]
refId
String (32)

 (Required)
A unique content identifier defined by the content provider
Query Parameters

 cc2
String (2)

 (Required)
Country code (cc2) for Samsung Server API
event
String (16)

 (Required)
Events on wallet card
e.g., ADDED, UPDATED, DELETED, PROVISIONED
* See Card States for details
Payload

 callback
String(1024)

 (Optional)
Callback URL for Samsung Server API

[Example]

POST /cards/12584806754/ref-20230304-001?cc2=us&event=ADDED

{
"callback": "https://us-tsapi.walletsvc.samsung.com"
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success.
401 Unauthorized

 Authorization token is invalid or expired.
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable

 Server is not ready to handle the request.

Samsung Server API

Partners can notify their contents changes with the following API.

Service Domain

Environment

 Domain
Public domain

 https://tsapi-card.walletsvc.samsung.com
Private domain

 ‘callback’ field from Send Card State API request payload.

The domains can be selectively used depending on your service requirement.

  • If the service needs to register static IPs on your system, we recommend using Private domain. In this case, use the domain received in the request 'callback' field from Send Card State API.
  • If the service does not require IP registration, Public domain can be a good choice. In this case, country code(cc2) is required as a path parameter.
  • To configure integration for each environment, register a new card service and get new card ID.
  • To guarantee safe communication, servers should configure Token-based Authentication. See Authorization Token for the details.

Update Notification

If wallet card data content is updated, send a notification to the Samsung server.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/updates
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-smcs-partner-id
String (32)

 (Required)
Partner ID
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain
cardId
String (32)

 (Required)
Wallet card identifier granted from Partners Portal.
Payload

 card
Object

 (Required)
Wallet card object
card.type
String (16)

 (Required)
Wallet card type.
* See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container
data[].refId
String (32)

 (Required)
Unique content identifier defined by the content provider
data[].state
String (16)

 (Required)
Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED.
* See Card States for details
data[].fields
String (128)

 (Optional)
Wallet Cards attributes which has been updated. Can be specified using commas(,) as separators. It is used when 'data[].state' is UPDATED.
e.g. balance,barcode.value
* Supported Wallet Card types: generic

[Example]

POST /wltex/cards/12584806754/notification
/** Header **/
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
  
/** Payload **/
/** Case 1: In general cases **/ 
{
  "card": {
    "type": "ticket",
    "data": [
      {
        "refId": "ref-ticket-0001",
        "state": "UPDATED"
      }
    ]
  }
}

/** Case 2: In case of deletion **/
{
  "card": {
    "type": "boardingpass",
    "data": [
        {
          "refId": "ref-boardingpass-0001",
          "state": "DELETED"
      }
    ]
  }
}

/** Case 3: When a specific field is updated **/
{
  "card": {
    "type": "idcard",
    "data": [
      {
        "refId": "ref-idcard-0001",
        "state": "UPDATED",
        "fields": "balance"
      }
    ]
  }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success.
204 No Content

 Card doesn’t exist.
400 Bad Request

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

 Authorization token is invalid or expired.
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from
fulfilling the request.
503 Service Unavailable

 Server is not ready to handle the request.

Cancel Notification

If a cancelation happens for events such as performances, sports, movies, and journeys, partners can send a notification about it and set all of the related cards to expire.

This API does not support updates for specific attributes on the card.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/cancels
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
*See Authorization Token
x-smcs-partner-id
String (32)

 (Required)
Partner ID.
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain.
cardId
String (32)

 (Required)
Wallet card identifier granted from the Partners Portal.
Payload

 card
Object

 (Required)
Wallet card object
card.type
String (16)

 (Required)
Wallet card type.
* See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container
data[].eventId
String (32)

 (Conditional)
Required if card.type has been set as ‘ticket’.
data[].vehicle Number
String (32)

 (Conditional)
Required if "card.type" has been set as "boardingpass".
data[].estimated OrActualStartDate
Long (13)
data[].state
String (16)

 (Required)
Wallet card state.
For example CANCELED
* See Card States for details

[Example]

POST /wltex/cards/12584806754/cancelation
/** Header **/
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140004
  
/** Payload **/
/** A movie ticket has been canceled **/
{
    "card": {
        "type": "ticket",
        "data": [
            {
                "eventId": "event-722164a1a7",
                "state": "CANCELED"
            }
        ]
    }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success.
204 No Content

 Card doesn’t exist.
400 Bad Request

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

 Authorization token is invalid or expired.
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from
fulfilling the request.
503 Service Unavailable

 Server is not ready to handle the request.