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