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.

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.

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.

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.

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

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

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)
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