Server Interaction

Adding users' cards to Samsung Wallet allows for the updating of their data using server interactions. If partners want to manage the added cards, they need to find the card details to configure the API on the Partners Portal.

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

Figure 1: Server interaction

Partner Server API

The Samsung server can call the following APIs by using an endpoint in 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 detailed information of the requested card.

Request

Type Value Description
Method GET
URL {Partner server URL}/cards/{Card Id}/{refId}?fields={fields}
Headers Authorization String (1024) Required Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
* Refer to Authorization Token for more details.

x-request-id String (32) Required Request identifier.
Randomly generated UUID string.

Path Parameters Card Id String (32) Required Wallet card identifier.
* Refer to "Add to Wallet" Interfaces for more details.

refId String (32) Required 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.
* Refer to balance,barcode.

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 Conditional Card object (JSON).
* This field needs to be encrypted.
* Refer to Security for more details.

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.
* Refer to Wallet Cards for more details.

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.
* Refer to Card States for more details.

data[].language String (8) Required Default content language code.
For example, en, ko.

data[].attributes Object Required Card data attributes
data[].attributes. {fields} Attribute fields by card type.
* Refer to Wallet Cards for more details.

data[].localization[] Array of Object Optional Information for multilingual support
localization[]. language String (8) Required Multilingual content language code.
For example, en, ko.

localization[]. attributes.{fields} For displaying a given language, "data[].attributes" can be replaced by localized versions.
* Refer to Wallet Cards for more details.

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"

                    *Refer to 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.
* The card will be removed from the wallet service.

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/{Card Id}/{refId}
Headers Authorization String (1024) Required Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
* Refer to Authorization Token for more details.

x-request-id String (32) Required Request identifier.
Randomly generated UUID string.

Path Parameters Card Id String (32) Required Wallet card identifier.
* Refer to ‘Add to Wallet’ Interfaces for more details.

refId String (32) Required Unique content identifier defined by the content provider
Query Parameters cc2 String (2) Required Country code (cc2).
* Must use this on Samsung Server API

event String (16) Required Events on wallet card.
For example, ADDED, UPDATED, PENDING, DELETED.
* Refer to Card States for more details.

Payload callback String Optional Callback URL for Samsung Server API

Example:

POST /cards/12584806754/ref-20230304-001?cc2=KR&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 need to configure token-based authentication. Refer to Authorization Token for more 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/{Card Id}/notification
Headers Authorization String (1024) Required Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
* Refer to Authorization Token for more details.

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

Card Id 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.
* Refer to Wallet Cards for more details.

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, PENDING.
* Refer to Card States for more details.

Example:

POST /wltex/cards/12584806754/notification
[Headers]
Authorization: Bearer eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
{
    "card": {
        "type": "ticket",
        "data": [
            {
                "refId": "ref-20230304-0003",
                "state": "UPDATED"
            }
        ]
    }
}

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.
* The Card will be removed in the wallet service.

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/{Card Id}/cancellation
Headers Authorization String (1024) Required Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
* Refer to Authorization Token for more details.

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.

Card Id 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.
* Refer to Wallet Cards for more details.

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) Required if "card.type" has been set as "boardingpass".
data[].estimated OrActualStartDate Long (13)
data[].state String (16) Required Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED, PENDING
* Refer to Card States for more details.

Example:

POST /wltex/cards/12584806754/cancelation
[Headers]
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.
* The Card will be removed in the wallet service

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.