3.3 API Guidelines

3.3.1 Adding Wallet Card Specs

When integrating with Samsung Wallet, the Add to Wallet functionality allows users to securely add cards (such as loyalty cards, payment cards, or tickets) to their Samsung Wallet app. To ensure a smooth and successful integration, partners need to follow specific API guidelines for adding card specs.

Here is an overview of the steps and key components you need to consider when integrating the API for adding wallet cards.

Data Transmit Link

The Data Transmit Link is the API endpoint through which partners send the initial card data (e.g., card number, expiration date, issuer information, barcode, etc.) to Samsung Wallet.

The most common and straightforward method is the Data Transmit Link approach, which securely includes tokenized data in the ATW link. The ATW link format for this method is as follows:

Type

 Value

 Description
URL

 https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}
Path parameters

 cardId
String

 (Required)
Wallet card identifier issued from Partner portal when the partner manager
signs up for partner services and registers the wallet card they want to service.
Hash path parameters

 #Clip
String

 (Required)
Parameters for the Hash link
* The first letter is capitalized
Query parameters

 cdata
String

 (Required)
Actual payload data in basic JSON format to communicate between partners
and Samsung Wallet.
This must be secured in JWT(JSON Web Token) format. * See Security

[Example]

https://a.swallet.link/atw/v3/1656147182764415319#Clip?cdata=eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0ZWQgdGltZSIsInBhcnRuZXJJRCI6InBhcnRuZXIgSUQifQ.
… … … …
Dn0_oZ3xcr0JuQ3mlSzLIUTxFoTewnZ0MQj7kiNjysNm5Xfwqt5vcN20PeebeLgUx8VJXLy4_9G4BHQ-hd4O9POYuTuAWew.YzdlMTFhO -NYCeL3T0YzNzAD2KcK_HrtwIGEErHLGn6ydaq_fpFdSlxsA3ZJtNpg3wcuqEw5cIdpbPFswbQLropqEpNawg5nlm3DKAA4a1dzaZMbSR1BGZHrH_vIKnx3CY5MO0jNBexl_YIZ5_wB379UYSwumQiPiTZVg2IjYvfht17I4

Data Fetch Link

The Data Fetch Link allows partners to retrieve card details after the card has been added to the Samsung Wallet.
In cases involving sensitive data or when providing static links, Data Fetch Link method is highly recommended. Links using this approach include only a unique reference ID, and Wallet Cards are added by querying data through Get Card Data path as specified in Partner portal.

Type

 Value

 Description
URL

 https://a.swallet.link/atw/v3/{CertificateId}/{cardId}#Clip?pdata={pdata}
Path parameters

 certificateId
String(4)

 (Conditional)
ertificate identifier based on a CSR during onboarding.
4 digits alphanumeric.
* Must be generated from Partner Portal
cardId
String(32)

 (Required) Wallet card identifier.
* It must be generated from Partners Portal.
Hash path parameters

 #Clip
String(5)

 (Required)
Parameters for the Hash link
Query parameter

 pdata
String(2048)

 (Required)
Unique ID defined by content providers.
This has identification for each user's Wallet Card contents.
* For secure transactions, a Reference ID (refId) must be in a form that cannot be inferred.

Example - https://a.swallet.link/atw/v3/YMtt/1656147182764415319#Clip?pdata=sIgHCzIwM9g

3.3.2 Updating Wallet Card Specs

When users add cards to Samsung Wallet, their data can be updated through server interactions. To manage these updates, partners need to configure their API settings via the Partner Portal.

Follow the steps below to manage and update the cards added to Samsung Wallet:

  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.

![](https://d3 unf4s5rp9dfh.cloudfront.net/SamsungWallet_doc/updating-wallet-card-specs.png)

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

The Get Card Data allows partners to retrieve the most up-to-date information about a card that has already been added to Samsung Wallet. This API is crucial for ensuring that the partner’s system has accurate and current details about a user's card, whether for display, transaction validation, or other purposes.

[Request]

Type

 Value

 Description
Method

 GET
URL

 {Partner server URL}/cards/{cardId}/{refId}?fields={fields}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
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 Parameter

 fields
String(128)

 (Optional)
Attributes which intended to retrieve.
Can be specified using commas(,) as separators.
e.g. balance,barcode.value
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(4096)

 (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 includes sensitive data, it is highly recommended 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)

 (Required)
Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, CANCELED, PENDING, SUSPENDED.
* 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 (Option1)]

{ 
"cdata": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" 
}

[Example (Option2)]

{
  "card": {
    "type": "ticket",
    "subType": "movies",
    "data": [{
      "refId": "ref-20230304-0002",
      "createdAt": 1612660039000,
      "language": "en",
      "attributes": {
        "title": "Samsung Wallet"
        /* Refer to Wallet Cards */
      },
      "localization": [{
        "language": "ko",
        "attributes": {
          "title": "삼성월렛"
        }
      }]
    }]
  }
}

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

The Send Card State is used to 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/{cardId}/{refId}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
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) for Samsung Server API
event
String (16)

 (Required)
Events on wallet card
e.g., ADDED, UPDATED, DELETED, PROVISIONED
* See Card States for details
Payload

 callback
String(1024)

 (Optional)
Callback URL for Samsung Server API

[Example]

POST /cards/12584806754/ref-20230304-001?cc2=us&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

The Samsung Server API allows partners to notify their content changes to Samsung Wallet. Depending on your service requirements, you can choose from Private Domain or Public Domain to send notifications. The domain selection depends on your system's needs and security preferences.

Service Domain

Environment

 Domain
Public domain

 https://tsapi-card.walletsvc.samsung.com
Private domain

 ‘callback’ field from Send Card State API request payload.

Key components

Private Domain (Recommended for IP Registration) - If your service requires registering static IP addresses on your system, we recommend using the Private Domain. When you use the Private Domain, you will receive a callback URL in the Send Card State API response. This URL will direct your system to the correct endpoint to send content updates or changes.

Public Domain (Recommended for No IP Registration) - If your service does not require IP registration or has more flexible network access, you can use the Public Domain. The Public Domain API endpoint allows easier integration without requiring specific IP addresses to be registered. However, it does require a country code (cc2) as a path parameter for each request. This ensures that content is correctly routed based on the user's region or country.

To configure the API integration for different environments (e.g., testing, production), you must first register a new card service with Samsung. This process will assign you a new card ID for use in your API calls.

The card ID is crucial for identifying and tracking the specific card you are interacting with.

To ensure safe and secure communication, servers should configure Token-based Authentication. For information, refer to the Authorization Token.

Update Notification

Allows partners to notify Samsung Wallet when there are changes or updates to the content of a wallet card. This ensures that the card information within Samsung Wallet remains up-to-date and accurate.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/updates
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., 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

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain
cardId
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.
* 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.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED.
* See Send Card State for details
data[].fields
String (128)

 (Optional)
Wallet Cards attributes which has been updated. Can be specified using commas(,) as separators.
It is used when 'data[].state' is UPDATED.
e.g. balance,barcode.value
* Supported Wallet Card types: generic

[Example]

POST /wltex/cards/12584806754/notification
[Headers]
Authorization: eyJjdHkiOiJUVRlliwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
(Case 1: In general cases)
{
  "card": {
    "type": "ticket",
    "data": [
      {
        "refId": "ref-ticket-0001",
        "state": "UPDATED"
      }
    ]
  }
}

(Case 2: In case of deletion)
{
  "card": {
    "type": "boardingpass",
    "data": [
      {
        "refId": "ref-boardingpass-0001",
        "state": "DELETED"
      }
    ]
  }
}

(Case 3: When a specific field is updated)
{
  "card": {
    "type": "idcard",
    "data": [
      {
        "refId": "ref-idcard-0001",
        "state": "UPDATED",
        "fields": "balance"
      }
    ]
  }
}

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

Allows partners to inform Samsung Wallet when a card (such as for performances, sports, movies, or journeys) needs to be cancelled. When a cancellation occurs, this API enables partners to set the related card(s) to an expired status. This ensures that users no longer have valid access to events or services that have been cancelled, such as a concert, flight, or movie screening.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/cancels
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., 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

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain.
cardId
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.
* 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)

 (Conditional)
Required if "card.type" has been set as "boardingpass".
data[].estimated OrActualStartDate
Long (13)
data[].state
String (16)

 (Required)
Wallet card state.
e.g., CANCELED
* See Card States for details

[Example]

POST /wltex/cards/12584806754/notification
[Headers]
Authorization: eyJjdHkiOiJUVRlliwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
* A movie ticket has been canceled.
{
  "card": {
    "type": "ticket",
    "data": [
      {
        "refId": "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
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