Server interaction

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

  1. Samsung server will notify its 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 call partners' server to look up the updated contents.

Server Interaction

Samsung Server API

[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) Mandatory Set credential token.
The token should have the prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See Security.

x-smcs-partner-id String(32) Mandatory Partner ID.
x-request-id String(32) Mandatory Request identifier.
Random generated UUID string.

Path Parameters cc2 String(2) Mandatory Country code (cc2).
* Use the value from Send Card State.

Card Id String(32) Mandatory Wallet card identifier granted from Partner Portal
Payload card Object Mandatory Wallet card object
card.type String(16) Mandatory Wallet card type.
* See Wallet Cards.

card.data[] Array of Object Mandatory Wallet card data container
data[].refId String(32) Mandatory A unique content identifier defined by the content provider
data[].state String(16) Mandatory Wallet card state
e.g., UPDATED, EXPIRED, REDEEMED, HELD, DELETED
* 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) Mandatory Set credential token.
The token should have the prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See Security.

x-smcs-partner-id String(32) Mandatory Partner ID.
x-request-id String(32) Mandatory Request identifier.
Randomly generated UUID string.

Path Parameters cc2 String(2) Mandatory Country code (cc2).
* Use the value from Send Card State

Card Id String(32) Mandatory Wallet card identifier granted from Partner Portal
Payload card Object Mandatory Wallet card object
card.type String(16) Mandatory Wallet card type.
* See Wallet Cards.

card.data[] Array of Object Mandatory Wallet card data container
data[].eventId String(32) Conditional Mandatory if card.type has been set as ‘ticket’.
data[].vehicle Number String(32) Mandatory if card.type has been set as ‘boardingpass’.
data[].estimated OrActualStartDate Long(13)
data[].state String(16) Mandatory Wallet card state
e.g., CANCELED.
* 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

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) Mandatory Set an authorization token.
* See Security.

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

Path Parameters Card Id String(32) Mandatory Wallet card identifier
* Refer to the ‘Add to Wallet’ Interfaces.

refId String(32) Mandatory 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 card Object Mandatory Card information.
card.type String(16) Mandatory Wallet Card type.
* See Wallet Cards.

card.data[] Array of Object Mandatory Wallet card data container
data[].refId String(32) Mandatory A unique content identifier defined by the content provider
data[].createdAt Long(13) Mandatory Timestamp of data.
Epoch timestamp in milliseconds.

data[].updatedAt Long(13) Mandatory Timestamp of data.
Epoch timestamp in milliseconds.

data[].state String(16) Mandatory Wallet card state
e.g., CREATED, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, CANCELED
* See Card States for details

data[].language String(8) Mandatory Default content language code.
e.g., en, ko

data[].attributes Object Mandatory 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) Mandatory 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"
            },
            "localization": [{
                "language": "ko",
                "attributes": {
                    "title": "Samsung Wallet"
                }
            }]
        }]
    }
}

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) Mandatory Set an authorization token.
* See Security.

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

Path Parameters Card Id String(32) Mandatory Wallet card identifier
* Refer to the ‘Add to Wallet’ Interfaces

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

event String(16) Mandatory Wallet card state as events
e.g., ADDED, 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