Server Interaction

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.

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. * Refer to 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	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. * 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"

                    *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.
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
	x-request-id	String (32)	Required	Request identifier. Randomly generated UUID string.
Path Parameters	cardId	String (32)	Required	Wallet card identifier. * Refer to the ‘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	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 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
[Headers]
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)		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 * See Card States for 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.
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.