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