Implement the button

For Wallet integration, you need to insert ‘Add To Wallet’ script into your system. We usually follow the procedures below to implement the ‘Add to Wallet’ button.

First, proceed with script composition with the sample script in Partner portal or refer to the Integration sample code.

Second, create tokenized card data (cdata) and insert the data token into the script above. Card data is the actual content data of wallet cards and has several formats based on card type. Please refer to Generate_Cdata Sample Code for detail.

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.

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 device that supports the Samsung Wallet.

To automatically parse <samsung:wallet> HTML tags on load, 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

Attributes	Type	Mandatory	Description
cardid	String	Y	Wallet card identifier * the value granted from partner portal
cdata	String	Y	Encrypted Card object (JSON). * This field needs to be encrypted. * See Security.
partnercode	String	Y	Partner Code. * the value granted from partner portal
buttonid	String	Y	DOM Element ID for the 'Add to Wallet' web button's for Samsung Wallet.
buttontype	String	N	'Add To Wallet' button type. [ "btnSW" / "btnATSW", default : btnSW ] * See Image resources
inline	String	N	Display one-line of 'Add To Wallet' image button. (default: true (one-line))
locale	String	N	locale of 'Add To Wallet' image button. * See Image resources
rdclickurl	String	Y	URL of logging a button click event. * the value granted from partner portal
rdimpressionurl	String	Y	URL of logging a button impression event. * the value granted from partner portal
showforced	String	N	Flag to show “Add To Wallet” button forced.(default : false)
mediatheme	String	N	Load button’s resources from media theme policy. [“default” / “inversion” / “lightonly” / “darkonly”, default: default] *default : load button’s theme by prefers-color-scheme policy *inversion : load inversion of default button’s theme. *lightonly : load light theme of default button. *darkonly : load dark theme of default button.
style	String (CSSStyleDeclaration)	N	Load button with custom style
target	String	N	Option to choose button’s target name [“PAY” / “WALLET”, default : “WALLET”]
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. * See Usage of onClickButton Handler

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 samsung:wallet HTML Tag case, You must use camelcase in the button attributes in function case.

Attributes	Type	Mandatory	Description
cardId	String	Y	Wallet card identifier * the value granted from partner portal
cdata	String	Y	Encrypted Card object (JSON). * This field needs to be encrypted. * See Security.
partnerCode	String	Y	Partner Code. * the value granted from partner 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's for Samsung Wallet.
buttonType	String	N	'Add To Wallet' button type. [ "btnSW" / "btnATSW", default : btnSW ] * See Image resources
inline	String	N	Display one-line of 'Add To Wallet' image button. (default: true (one-line))
locale	String	N	locale of 'Add To Wallet' image button. * See Image resources
RDClickUrl	String	Y	URL of logging a button click event. * the value granted from partner portal
RDImpressionUrl	String	Y	URL of logging a button impression event. * the value granted from partner portal
showForced	String	N	Flag to show “Add To Wallet” button forced. (default : false)
mediaTheme	String	N	Load button’s resources from media theme policy. [“default” / “inversion” / “lightonly” / “darkonly”, default: default] *default : load button’s theme by prefers-color-scheme policy *inversion : load inversion of default button’s theme. *lightonly : load light theme of default button. *darkonly : load dark theme of default button.
style	Object (CSSStyleDeclaration)	N	Load button with custom style
target	String	N	Option to choose button’s target name [“PAY” / “WALLET”, default : “WALLET”]
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. * See Usage of onClickButton Handler

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. And the function’s parameters are defined as follows.
And we recommend that add the generating process of the JWT cdata (add cdata to options.cdata) in this handler because of the expiration time of the cdata.

Attributes	Type	Mandatory	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. (under ES5)

By executing a callback function with 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. (ES6)

By returning a promise with 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

The following outline explains how to implement 'Add to Wallet' button on native app.

1. Get button graphic resources from a repository depending on your service environment.
   A. See Image resources.
2. Check availability by calling API 'Check service available devices', then determine whether showing up 'Add to Wallet' button on the user device.
   A. If 'available' on response has 'true' -> SUPPORT
   B. it has 'false' -> NOT SUPPORT
3. Implements 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";  // (mandatory, fixed) for Samsung Wallet
            final String partnerCode = null;      // (mandatory)

            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 mandatory parameter");
            throw new Exception("something went wrong (failed to get device model name)");
        }
        if (serviceType == null || serviceType.isEmpty()) {
            Log.e(TAG, "serviceType is mandatory parameter");
            throw new Exception("something went wrong (failed to get device serviceType)");
        }
        if (partnerCode == null || partnerCode.isEmpty()) {
            Log.e(TAG, "partnerCode is mandatory 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 the MMS/Email

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

1. Implement the process 'Slim data flow' including Server APIs. You need to create a unique 'reference ID'. Please make sure 'reference ID' is complex enough, so that its logic can't be guessed for security reasons.
2. Deliver messages including the web link via message platforms. In MMS case, the designed link will show up as ‘Smart Suggestion’ on Samsung Devices. You can find a sample web link on Partner portal’s Wallet card page.
3. As for card data, Samsung wallet will ask the partner system to provide card detail through server API.
4. Duplicate requests will be prohibited on the same device.

Link to 'Add to Wallet' on the 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 e-mail.

* These methods do not support controlling 'Add to Wallet' button visibility.

MMS Link

URL Link: URL

Attributes	Type	Mandatory	Description
URL	String	Y	Add to wallet link URL * See Typical flow. * See Slim data flow

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	Mandatory	Description
URL	String	Y	Add to wallet link URL * See Typical flow. * See Slim data flow
IMAGE_URL	String	Y	Button’s image resource URL * See Image resources
RD_IMPRESSION_URL	String	Y	Logging URL for impression * the value granted from partner portal

Statistics Service

Samsung Wallet serves useful statistics data of the integrated service on partner portal. The data configured by calling simple API calls for each events such as button impression and click. These are necessary to provide the 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 events in situations:
- impression: When ‘Add to Wallet’ button has been showed
- click: When ‘Add to Wallet’ button has been clicked

{parameters}:
Includes key factors to figure out the service.

{channel}:
- app: Samsung Wallet button on the App
- web: Samsung Wallet button on the Web
- email: Samsung Wallet button on the Email