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