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/{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)
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