3.4 Implementing ATW button

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 Partners Portal. Alternatively, refer to the Integration Sample Code for detailed instructions.
  • Create Tokenized Card Data (Cdata): Next, generate the Cdata (tokenized card data) and insert the corresponding Cdata token into the script. Cdata represents the actual content of the wallet card and comes in various formats depending on the card type. For more information, refer to the Generate_Cdata Sample Code.

To implement ‘Add to Wallet’ button, you may need some base data. You can find the base data and other necessary information on Partner portal’s Wallet card page.

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

<samsung:wallet 
cardid="CARD_ID" cdata="CDATA" partnercode="PARTNER_CODE" buttonid="BUTTON_ID"
rdclickurl="RD_CLICK_URL" rdimpressionurl="RD_IMPRESSION_URL"
></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 Security
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
authToken
String

 (Optional)
Token generated when “qrcode” is used.
* Required only if the “buttonType” is set to “qrcode”
model
String

 (Optional)
Device model to display button
* By default, value from User-Agent is used. If no value from User-Agent, the button is displayed.
* To display buttons only on devices supporting Samsung Wallet, explicitly include the model name.
* For example, you can retrieve the device model name (e.g., SM-S928F) from the browser's User-Agent.
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 the Partners Portal.
rdimpressionurl
String

 (Required)
URL for 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
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.

samsungWallet.addButton({
    cardId: "CARD_ID",
    cdata: "CDATA",
    partnerCode: "PARTNER_CODE",
    targetId: "TARGET_ID",
    buttonId: "BUTTON_ID",
    RDclickUrl: "RD_CLICK_URL",
    RDImpressionUrl: "RD_IMPRESSION_URL",
})

Button attributes

Attributes

 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.
* SeeSecurity
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
authToken
String

 (Optional)
Token generated when “qrcode” is used.
* Required only if the “buttonType” is set to “qrcode”
model
String

 (Optional)
Device model to display button
* By default, value from User-Agent is used. If no value from User-Agent, the button is displayed.
* To display buttons only on devices supporting Samsung Wallet, explicitly include the model name.
* For example, you can retrieve the device model name (e.g., SM-S928F) from the browser's User-Agent.
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.

onClickButton: function (options, callback) {
    // TODO partner's process
    callback(flag)
}

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.

onClickButton: async (options) => {
    return new Promise(async (resolve, reject) => {
        // TODO partner's process (await)
        resolve(flag)
    })
}

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

  1. 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.
  2. Before displaying the button, use the ‘Check Service Available Devices’ API to determine whether the user's device supports Samsung Wallet.
  3. Interpret the API response as follows:
  4. If "available": true → Device is supported → Show the ‘Add to Wallet’ button.
  5. If "available": false → Device is not supported → Do not show the button.
  6. Implement a JWT web link on the button triggered action.

App Button on Android

[Sample code implementation]

public class WalletCodeSample {
    protected final static String TAG = "SamsungWalletSample";
    protected static final String HOST = "https://api-us3.mpay.samsung.com";
    protected static final String PATH = "wallet/cmn/v2.0/device/available";

    /**
     * Sample entry point of the usage
     */
    public static void main() {
        Executors.newSingleThreadExecutor().submit(() -> {
            final String modelName = Build.MODEL;
            final String countryCode = null;     // (optional) country code (ISO_3166-2)
            final String serviceType = "WALLET"; // (Required, fixed) for Samsung Wallet
            final String partnerCode = null;     // (Required)

            try {
                WalletCodeSample sample = new WalletCodeSample();
                boolean isWalletSupported = sample.checkWalletSupported(
                        modelName, countryCode, serviceType, partnerCode
                );

                String msg = String.format(
                        "query for model(%s), countryCode(%s), serviceType(%s), partnerCode(%s) / wallet supported? (%s)",
                        modelName,
                        countryCode,
                        serviceType,
                        partnerCode,
                        isWalletSupported);
                Log.d(TAG, msg);
            } catch (Exception e) {
                // failed to check due to some reasons
                Log.e(TAG, e.getMessage(), e);
            }
        });
    }

    /**
     * please See the Wallet API Spec document > '6.6 Check service available devices' for more details
     *
     * @return true if wallet supported, otherwise false
     * @throws Exception throws exception when it's not possible to get status due to any reasons
     */
    public boolean checkWalletSupported(@NonNull String modelName, @Nullable String countryCode,
                                        @NonNull String serviceType, @NonNull String partnerCode)
throws Exception {
        if (modelName == null || modelName.isEmpty()) {
            Log.e(TAG, "model name is Required parameter");
            throw new Exception("something went wrong (failed to get device model name)");
        }
        if (serviceType == null || serviceType.isEmpty()) {
            Log.e(TAG, "serviceType is Required parameter");
            throw new Exception("something went wrong (failed to get device serviceType)");
        }
        if (partnerCode == null || partnerCode.isEmpty()) {
            Log.e(TAG, "partnerCode is Required parameter");
            throw new Exception("something went wrong (failed to get device partnerCode)");
        }

        String urlString = makeUrl(modelName, countryCode, serviceType);
        Log.i(TAG, "urlString: " + urlString);

        try {
            URL url = new URL(urlString);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestProperty("partnerCode", partnerCode);
            connection.setRequestMethod("GET");

            int responseCode = connection.getResponseCode();
            Log.i(TAG, "responseCode: " + responseCode);

            BufferedReader bufferedReader;
            if (responseCode == 200) {
                bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            } else {
                bufferedReader = new BufferedReader(new InputStreamReader(connection.getErrorStream()));
            }

            StringBuilder sb = new StringBuilder();
            String inputline;
            while ((inputline = bufferedReader.readLine()) != null) {
                Log.i(TAG, inputline);
                sb.append(inputline);
            }

            connection.disconnect();
            bufferedReader.close();

            // parse result
            JSONObject jsonObject = new JSONObject(sb.toString());
            String resultCode = jsonObject.getString("resultCode");
            String resultMessage = jsonObject.getString("resultMessage");

            if ("0".equals(resultCode) && "SUCCESS".equals(resultMessage)) {
                return jsonObject.getBoolean("available");
            } else {
                throw new Exception("something went wrong, resultCode(" + resultCode +
                        "), resultMessage(" + resultMessage + ")");
            }

        } catch (IOException e) {
            Log.e(TAG, e.getMessage(), e);
            throw new Exception("something went wrong (IOException), " + e.getMessage());
        } catch (JSONException e) {
            Log.e(TAG, e.getMessage(), e);
            throw new Exception("something went wrong, receive wrong formatted response, " + e.getMessage());
        }
    }

    protected String makeUrl(@NonNull String modelName,
                             @Nullable String countryCode,
                             @NonNull String serviceType) {

        StringBuilder sb = new StringBuilder();
        sb.append(HOST).append('/');
        sb.append(PATH);
        sb.append('?').append("serviceType").append('=').append(serviceType);
        sb.append('&').append("modelName").append('=').append(modelName);

        if (countryCode != null && !countryCode.isEmpty()) {
            sb.append('&').append("countryCode").append('=').append(countryCode);
        }

        return sb.toString();
    }
}

Samsung Wallet via MMA 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

Guide to configuring wallet code for email and MMS messages

  1. Set up the Data Fetch Link, including the necessary server APIs to retrieve the wallet card data.
  2. Create a unique ‘reference ID’ for each transaction or request.
  3. Ensure the ‘reference ID’ is complex and secure to prevent the inference of sensitive information.
  4. 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 Wallet Cards guide on the Partners Portal.
  5. For card data, Samsung Wallet asks the partner system to provide card details through the server API.
  6. 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
* See Data Fetch Link

[Email on Web Button Link]

<a href="URL"> 
    <img src="IMAGE_URL"> 
    <img src="RD_IMPRESSION_URL" style="width:1px; height:1px;"> 
</a>
Attributes

 Description
URL
String

 (Required)
“Add to Wallet” link URL.
* See Data Transmit Link
* See Data Fetch 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.

3.4.2 Statistics Service

Samsung Wallet provides valuable statistical data related to the integrated services, accessible via the Partners Portal. This data helps track key events, such as button impressions and user interactions, to optimize your service and improve the overall user experience.

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.