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.

Samsung server will notify the result of 'Add to Wallet' via Send Card State.
Partners get the callback URL for Samsung Server API from Send Card State payload.
Using the callback URL, partners can make actions for the added cards via Samsung Server API.
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.

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 detailed information of the requested Card.

[Request]

Type	Value			Description
Method	GET
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. i.e., Bearer <credentials> * See Authorization Token.
Headers	x-request-id	String(32)	Required	Request identifier. Randomly generated UUID string.
Path Parameters	Card Id	String(32)	Required	Wallet card identifier * Refer to the ‘Add to Wallet’ Interfaces.
Path Parameters	refId	String(32)	Required	A unique content identifier defined by the content provider
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 cards include sensitive data, highly recommend using 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)	Mandatory	Wallet card state e.g., 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:

{
       "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": "삼성월렛"
                }
            }]
        }]
    }
}

Refer to Wallet Cards.

[Result]

HTTP Status Code		Description
200	200 OK
200	204 No Content	Card doesn't exist. * The Card will be removed in the wallet service.
400	401 Unauthorized	Authorization token is invalid or expired.
500	500 Internal Server Error
500	503 Service Unavailable

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. i.e., Bearer <credentials> * See Authorization Token.
Headers	x-request-id	String(32)	Required	Request identifier. Randomly generated UUID string.
Path Parameters	Card Id	String(32)	Required	Wallet card identifier * Refer to the ‘Add to Wallet’ Interfaces
Path Parameters	refId	String(32)	Required	A unique content identifier defined by the content provider
Query Parameters	cc2	String(2)	Required	Country code (cc2). * Must use this on Samsung Server API
Query Parameters	event	String(16)	Required	Events on wallet card e.g., ADDED, UPDATED, PENDING, DELETED * 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	200 OK
400	401 Unauthorized	Authorization token is invalid or expired.
500	500 Internal Server Error
500	503 Service Unavailable

Samsung Server API

Partners can notify their contents changes with the following API by using 'callback' endpoint from Sende Card States API response.

If there is no need to manage static IPs, use the following domain to invoke APIs.

[Service Domain]

Environment	Domain
Production	https://tsapi-card.walletsvc.samsung.com

- To configure integration for each environments, 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	/wltex/cards/{Card Id}/notification
Headers	Authorization	String(1024)	Required	Credential token. The token can have prefix "Bearer" as an authorization type. i.e., Bearer <credentials> * See Authorization Token.
	x-smcs-partner-id	String(32)	Required	Partner ID.
	x-request-id	String(32)	Required	Request identifier. Random generated UUID string.
Path Parameters	Card Id	String(32)	Required	Wallet card identifier granted from Partner 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	A unique content identifier defined by the content provider
	data[].state	String(16)	Required	Wallet card state e.g., ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED, PENDING * See Card States for 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	200 OK
200	204 No Content
400	401 Unauthorized	Authorization token is invalid or expired.
500	500 Internal Server Error
500	503 Service Unavailable

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	/wltex/cards/{Card Id}/cancellation
Headers	Authorization	String(1024)	Required	Credential token. The token can have prefix "Bearer" as an authorization type. i.e., 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	Card Id	String(32)	Required	Wallet card identifier granted from Partner 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)		Required if card.type has been set as ‘boardingpass’.
	data[].state	String(16)	Required	Wallet card state e.g., ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED, PENDING * See Card States for details.

Example:

POST /wltex/cards/12584806754/cancellation
[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	200 OK
200	204 No Content
400	401 Unauthorized	Authorization token is invalid or expired.
500	500 Internal Server Error
500	503 Service Unavailable