Card Management API Guidelines

Once your service is successfully onboarded, you gain the ability to design and deploy custom digital assets—such as boarding passes, coupons, tickets, and more—directly to Samsung Wallet.

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

 title
String(32)

 (Required)
Wallet Card Name
countryCode
String(2)

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

 (Required)
Template Card Type
For details, refer to Wallet Cards
subType
String(100)

 (Required)
Template Card Sub Type
For details, refer to Wallet Cards
designType
String(100)

 (Optional)
The value that defines
the design type of the wallet card.
For details, refer to Wallet Cards
appLogoImg
String(200)

 (Optional)
The banner logo image URL. The maximum size of the image is 1024*1024.
e.g.: ttp://www.yourdomain.com/banner_logo_image.png
saveInServerYn
String(1)

 (Optional)
Sets whether to save the card data. This value can only be set for the ‘ID Card’ type.
prtnrAppPckgName
String(128)

(Optional)
The Application Package Name.
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'.
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'.
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'.
preventCaptureYn
String(1)

 (Optional)
This value is a screen capture prevention flag that defines whether the content view prevents screen capture.
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.
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
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
prtnrMemPoint
String(1000)

 (Optional)
[Get membership point] Partner URL.
cardMetaCP
String(1000)

 (Optional)
[Get card Meta CP] Partner URL.
getFulfillmentList
String(1000)

 (Optional)
[Get Fulfillment list] Partner URL.
prtnrBalance
String(1000)

 (Optional)
[Get card Balance] Partner URL.
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'.
desc
String(500)

 (Optional)
Description

Example

/** Example: Card Template object **/
{
  "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 Templates 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

 title
String(32)

 (Required)
Wallet Card Name
countryCode
String(2)

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

 (Optional)
The Application Package Name.
appLogoImg
String(200)

 (Optional)
The banner logo image URL. The maximum size of that image is 1024*1024.
saveInServerYn
String(1)

 (Optional)
Sets whether to save the card data. This value can only be set for the ‘ID Card’ type.
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'.
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'.
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'.
preventCaptureYn
String(1)

 (Optional)
This value is a screen capture prevention flag that defines whether the content view prevents screen capture.
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.
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
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
prtnrMemPoint
String(1000)

 (Optional)
[Get membership point] Partner URL.
cardMetaCP
String(1000)

 (Optional)
[Get card Meta CP] Partner URL.
getFulfillmentList
String(1000)

 (Optional)
[Get Fulfillmet list] Partner URL.
prtnrBalance
String(1000)

 (Optional)
[Get card Balance] Partner URL.
state
String(15)

 (Optional)
If the card status is “DRAFT”, you can only select “VERIFYING”.
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’.
desc
String(500)

 (Optional)
Description

[Example]

/* *Example: Card Template object **/
{
  "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

Get Wallet Card Templates

Wallet Card Templates created through the API can be retrieved via the template list API and are also visible and manageable through the Wallet Partners Portal.
Partners can view and manage all wallet card templates they have created.

[Request]

Type

 Value

 Description
Method

 GET
URL

 /partner/v1/card/templates
Headers

 Authorization
String(1024)

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

[Example]

/** Example **/
GET /partner/v1/card/templates
[Headers]
Authorization: eyJjdHkiOiJBVVRIIiwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
x-request-cc2: KR

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK

[Example]

200 OK
{
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "templates": [
        {
            "cardId": "3hdpejr6qi380",
            "title": "Wallet Card Title 01",
            "countryCode": "US",
            "cardType": "loyalty",
            "subType": "others",
            "noNetworkSupportYn": "N",
            "testingModeOff": "Y",
            "provisioningType": "NA",
            "useMoreServiceYn": "N",
            "preventCaptureYn": "N",
            "prtnrAppPckgName": null,
            "privacyModeYn": "N",
            "shareButtonExposureYN": "Y",
            "state": "VERIFYING",
            "appLogoImg": “”,
            "desc": “”
        },
        {
            "cardId": "3ctei2riqi9iq",
            "title": "Wallet Card Title 02",
            "countryCode": "US",
            "cardType": "generic",
            "subType": "others",
            "noNetworkSupportYn": "N",
            "testingModeOff": "Y",
            "provisioningType": "NA",
            "useMoreServiceYn": "N",
            "preventCaptureYn": "N",
            "prtnrAppPckgName": “”,
            "privacyModeYn": "N",
            "state": "VERIFYING",
            "category": "membership",
            "appLogoImg": “”,
            "desc": "NTF_US_GENERIC"
        }
]
}

[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