Implementing ATW button

For Samsung Wallet integration, you need to insert an "Add To Wallet" script into your system. To implement an "Add to Wallet" button, follow the procedure below:

  1. First, proceed with script composition with the sample script on the Partners Portal or refer to the Integration sample code.
  2. Create the tokenized card data (Cdata). Card data is the actual content of the wallet card and it has several formats based on the card type. Refer to the CData Generation Sample Code for details.

For "Add to Wallet" integration, you may also need some base data. You can find that and other necessary information on Partners Portal.

Samsung Wallet on the Web

This section explains how to implement an "Add to Wallet" button using JavaScript in a 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're 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 Type Required Description
cardid String Y Wallet card identifier
* Value granted from the Partners Portal.
cdata String Y Encrypted card object (JSON).
* This field needs to be encrypted.
* Refer to Security for more details.
partnercode String Y Partner code.
* Value granted from the Partners portal.
buttonid String Y DOM element ID for the "Add to Wallet" web button for Samsung Wallet
buttontype String N "Add to Wallet" button type.
[ "btnSW" / "btnATSW", default : btnSW ]
* Refer to Image resources for more details.
inline String N Flag to display the "Add to Wallet" image button in one-line format.
Default: true (one-line).
locale String N Locale of the "Add to Wallet" image button.
* Refer to Image resources for more details.
rdclickurl String Y URL for logging a button click event.
* Value granted from the Partners Portal.
rdimpressionurl String Y URL for logging a button impression event.
* Value granted from the Partners Portal.
showforced String N Flag to force the "Add to Wallet" button to be displayed.
Default: false.
mediatheme String N 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)

 N Load the button with custom style
onshowbutton Function N Callback handler function for the button’s on-show event
onclickbutton Function N Callback handler function for the button’s on-click event.
If you register the handler function, you must return a callback or promise value.
* Refer to Usage of onClickButton Handler for more details.

samsungWallet.addButton Function

This function allows you to explicitly render the Samsung Wallet API for the "Add to Wallet" web button.

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

Unlike the samsung:wallet HTML tag, you must use camelCase in the button attributes in function case.

Attributes Type Required Description
cardId String Y Wallet card identifier.
* Value granted from the Partners Portal.
cdata String Y Encrypted card object (JSON).
* This field needs to be encrypted.
* Refer to Security for more details.
partnerCode String Y Partner code.
* Value granted from the Partners Portal.
targetId String Y DOM (Document Object Model) Element ID to place the "Add to Wallet" web button for Samsung Wallet
buttonId String Y DOM Element ID for the "Add to Wallet" web button for Samsung Wallet
buttonType String N "Add to Wallet" button type ("btnSW" and "btnATSW")
Default : btnSW
* Refer to Image resources for more details.
inline String N Flag to display the "Add to Wallet" image button in one-line format.
Default: true (one-line).
locale String N Locale of the "Add to Wallet" image button.
* Refer to Image resources for more details.
RDClickUrl String Y URL of logging a button click event.
* Value granted from the Partners Portal.
RDImpressionUrl String Y URL of logging a button impression event.
*Value granted from the Partners Portal.
showForced String N Flag to force the "Add to Wallet" button to be displayed.
Default: false.
mediaTheme String N 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) N Load the button with a custom style
onShowButton Function N Callback handler function for the button’s on-show event.
onClickButton Function N Callback handler function for the button’s on-click event.
If you register the handler function, you must return a callback or promise value.
* Refer to Usage of onClickButton Handler for more details.

Usage of onClickButton Handler

You can choose whether to proceed with the next "Add to Wallet" step using a promise or a callback function, if you register a callback handler in onClickButton. 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 Type Required Description
options Button attributes N Attributes of the current button
callback Function N Callback function to pass the flag to proceed.
Default: false.
(Promise resolve) Function N Promise-resolved value to pass the flag to proceed
Default: false.

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

By executing a callback function with a flag, you can proceed to the next 'Add to Wallet' process.

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

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

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 a Native Application

The following outline explains how to implement the "Add to Wallet" button on a native application.

  1. Get button graphic resources from a repository depending on your service environment. For more information, refer to Image resources.
  2. Check availability by calling the "Check service available devices" APO, then determine whether to show up the "Add to Wallet" button on the user device.
    A. If "available" on response has "true" -> SUPPORT
    B. If has "false" -> NOT SUPPORT
  3. Implement a JWT web link on the button triggered action.

App Button Reference

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 refer to 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 on an MMS/Email

The following guides how to configure wallet code on email and MMS messages.

  1. Implement the Data Fetch Link process, including server APIs. You need to create a unique "reference ID". For security reasons, make sure the "reference ID" is complex enough that no important information can be inferred.
  2. Deliver a message including the web link through the chosen message platform. For MMS, the designed link shows up as a "Smart Suggestion" on Samsung devices. You can find a sample web link on the Wallet Cards guide on the Partners Portal.
  3. For card data, Samsung Wallet asks the partner system to provide card details through the server API.
  4. Duplicate requests are prohibited on the same device.

Link to “Add to Wallet” on an MMS/Email

You can add an “Add to Wallet” web button even 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 Type Required Description
URL String Y “Add to Wallet” link URL.
* Refer to Data Transmit Link for more details.
* Refer to Data Fetch Link for more details.

Email on Web Button Link

<a href="URL">
    <img src="IMAGE_URL">
    <img src="RD_IMPRESSION_URL" style="width:1px; height:1px;">
</a>
Attributes Type Required Description
URL String Y “Add to Wallet” link URL.
* Refer to Data Transmit Link for more details.
* Refer to Data Fetch Link for more details.
IMAGE_URL String Y Button’s image resource URL.
* Refer to Image resources for more details.
RD_IMPRESSION_URL String Y Impressions logging URL.
* Value granted from the Partners Portal.

Statistics Service

Samsung Wallet serves useful statistics data of the integrated service on the Partners Portal. The data configured by making simple API calls for each event such as button impression and click. These are necessary to provide better services as well.

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