Card Template Management

This subsection defines APIs and governance rules for managing wallet card templates.

A wallet card template represents the structural and operational definition of a wallet card service. It defines:

The card type and subtype
Design configuration
Operational flags and policies
Lifecycle state

Template Lifecycle

Wallet card templates operate under a controlled lifecycle model.
Each template transitions through defined states before it becomes eligible for issuing wallet card instances.

Typical lifecycle states include:

Status	Description
VERIFYING	Initial state when a card template is first created. All fields and settings are fully editable.
ACTIVE	The card template is published and visible to users. This state is set by the partner through the Update API when the card is ready to launch. Once active, the card cannot be reverted to a previous state.
BLOCKED	Card has been blocked by Samsung (administrator-only action).

Templates must reach an appropriate operational state before wallet card instances can be issued.

Base Template Requirement
Before issuing any wallet card instance, a Base Template must be created.
The Base Template serves as the structural foundation for the associated wallet card type and defines its operational configuration.

Card Management Tools
Wallet card templates and instances can be managed using the following tools:

• Wallet Partners Portal
‐ Intended for managing individual templates or smaller batches.
‐ Provides a user interface for lifecycle management, status updates, and administrative review.

• Server API Access
‐ Designed for partners managing high volumes of wallet cards.
‐ Supports automation and scalable integration.
‐ Templates and cards created via API remain visible and manageable in the Samsung Wallet Partners Portal.

• Testing Mode
When a wallet card template is first created, it is automatically placed in Testing Mode.
‐ In Testing Mode, the wallet card is not publicly available to end users.
‐ Testing Mode must be manually disabled after validation is complete.
‐ Once Testing Mode is turned off, it cannot be re-enabled.
Testing Mode must be disabled before official deployment.

Template Management APIs

After successful onboarding, partners can create and manage wallet card templates and issue wallet card instances to Samsung Wallet.

The Card Template Management interfaces provide APIs to:
• Add wallet card templates
• Update wallet card templates
• Retrieve wallet card templates

These APIs define and manage the configuration under which wallet card instances are created.
Once a template is properly configured, authorized partners may add wallet cards to users directly from the partner server using the Adding Wallet Cards process.
A wallet card template may require administrative approval before it transitions to the Active state and becomes eligible for issuing wallet card instances.

Service Domain

Environment	Domain
Public domain	https://tsapi-card.walletsvc.samsung.com

Adding Wallet Card Template

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

[Request]

Type	Value	Description
Method	POST
URL	/partner/v1/card/template
Header	Authorization `String(1024)`	(Required) Credential token. The token can have prefix "Bearer" as an authorization type. i.e., Bearer <credentials> * See REST API Authorization Token (JWT / JWS).
	x-smcs-partner-id `String (32)`	(Required) Partner ID.
	x-request-id `String (32)`	(Required) Request identifier. Random generated UUID string.
Payload	Ctemplate `String`	(Required) Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. * See Template Specs This must be in the secure JWT (JSON Web Token) format. * See Card Data Token (cdata) section for more details.

Example

POST /partner/v1/card/template

/*[Headers]*/
Authorization: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/*[Payload]*/
{
  "ctemplate" : "<JWT_SERIALIZED>"
}

[Response]

Type	Value	Description
HTTP Status	200	OK
Payload	cardId `String(32)`	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 Template

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/{cardId}
Headers	Authorization `String(1024)`	(Required) Credential token. The token can have prefix "Bearer" as an authorization type. i.e., Bearer <credentials> * See REST API Authorization Token (JWT / JWS).
	x-smcs-partner-id `String(32)`	(Required) Partner ID.
	x-request-id `String(32)`	(Required) Request identifier. Random generated UUID string.
Path Parameters	cardId `String(32)`	(Required) The wallet card identifier granted through the Partner Portal. * The identifier is needed when updating a specific card template.
Payload	Ctemplate `Object`	(Required) Actual payload data in basic JSON format to establish the communication between partners and Samsung Wallet. * See Template Specs This must be in the secure JWT (JSON Web Token) format. * See Card Data Token (cdata) section for more details.

Example

POST /partner/v1/card/template/3hdpejr6qi380

/*[Headers]*/
Authorization: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

/*[Payload]*/
{
  "ctemplate" : "<JWT_SERIALIZED>"
}

[Response]

Type	Value	Description
HTTP Status	200	OK
Payload	cardId `String(32)`	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 <credentials> * See REST API Authorization Token (JWT / JWS).
	x-smcs-partner-id `String(32)`	(Required) Partner ID.
	x-request-id `String(32)`	(Required) Request identifier. Random generated UUID string.

Example

GET /partner/v1/card/templates

/*[Headers]*/
Authorization: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

[Response]

Type	Value	Description
HTTP Status	200	OK
Payload	templates `Object Array`	(Required) Wallet card template object

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

Template Specs

Template Attributes

Wallet Card Types

Wallet card type	Wallet card subtype
boardingpass	airlines, trains, buses, others
ticket	performances, sports, movies, entrances, others
coupon	others
giftcard	others
loyalty	others
idcard	employees, nationals, students, drivers, guests, others
digitalkey	doors, residents, hotels, cars, others
payasyougo	evcharges, others
generic	others
reservation	rentalcars, restaurants, accommodations, etickets, taxis, activities, others
transitcard	others
clip	businesstrips, trips, others

Wallet Card Templates Attributes

Type	Value	Description
Payload	cardTemplate `Object`	(Required) Wallet card template object
	cardTemplate.title `String(32)`	(Conditional) Wallet Card Name * Required when Adding wallet card template
	cardTemplate.countryCode `String(2)`	(Conditional) The Main (Headquarters) Location. * Required when Adding wallet card template
	cardTemplate.cardType `String(100)`	(Conditional) This value is set to cardType. * Required when Adding wallet card template
	cardTemplate.subType `String(100)`	(Conditional) This value is set to subType. * Required when Adding wallet card template
	cardTemplate.designType `String(100)`	(Optional) The value that defines the design type of the wallet card. * For Generic templates (i.e., when cardType is set to generic), set designType to one of the following values: "generic 01", "generic 02", or "generic 03". * Default: "generic 01"
	cardTemplate.prtnrAppPckgName `String(128)`	(Optional) The Application Package Name.
	cardTemplate.appLogoImg `String(200)`	(Optional) The banner logo image URL.
	cardTemplate.noNetworkSupportYn `String(1)`	(Optional) This must be set to either 'Y' or 'N'. * Default: 'N'.
	cardTemplate.shareButtonExposureYN `String(1)`	(Optional) This must be set to either 'Y' or 'N'. * Default: 'Y'.
	cardTemplate.privacyModeYn `String(1)`	(Optional) 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.shareButtonExposureYN `String(1)`	(Optional) This must be set to either 'Y' or 'N'. * Default: 'Y'.
	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 Get Card Data. 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 Send Card State (Send Card Event). For instance, you can use: https://{yourdomain}
	cardTemplate.state `String(15)`	(Optional) Wallet card's state * Default: 'VERIFYING' A card is always created in the VERIFYING state; this field cannot be set at creation time. Use this field in the Update API to change the state to ACTIVE. Only the VERIFYING → ACTIVE transition is supported.
	cardTemplate.testingModeOff `String(1)`	(Optional) TestMode Off. This must be set to either 'Y' or 'N'. * Default: ‘N’. * Available only when updating templates.
	cardTemplate.saveInServerYn `String(2)`	(Optional) This must be set to either 'Y' or 'N'. * Default: 'Y'.
	cardTemplate.category `String(20)`	(Optional) Select from the following values: “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others”. * This field is applicable only to Generic Card templates (i.e., when cardType is set to generic).
	cardTemplate.desc `String(500)`	(Optional) Description
	cardTemplate.layout `Object`	(Optional) Defines presentation rules for card data in Samsung Wallet. This field is applicable only when the `designType` is set to `generic-{subtype}-default`. For detailed specifications, see the section Layout Specs

Examples

Boarding Pass

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551312",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "boardingpass",
    "subType": "airlines",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "Y",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Event Ticket

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551314",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "ticket",
    "subType": "entrances",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "N",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Coupon

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551313",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "coupon",
    "subType": "others",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "Y",
    "privacyModeYn": "N",
    "preventCaptureYn": "N",
  }
}

Gift Card

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551315",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "gift",
    "subType": "others",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "Y",
    "privacyModeYn": "N",
    "preventCaptureYn": "N",
  }
}

Loyalty

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551316",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "loyalty",
    "subType": "others",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "N",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Digital ID

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551317",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "idcard",
    "subType": "employees",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "saveInServerYn": "Y",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "Y",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Pay As You Go

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551318",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "payasyougo",
    "subType": "evcharges",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "noNetworkSupportYn": "N",
    "shareButtonExposureYN": "Y",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Generic Card

{
  "cardTemplate": {
    "prtnrId": "4082825513190138240",
    "templateRefId": "2138240408282551319",
    "title": "Wallet Card Title",
    "prtnrAppPckgName": "prtnrAppPckgName",
    "countryCode": "US",
    "desc": "desc",
    "cardType": "generic",
    "subType": "others",
    "appLogoImg": "http://www.yourdomain.com/banner_logo_image.png",
    "designType": "generic 02",
    "noNetworkSupportYn": "N",
    "category": "membership",
    "privacyModeYn": "N",
    "preventCaptureYn": "N"
  }
}

Layout Specs

This document provides detailed specifications for the layout field used when adding Wallet Card Templates through the Card Management API. It is intended to be referenced from the layout field description in the Adding Wallet Card Template.

Overview

This section describes the specification of the layout field used when Adding Wallet Card Template.

The layout object defines presentation rules for card data in Samsung Wallet.
It does not contain display values directly. Instead, it references card data using attribute keys.

Layout Object Structure

The layout object consists of three sections:

header
primary
auxiliary

Each section defines a layout preset and a list of entry mappings.

Type	Value	Description
Layout object	layout `Object`	(Optional) Defines presentation rules for card data in Samsung Wallet.
	layout.header `Object`	(Required) Defines the header area of the card.
	layout.header.preset `String(10)`	(Required) Header layout preset. Allowed values: logo, logoText, text.
	layout.header.entries[] `Array of Object`	(Required) List of entry mappings that define how header UI slots reference card data.
	layout.header.entries[].entryName `String(100)`	(Required) Identifier of the UI slot. Format: {role}_{index} (e.g., image_01, field_01, subField_01).
	layout.header.entries[].entryKey `String(100)`	(Required) Attribute key used to retrieve the corresponding data value.
	layout.primary `Object`	(Required) Defines the primary content area of the card.
	layout.primary.preset `String(20)`	(Required) Primary layout preset. Generic cards: landscape, square, vertical, textOnly Boarding Pass: threeFields, fourFields, fiveFields.
	layout.primary.entries[] `Array of Object`	(Required) List of entry mappings that define how primary UI slots reference card data.
	layout.primary.entries[].entryName `String(100)`	(Required) Identifier of the UI slot. Format: {role}_{index} (e.g., image_01, field_01, subField_01).
	layout.primary.entries[].entryKey `String(100)`	(Required) Attribute key used to retrieve the corresponding data value.
	layout.primary.useBoardingTime `Boolean`	(Optional) Controls which time is displayed on the Boarding Pass card. - false (default): Displays the departure time - true: Displays the boarding start time Applies only when cardType = boardingpass
	layout.auxiliary `Object`	(Required) Defines additional information displayed when the card is expanded.
	layout.auxiliary.preset `String(20)`	(Optional) Defines the number of fields to be displayed. Allowed values: twoFields, threeFields, fourFields.
	layout.auxiliary.entries[] `Array of Object`	(Required) Ordered list of Fields rendered as label–value pairs. Each value is an attribute key.
	layout.auxiliary.entries[].entryName `String(100)`	(Required) Identifier of the UI slot. Format: {role}_{index} (e.g., image_01, field_01, subField_01).
	layout.auxiliary.entries[].entryKey `String(100)`	(Required) Attribute key used to retrieve the corresponding data value.

Example

{
  ......
  "layout": {
    "header": {
      “preset”: "logoText",
      "entries": [
        {
          "entryName": "image_01",
          "entryKey": "providerLogo"
        },
        {
          "entryName": "field_01",
          "entryKey": "providerName"
        },
        {
          "entryName": "subField_01",
          "entryKey": "vehicleNumber"
        }
      ]
    },
    "primary": {
      “preset”: "square",
      "entries": [
        {
          "entryName": "image_01",
          "entryKey": "wideImage"
        },
        {
          "entryName": "field_01",
          "entryKey": "grade"
        },
        {
          "entryName": "field_02",
          "entryKey": "seatClass"
        }
      ]
    },
    "auxiliary": {
      “preset”: "twoFields",
      "entries": [
        {
          "entryName": "field_01",
          "entryKey": "entrance"
        },
        {
          "entryName": "field_02",
          "entryKey": "seatNumber"
        }
      ]
    }
  }
}

Header – Required entryName by Preset

Preset	Required entryName	Description
logo	image_01, subField_01	Logo image with secondary text.
logoText	image_01, field_01, subField_01	Logo image with primary and secondary text.
text	field_01, subField_01	Primary and secondary text without image.

Primary – Required entryName by Preset

Preset	Required entryName	Description
landscape	image_01	Landscape image only.
square	image_01, field_01, field_02	Square image with two text fields.
vertical	image_01, field_01, field_02	Vertical image with two text fields.
textOnly	field_01	Single text field without image.

Primary / Auxiliary – Field-based Presets

Preset	Required entryName	Description
twoFields	field_01, field_02	Displays two label–value pairs.
threeFields	field_01, field_02, field_03	Displays three label–value pairs.
fourFields	field_01, field_02, field_03, field_04	Displays four label–value pairs.
fiveFields	field_01, field_02, field_03, field_04, field_05	Displays five label–value pairs (allowed where applicable).

Data Mapping (layout → card data)

The layout object does not contain display values.
Each field defined in layout references card data using an attribute key.

This section describes how attribute keys are resolved.

Data Resolution Rule
When a field is defined in layout, the value is resolved from the following locations in order:

card.data[].attributes
card.data[].attributes.extendedFields[].entryKey

Standard Attribute Mapping
If the entryKey defined in layout matches a field inside:

card.data[].attributes

The value is resolved directly from that attribute.

Example(Layout)

…
"primary": {
 …
 “preset”: "square",
 "entries": [
      {
        "entryName": "field_01",
        "entryKey": "providerName "
      },
 …
}
…

Example(Card.data[])

"attributes": {
…
"providerName": "Samsung Wallet"
…
}

Extended Fields Mapping
In addition to predefined attributes, layout fields may reference values inside extendedFields.

extendedFields is a user-defined data container that allows partners to define additional fields not included in the standard card specification.

extendedFields Structure

{
"card": {
    "data": [
      {
        …
        "attributes": {
          …
          "extendedFields": [
            {
              "label": "Gate",
              "value": "A12",
              "entryKey": "gateNumber"
            },
            {
              "label": "Zone",
              "value": "3",
              "entryKey": "boardingZone"
            }
          ]
        }
      }
    ]
  }
}

extendedFields Resolution Logic
If the layout field key does not exist in predefined attributes:

The system searches:

attributes.extendedFields[].entryKey

When a matching entryKey is found:

Value → resolved from extendedFields[].value
Label → resolved from extendedFields[].label

Example: layout referencing extendedFields

…
"auxiliary": {
  “preset”: "twoFields",
      "entries": [
        {
          "entryName": "field_01",
          "entryKey": "gateNumber"
        },
        {
          "entryName": "field_02",
          "entryKey": "boardingZone"
        }
      ]
}
…

Result
• gateNumber → value: "A12", label: "Gate"
• boardingZone → value: "3", label: "Zone"

Mapping Priority
If the same key exists in both:
• predefined attributes
• extendedFields

The resolution priority is:
• attributes (predefined fields)
• extendedFields

Summary
• layout fields reference data by attribute key.
• Standard attributes are resolved first.
• extendedFields enables user-defined data expansion.
• layout does not directly contain display value

Card Template Management

Template Lifecycle

Template Management APIs

Adding Wallet Card Template

Updating Wallet Card Template

Get Wallet Card Templates

Template Specs

Template Attributes

Examples

Layout Specs

Overview

Layout Object Structure

Data Mapping (layout → card data)

Manage Your Cookies

Essential Cookies

Analytical/Performance Cookies

Functionality Cookies

Preferences Submitted