Implement the Add to Samsung Wallet Entry Point

Generate the ATW URL on the partner back end, then present it through the channel that starts the user journey. This section defines channel-specific entry points; the URL contract itself is defined in Add Card Links.

To integrate the Add to Wallet (ATW) functionality into your system, you need to embed the provided ATW script and configure it using tokenized card data. This allows users to securely add digital cards to Samsung Wallet.

Follow the steps below to implement the ATW button:

Script Composition: Begin by composing the integration script using the sample code provided on the Samsung Wallet Partners Portal. Alternatively, refer to the Code Resources for detailed instructions.
Create Tokenized Card Data (cdata): Generate cdata on the partner back end and insert the resulting token into the script. The protected payload contains the card content defined by the selected card type. For more information, see Code Resources.

Note:Cdata token should expire in 30 seconds after creation, so cdata token needs to be created right after users actually click ‘Add to Wallet’ button.

To implement ‘Add to Wallet’ button, you may need some base data. You can find the base data and other necessary information on Samsung Wallet Partners Portal.

Partners are required to implement both impression and click tracking for the Add to Wallet entry point.

Samsung Wallet on the Web

This section explains how to implement the Add to Wallet button using JavaScript within a web environment or web view.

Web Button Reference with importing API Javascript

If you implement the "Add to Wallet" button using this script, the button is shown only on the devices that support Samsung Wallet.

To automatically parse <samsung:wallet> HTML tags when the page is loaded, include the following standard JavaScript:

<script src="https://us-cdn-gpp.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>

You can use these tags or JavaScript functions for the web button if you are rendering HTML and you have proper partner permissions. You can also use the script by referring to the various attributes.

samsung:wallet HTML Tag

The ‘samsung:wallet’ namespace tag defines the placement and various attributes of the "Add to Wallet" web button for Samsung Wallet.

Button attributes

Attribute	Description
cardid `String`	(Required) Wallet card identifier * Value granted from the Partners Portal.
cdata `String`	(Required) Encrypted card object (JSON). * This field needs to be encrypted. * See Card Data Token (cdata)
partnercode `String`	(Required) Partner code. * Value granted from the Partners portal.
buttonid `String`	(Required) DOM element ID for the "Add to Wallet" web button for Samsung Wallet
buttontype `String`	(Optional) “Add to Wallet” button type [“btnSW” / “btnATSW” / “qrcode”, default: btnSW] * See Image Resources
inline `String`	(Optional) Flag to display the "Add to Wallet" image button in one-line format. Default: true (one-line).
locale `String`	(Optional) Locale of the "Add to Wallet" image button. * See Image Resources
rdclickurl `String`	(Required) URL for logging a button click event. * Value granted from Samsung Wallet Partners Portal
rdimpressionurl `String`	(Required) URL for logging a button impression event. * Value granted from Samsung Wallet Partners Portal
showforced `String`	(Optional) Flag to force the "Add to Wallet" button to be displayed. Default: false.
mediatheme `String`	(Optional) Load the button’s resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly. Default: default. default: Load the button’s theme according to the prefers-color-scheme policy. inversion: Load the inverse of the default button’s theme.* lightonly: Load the light theme of the default button. *darkonly: Load the dark theme of the default button.
style `String` (CSSStyleDeclaration)	(Optional) Load the button with custom style
target `String`	(Optional) Option to choose button’s target name * default : “WALLET”
onshowbutton Function	(Optional) Callback handler function for the button’s on-show event
onclickbutton Function	(Optional) Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value. * See Usage of onClickButton Handler

samsungWallet.addButton Function

The samsungWallet.addButton function is used to explicitly render the Add to Wallet button on your web page using the Samsung Wallet JavaScript API.

Button Attributes

Attribute	Description
cardId `String`	(Required) Wallet card identifier. * Value granted from the Partners Portal.
cdata `String`	(Required) Encrypted card object (JSON). * This field needs to be encrypted. * See Card Data Token (cdata)
partnerCode `String`	(Required) Partner code. * Value granted from the Partners Portal.
targetId `String`	(Required) DOM (Document Object Model) Element ID to place the "Add to Wallet" web button for Samsung Wallet
buttonId `String`	(Required) DOM Element ID for the "Add to Wallet" web button for Samsung Wallet
buttonType `String`	(Optional) “Add to Wallet” button type [“btnSW” / “btnATSW” / “qrcode”, default: btnSW] * See Image Resources
Inline `String`	(Optional) Flag to display the "Add to Wallet" image button in one-line format. Default: true (one-line).
locale `String`	(Optional) Locale of the "Add to Wallet" image button. * See Image Resources
RDClickUrl `String`	(Required) URL of logging a button click event. * Value granted from the Partners Portal.
RDImpressionUrl `String`	(Required) URL of logging a button impression event. * Value granted from the Partners Portal.
showForced `String`	(Optional) Flag to force the "Add to Wallet" button to be displayed. Default: false.
mediaTheme `String`	(Optional) Load the button’s resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly. Default: default. default: Load the button’s theme according to the prefers-color-scheme policy. inversion: Load the inverse of the default button’s theme. lightonly: Load the light theme of the default button. darkonly: Load the dark theme of the default button.
style `Object` (CSSStyleDeclaration)	(Optional) Load the button with a custom style
target `String`	(Optional) Option to choose button’s target name * default : “WALLET”
onShowButton Function	(Optional) Callback handler function for the button’s on-show event.
onClickButton Function	(Optional) Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value. * See Usage of onClickButton Handler

Usage of onClickButton Handler

The onClickButton handler allows to define what happens when a user clicks the ‘Add to Wallet’ button. We recommend that you add the process of generating JWT cdata (add cdata to options.cdata) to this handler, because of the cdata expiration time.

The function parameters are defined as follows.

Attributes	Description
options Button attributes	(Optional) Attributes of the current button
callback Function	(Optional) Callback function to pass the flag to proceed. Default: false.
(Promise resolve) Function	(Optional) Promise-resolved value to pass the flag to proceed Default: false.

Callback to web button process from callback attributes (for ES5)

In an ES5 (ECMAScript 5) environment, you can use the callback attribute in your web button implementation to control the flow of the "Add to Wallet" process.

By executing the callback function with a Boolean flag {callback(flag)} you can determine whether or not to proceed to the next step in the wallet integration.

Callback to web button process from returning Promise (for ES6)

In an ES6 environment, by returning a promise with a resolving flag, you can proceed to the next Add to Wallet process.

Note:The card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the ‘Add to Wallet’ button.

Samsung Wallet on the App

This section outlines how to implement the “Add to Wallet” button within a native application (e.g., Android or iOS).

Steps to Implement ‘Add to Wallet’ in a Native App

Download the official ‘Add to Wallet’ button graphics from the designated repository based on your service environment. For details on available assets and usage guidelines, see the Image Resources section.
Before displaying the button, use the ‘Check Service Available Devices’ API to determine whether the user's device supports Samsung Wallet.
Interpret the API response as follows:
If "available": true → Device is supported → Show the ‘Add to Wallet’ button.
If "available": false → Device is not supported → Do not show the button.
Implement a JWT web link on the button triggered action.

Note:The card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “Add to Wallet” button.

App Button on Android

Sample code implementation

Samsung Wallet via MMS or Email

This section outlines how to configure and deliver Samsung Wallet cards through MMS or email, enabling users to add cards to Samsung Wallet directly from their messaging platforms.

Overview

Integrating Samsung Wallet into MMS or email involves sending a web link that allows users to add a wallet card without needing to load the full JavaScript API. This approach is ideal for environments such as:

SMS/MMS messages
Email communications

Note:These methods do not support dynamically controlling button visibility based on device compatibility.

Guide to configuring wallet code for email and MMS messages

Set up the Data Fetch Link, including the necessary server APIs to retrieve the wallet card data.
Create a unique ‘reference ID’ for each transaction or request.
Ensure the ‘reference ID’ is complex and secure to prevent the inference of sensitive information.
Send the message containing the web link via a preferred platform (e.g., email or MMS). For MMS, the web link will show up as a ‘Smart Suggestion’ on Samsung devices, providing a streamlined user experience. For reference, a sample web link can be found on the [Samsung Wallet Partners Portal(https://partner.walletsvc.samsung.com/) guide.
For card data, Samsung Wallet asks the partner system to provide card details through the server API.
Duplicate requests are prohibited on the same device to ensure data integrity.

Link to ‘Add to Wallet’ on MMS/Email

You can include an “Add to Wallet” web button in environments where the JavaScript API cannot be loaded, such as SMS or email.

These methods do not support controlling “Add to Wallet” button visibility.

MMS Link

URL Link: URL
Attributes	Description
URL `String`	(Required) “Add to Wallet” link URL. * See Data Transmit Link

Email on Web Button Link

Attributes	Description
URL `String`	(Required) “Add to Wallet” link URL. * See Data Transmit Link
IMAGE_URL `String`	(Required) Button’s image resource URL. * See Image Resources
RD_IMPRESSION_URL `String`	(Required) Impressions logging URL. * Value granted from the Partners Portal.

Instrument ATW Impressions and Clicks

Samsung Wallet provides valuable statistical data about integrated services through the Partners Portal. This data helps you track key events, such as button impressions and user interactions, to optimise your service and improve the overall user experience.

Note:Statistics API sample code - The actual code sample is at the wallet script guide section in ‘Wallet Cards’ menu on the Samsung Wallet Partners Portal.

Event Notification API

https://us-rd.mcsvc.samsung.com/statistics/{event}/addtowlt?{parameters}&utm_source=partner&utm_medium={channel}

{event}:

For each event in the following situations:

impression: When the “Add to Wallet” button has been shown
click: When the “Add to Wallet” button has been clicked

{parameters}:

Includes key factors to figure out the service.

{channel}:

app: "Samsung Wallet" button in a native application
web: "Samsung Wallet" button on the web
email: "Samsung Wallet" button in an email

For details, please visit 'Wallet Cards' menu on the partner portal.

Partner Tracking Obligations for Add to Wallet

To support service measurement and operational analytics, the partner must transmit Add to Wallet tracking events for user exposure and user interaction.

Mandatory requirements

The partner MUST send an impression event when the Add to Wallet button is shown to the end user.
The partner MUST send a click event when the end user clicks or taps the Add to Wallet button.
These tracking events apply to supported channels, including app, web, and email, where the Add to Wallet integration is presented.
The partner MUST use the tracking endpoint and required parameters provided by Samsung Wallet or the Partner Portal.
The partner SHOULD ensure that tracking events are sent once per actual user event and SHOULD avoid artificial duplication caused by page reloads, retries, or automated scripts.

Implementation note

Tracking delivery is a partner integration responsibility and is not optional when Add to Wallet analytics is required for the card programme.
Failure to implement the required impression and click tracking may result in incomplete statistics, operational visibility gaps, or review issues during onboarding and approval.