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.
- The Samsung server sends a notification of the result of the 'Add to Wallet' operation with Send Card State.
- Partners get the callback URL for Samsung Server API from the Send Card State payload.
- Using the callback URL, partners can perform actions for the added cards with the Samsung Server API.
- 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.
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": "삼성월렛"
}
}]
}]
}
}
- Refer to Wallet Cards for more details.
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. |