API Guidelines

The Adding Samsung Wallet Card Templates section defines interfaces for providers to conveniently create wallet cards in Samsung Wallet. The generated wallet card templates can be updated by following the instructions on the Updating Wallet Card Templates section.

Authorized partners can add wallet cards to users directly from the partner server by following the instructions on the Adding Wallet Cards section below.

[Service Domain]

Environment

 Domain
Public domain

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

Adding Wallet Card Templates

This section describes how to create a wallet card in Samsung Wallet.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /partner/v1/card/template
Headers

 Authorization

 String(1024)

 Required

 Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web Token.
x-smcs-partner-id

 String(32)

 Required

 Partner ID.
x-request-id

 String(32)

 Required

 Request identifier.
Random generated UUID string.
Body Parameters

 ctemplate

 Object

 Required

 Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. This must be in the secure JWT (JSON Web Token) format.
* See the chapter Security for more details.
Payload object

 cardTemplate

 Object

 Required

 Wallet card template object
cardTemplate.prtnrId

 String(32)

 Required

 Partner ID
cardTemplate.templateRefId

 String(19)

 Required

 Partner Template ID Unique value for
each template created by a partner.
This value is set to a number of 19
digits or less.
cardTemplate.title

 String(32)

 Required

 Wallet Card Name
cardTemplate.countryCode

 String(2)

 Required

 The Main (Headquarters) Location code.
Refer to ISO-3166-1 alpha-2) for the country code.
cardTemplate.cardType

 String(100)

 Required

 Template Card Type
For details, refer to Wallet Cards.
cardTemplate.subType

 String(100)

 Required

 Template Card Sub Type
For details, refer to Wallet Cards.
cardTemplate.designType

 String(100)

 Optional

 The value that defines
the design type of the wallet card.
For details, refer to Wallet Cards.
cardTemplate.appLogoImg

 String(200)

 Optional

 The banner logo image URL. The maximum size of the image is 1024*1024.
e.g.: http://www.yourdomain.com/banner_logo_image.png).
cardTemplate.saveInServerYn

 String(1)

 Optional

 Sets whether to save the card data. This value can only be set for the ‘ID Card’ type.
cardTemplate.prtnrAppPckgName

 String(128)

 Optional

 The Application Package Name.
cardTemplate.noNetworkSupportYn

 String(1)

 Optional

 Sets whether to support opening the wallet card under 'No Network' Status. This feature cannot be modified after the Wallet card is approved.
This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.shareButton
ExposureYN

 String(1)

 Optional

 Sets whether to support the sharing function. This feature cannot be modified after the Wallet card is approved.
This must be set to either 'Y' or 'N'.
* Default: 'Y'.
cardTemplate.privacyModeYn

 String(1)

 Optional

 If this value is set, the user authentication is required when using the card to protect the user's sensitive information.
This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.preventCaptureYn

 String(1)

 Optional

 This value is a screen capture prevention flag that defines whether the content view prevents screen capture.
cardTemplate.category

 String(20)

 Optional

 This item can only be set if the card type is “generic”.Set the Category to get more detailed statistical information. For instance, parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others.
cardTemplate.prtnrCardData

 String(1000)

 Optional

 [Get card data] Partner URL. Check the URL format below and implement the API according to the URL.
Refer to Partner Server API specification.
For instance, you can use: https://yourdomain
cardTemplate.prtnrCardState

 String(1000)

 Optional

 [Get card state] Partner URL.Check the URL format below and implement API according to URL.
Refer to Partner Server API specification.
For instance, you can use: https://yourdomain
cardTemplate.prtnrMemPoint

 String(1000)

 Optional

 [Get membership point] Partner URL.
cardTemplate.cardMetaCP

 String(1000)

 Optional

 [Get card Meta CP] Partner URL.
cardTemplate.getFulfillmentList

 String(1000)

 Optional

 [Get Fulfillment list] Partner URL.
cardTemplate.prtnrBalance

 String(1000)

 Optional

 [Get card Balance] Partner URL.
cardTemplate.state

 String(15)

 Optional

 When creating a card, you can transition the card's state from “Draft” to “Verifying”.
You can only choose “DRAFT” or “VERIFYING”.
* Default: 'DRAFT'.
cardTemplate.desc

 String(500)

 Optional

 Description

Example

* Example: Card Template object
{
  "prtnrId": "4083254626439156160",
  "templateRefId": "123456781864545365",
  "title": "Coupon",
  "countryCode": "KR",
  "cardType": "coupon",
  "subType": "others",
  "noNetworkSupportYn": "N",
  "shareButtonExposureYN": "Y"
}
* Example
POST /partner/v1/card/template
[Headers]
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR
[Payload]
{
  "ctemplate" : "eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…"
}

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK
Payload

 cardId

 Wallet Card ID

Example

200 OK
{
  "cardId": "3hdpejr6qi380",
  "resultCode": "0",
  "resultMessage": "SUCCESS"
}

[Result]]

HTTP Status Code

 Description
200

 200 OK
400

 400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401

 401 Unauthorized

 Authorization token is invalid or expired.
500

 500 Internal Server Error
503

 503 Service Unavailable

Updating Wallet Card Templates

Wallet Card Tmplates updated through API can also be checked and managed in the same way on the ‘Wallet Partners Portal'. Partners can manage all wallet cards they have created.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /partner/v1/card/template?cardId={Card Id}
Headers

 Authorization

 String(1024)

 Required

 Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web Token.
x-smcs-partner-id

 String(32)

 Required

 Partner ID.
x-request-id

 String(32)

 Required

 Request identifier.
Random generated UUID string.
Path Parameters

 N/A
Query Parameter

 Card Id

 String(32)

 Required

 The wallet card identifier granted through the Partner Portal.
* The identifier is needed when updating a specific card template.
Body Parameters

 ctemplate

 Object

 Required

 Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. This must be in the secure JWT (JSON Web Token) format.
* See the chapter Security for more details.
Payload object

 cardTemplate

 Object

 Required

 Wallet card template object
cardTemplate.prtnrId

 String(32)

 Required

 Partner ID
cardTemplate.cardId

 String(32)

 Required

 The cardId response received when creating a card.
cardTemplate.templateRefId

 String(19)

 Required

 Partner Template ID.
The unique value for each template created by a partner. This value is set to a number with 19 digits or less
cardTemplate.title

 String(32)

 Optional

 Wallet Card Name
cardTemplate.countryCode

 String(2)

 Optional

 The Main (Headquarters) Location code. Refer to ISO-3166-1 alpha-2) for the country code.
cardTemplate.prtnrAppPckgName

 String(128)

 Optional

 The Application Package Name.
cardTemplate.appLogoImg

 String(200)

 Optional

 The banner logo image URL. The maximum size of that image is 1024*1024.
cardTemplate.saveInServerYn

 String(1)

 Optional

 Sets whether to save the card data. This value can only be set for the ‘ID Card’ type.
cardTemplate.noNetworkSupportYn

 String(1)

 Optional

 Sets whether to support opening the wallet card under 'No Network' Status.
This feature cannot be modified after the Wallet card is approved. This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.shareButtonExposureYN

 String(1)

 Optional

 Sets whether to support the sharing function. This feature cannot be modified after the wallet card is approved.
This must be set to either 'Y' or 'N'.
* Default: 'Y'.
cardTemplate.privacyModeYn

 String(1)

 Optional

 If this value is set, user authentication is required when using the card to protect the user's sensitive information. This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.preventCaptureYn

 String(1)

 Optional

 This value is a screen capture prevention flag that defines whether the content view prevents screen capture.
cardTemplate.category

 String(20)

 Optional

 This item can only be set if the card type is “generic”.
Set the Category to get more detailed statistical information.
For instance: parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others.
cardTemplate.prtnrCardData

 String(1000)

 Optional

 [Get card data] Partner URL.
Check the URL format below and implement the API according to the URL.
Refer to Partner Server API specification.
For instance, you can use: https://yourdomainn
cardTemplate.prtnrCardState

 String(1000)

 Optional

 Partner URL.
Check the URL format below and implement the API according to the URL.
Refer to Partner Server API specification.
For instance, you can use: https://yourdomain
cardTemplate.prtnrMemPoint

 String(1000)

 Optional

 [Get membership point] Partner URL.
cardTemplate.cardMetaCP

 String(1000)

 Optional

 [Get card Meta CP] Partner URL.
cardTemplate.getFulfillmentList

 String(1000)

 Optional

 [Get Fulfillment list] Partner URL.
cardTemplate.prtnrBalance

 String(1000)

 Optional

 [Get card Balance] Partner URL.
cardTemplate.state

 String(15)

 Optional

 If the card status is “DRAFT”, you can only select “VERIFYING”.
cardTemplate.testingModeOff

 String(1)

 Optional

 This value can be set only when the card status is Active. Normal service is possible only when the testing mode is changed to off.
* Default: ‘N’.
cardTemplate.desc

 String(500)

 Optional

 Description

Example

*Example: Card Template object
{
  "prtnrId": "4083254626439156160",
  "cardId": "3hdpejr6qi380",
  "templateRefId": "123456781864545365",
  "title": "Coupon",
  "countryCode": "KR",
  "noNetworkSupportYn": "N",
  "shareButtonExposureYN": "Y"
}
* Example
POST /partner/v1/card/template?cardId=3hdpejr6qi380
[Headers]
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR

[Payload]
{
  "ctemplate" : "eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…"
}

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK
Payload

 cardId

 Wallet Card ID

Example

200 OK
{
  "cardId": "3hdpejr6qi380",
  "resultCode": "0",
  "resultMessage": "SUCCESS"
}

[Result]]

HTTP Status Code

 Description
200

 200 OK
400

 400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401

 401 Unauthorized

 Authorization token is invalid or expired.
500

 500 Internal Server Error
503

 503 Service Unavailable

Adding Wallet Cards

A typical addition to the wallet card is triggered by user interaction, such as pressing the Add To Wallet button or link. The API also supports adding a wallet card automatically to the user for a special purpose with user’s consent.

This API allows partners to provide wallet cards to users. The request payload must contain information about the target to which the card is added. This information may be related to the user’s account, or it may contain information about a card that is already registered. A push notification is sent to the user’s device to confirm successful card registration. The success of card registration must be determined that the card is registered normally when it is updated to ADDED of Send Card State.

An administrator must grant permission for partners to use this API.

[Card Data Specification]

Card ID
{Card Id} is an ID issued when the partner manager signs up for partner services and register the wallet card they want to service. Refer to Partner Onboarding guide document for details.

cdata
Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. See the details in the table below.

Card Data Token
The specific wallet card data mentioned as cdata must be secured in JWT(JSON Web Token) format. See a chapter Security for details.

[Request]

Type

 Value

 Description
Method

 POST
URL

 /atw/v1/cards/{Card Id}
Headers

 Authorization

 String(1024)

 Required

 Credential token.
The token can have prefix "Bearer" as an authorization type.
i.e., Bearer <credentials>
* See JSON Web 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 through the Partner Portal.
Body Parameters

 cdata

 Object

 Required

 Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet.
This must be in the secure JWT (JSON Web Token) format.
* See the chapter Security for more details.
payload object

 card

 Object

 Required

 Wallet card object
card.type

 String(16)

 Required

 Wallet Card type.
*See Wallet Cards
card.subType

 String(16)

 Required

 Wallet Card sub 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

 Data creation timestamp.
Epoch timestamp in milliseconds.
*UTC±00:00
data[].updatedAt

 Long(13)

 Required

 Data update timestamp.
Epoch timestamp in milliseconds.
*UTC±00:00
data[].language

 String(8)

 Required

 Default card language code.
e.g. en, ko
data[].attributes

 Object

 Required

 Attributes container.
data[].attributes.{fields}

 Required

 Attributes fields by card.type
*See Wallet Cards
data[].localization[]

 Array of Object

 Optional

 Localized language container.
*See Wallet Cards
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
account

 Object

 Conditional

 User account object.
account .type

 String(16)

 Required

 Type of user identifier, e.g. phoneNumber, email.
account .value

 String(64)

 Required

 User identifier

Example

* Example: Card object
{
    "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": "삼성 월렛"
                }
            }]
        }]
    },
    "account": {
      "type": "phoneNumber",
      "value": "+821012345678”
    }
}

* Example
POST /atw/v1/cards/1656147182764415319
[Headers] Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O... x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR
[Payload]
{
  "cdata" : "eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0Z…"
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A
Example

 200 OK

[Result]]

HTTP Status Code

 Description
200

 200 OK
400

 400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401

 401 Unauthorized

 Authorization token is invalid or expired.
500

 500 Internal Server Error
503

 503 Service Unavailable