Template Management API

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
DRAFT

 Initial state when a card is first created. All fields and settings are fully editable.
VERIFYING

 Verification process by Samsung administrators. Requires completion of General Information and CSR (Certificate Signing Request) registration.
* See Key & Certificate Lifecycle (Certificate-based Onboarding)
REJECTED

 Card did not pass verification. Rejection reasons are emailed to the partner. Cards can be revised and resubmitted.
ACTIVE

 Card has been approved and is now visible to users. Activation is final and cannot be undone.
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, authorised 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 may use the "Bearer" authorisation scheme.
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: &lt;JWT_SERIALIZED&gt;
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 may use the "Bearer" authorisation scheme.
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.

[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 Template

Retrieve one wallet card template created through the API by its Wallet Card ID (cardId).

[Request]

Type

 Value

 Description
Method

 GET
URL

 /partner/v1/card/template/{cardId}
Headers

 Authorization
String(1024)

 (Required)
Credential token. The token may use the "Bearer" authorisation scheme.
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. Randomly generated UUID string.
Path Parameters

 cardId
String(32)

 (Required)
Wallet card identifier issued through the Partner Portal.

 
GET /partner/v1/card/template/3hdpejr6qi380

Authorization: <JWT_SERIALIZED>
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003

[Response]

Type

 Value

 Description
HTTP Status

 200

 OK
Payload

 template
Object

 (Required)
Wallet card template object.

 
{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "template": {
    "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": ""
  }
}

[Result]

HTTP Status Code

 Description
200

 200 OK
400

 400 Bad Request
401

 401 Unauthorized — the 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.

Results can be paged with the offset and limit query parameters. If both are omitted, the API returns the full list without paging metadata for backward compatibility.

[Request]

Type

 Value

 Description
Method

 GET
URL

 /partner/v1/card/templates
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token may use the "Bearer" authorisation scheme.
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.
Query Parameters

 offset
Integer

 (Optional)
Zero-based start index. Default: 0. Must not be negative.
limit
Integer

 (Optional)
Number of items to return. Default: 20; maximum: 100.
If offset and limit are both omitted, the full list is returned without paging metadata.
Values outside 1–100 return 400 Bad Request (WDT1N1002).

 
GET /partner/v1/card/templates?offset=0&limit=20

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
totalCount
Integer

 (Optional)
Total number of templates matching the request. Included only when offset or limit is supplied.
offset
Integer

 (Optional)
Resolved offset value. Included only when offset or limit is supplied.
limit
Integer

 (Optional)
Resolved limit value. Included only when offset or limit is supplied.

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"
    }
  ]
}

Example (paged)

{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "totalCount": 137,
  "offset": 0,
  "limit": 20,
  "templates": [{
    "cardId": "3hdpejr6qi380",
    "title": "Wallet Card Title 01",
    "countryCode": "US",
    "cardType": "loyalty",
    "subType": "others",
    "state": "VERIFYING"
  }]
}

[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, 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)
Partner URL for the Get Card Data endpoint. Implement the endpoint according to the referenced API contract.
Example: https://{yourdomain}
cardTemplate.prtnrCardState
String(1000)

 (Optional)
Partner URL for the Send Card State (Send Card Event) endpoint. Implement the endpoint according to the referenced API contract.
Example: https://{yourdomain}
cardTemplate.state
String(15)

 (Optional)
Wallet card's state
* Default: 'DRAFT'
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
  1. Examples

Boarding Pass

Event Ticket

Coupon

Gift Card

Loyalty

Digital ID

Pay As You Go

Generic Card

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 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.

Illustrative layout fragment (not a complete JSON document):

{
  …..
  "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:

  1. card.data[].attributes

  2. 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 "
},
….
}
….
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

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

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