Integrate 'Add to Samsung Wallet' button into partner services

Objective

Learn how to integrate the Add to Samsung Wallet functionality into partner services, enabling users to add boarding passes, tickets, coupons, gift cards, loyalty cards, and ID cards to Samsung Wallet.

Partnership Request

To create, manage, and monitor performance of wallet cards with the Samsung Wallet Partners Portal, you must become an official Samsung partner. Once done, you can fully utilize this Code Lab. You can learn more by visiting Samsung Wallet Partner Onboarding process, here in Samsung Developers.

NoteIn accordance with the applicable Samsung partner agreements, this Code Lab covers setup and use of the Samsung Wallet Partners Portal for purposes of integrating the Add To Samsung Wallet functionality into partner sites. The use cases and corresponding code samples included are representative examples only and should not be construed as either recommended or required.

Overview

Samsung Wallet is the secure, go-everywhere app for your essentials — credit cards, boarding passes, tickets, coupons, and more. All in one spot, all accessible with one swipe.
Users can conveniently access the Samsung Wallet by swiping it up from the bottom of the screen.
Various wallet cards of partners can be added to the Samsung Wallet, allowing users to quickly and easily access partners' contents, such as:

Boarding passes: Registered boarding passes can remind the user of boarding time and help during check-in. Depending on the integration level, it can provide status information updates related to flights, such as boarding gate changes or cancellations.
Tickets: Registered tickets can provide additional information about the event and an alarm before expiration. Ticket cards support event commodities for Performances, Sports, Movies, and Entrance.
Coupons: Registered coupons for various channels can provide alarms before expiration and update usage status.
Gift Cards: Gift cards are prepaid cards, also known as gift certificates, gift vouchers, or gift tokens. Gift cards in Wallet support provide balance and transaction history in real time.
Loyalties: Loyalty or membership cards serve as members’ certificates. The cards in Wallet show loyalty points.
ID Cards: The ID cards are for identification purposes, as well as for access authentication. It supports real-time status change as the user's permission is changed.

NoteDepending on your country or region, some card types are not supported.
If you need assistance, please contact us at developer.samsung.com/dashboard/support.

The image below shows the process of managing wallet cards:

For detailed description, see Manage Wallet Cards.

Set up your environment

You will need the following:

Latest Samsung Wallet from Galaxy Store
Samsung Galaxy device that supports Samsung Wallet
Samsung Wallet Partners Portal account
Internet browser, such as Chrome
IDEA such as IntelliJ
Key Pairs, Certificate from Samsung (see Encryption Setting)
- Partner Private Key
- Partner Certificate
- Samsung Certificate

Start your project

Open your internet browser and go to the following sample partner sites:

Boarding pass - https://codesandbox.io/s/wtr5s2
Ticket - https://codesandbox.io/s/c66tdq
Coupon - https://codesandbox.io/s/p2kym4
Gift Card - https://codesandbox.io/s/hhnr5m
Loyalty - https://codesandbox.io/s/7m78dt
ID Card - https://codesandbox.io/s/rsc226

Click Fork on the selected project to copy and modify the code.

Once done, the forked project has been automatically copied to your CodeSandbox account. Modify the index.html later for the Add To Samsung Wallet integration.

NoteThe next steps require a Samsung Wallet Partners Portal account. If you wish to check and test the complete code of these sample partner sites, you can jump to You're done! section of this Code Lab. Otherwise, you can proceed to learn the process of integrating Add to Samsung Wallet functionality.

Create wallet cards

Now, go to Samsung Wallet Partners Portal and sign in using your Samsung partner account.

On the left sidebar menu, click Wallet Cards > Create Wallet Card and enter the wallet card details of your chosen card type as below:

In Wallet Card Template, choose a card type and a sub type.

Select the card template. Then, click Done.

You can choose from various types of wallet card templates optimized for partners.

Once all the details are entered and the correct template is selected, click Save to set the wallet card status to Draft.

Launch wallet cards

You can launch and request activation of the cards by clicking the Launch button.

Upon agreeing to proceed, the Launch button text changes to Launched and the card status becomes Verifying.

Apply the Add to Samsung Wallet script

The Samsung Wallet Partners Portal includes generated Add to Samsung Wallet scripts for every wallet card created. These scripts can be copied and inserted into partner apps (Web and Android) or via Email/MMS.

Go to [Add to Wallet Script Guide] of the card(s) you created. Click Show to see the scripts for Web Integration and copy the script under Web Button (JS) code sample.

NoteA statistical image beacon is added to the script for tracking effect analysis.

Below are the generated Add to Samsung Wallet scripts of wallet cards created for this Code Lab.

Copy the script of your chosen card type:

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3fre4kmmboq00",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641030840334;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093501522138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641030840334;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093501522138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3fre4mp5mui00",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641034510350;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093588496138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641034510350;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093588496138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3fre4p0otdv00",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3gna29cgdi7g0",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3gna0sm71ts00",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

<script src="https://us-cdn-gpp.stg.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>
<div id="TARGET_ID"></div>
<script>
	samsungWallet.addButton({
		partnerCode: "4030093436155138240",
		cardId: "3gna1lkrjvng0",
		cdata: "${CARD DATA as JWT}",
		RDClickUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/click/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		RDImpressionUrl:
			"https://us-rd.mcsvc.samsung.com/statistics/impression/addtowlt?ep=C50C3754FEB24833B30C10B275BB6AB8;cc=GC;ii=1287098641019830286;co=4030093436155138240;cp=1288017491089625089;si=24;pg=101212967375212546;pi=Aqz68EBXSx6Mv9jsaZxzaA;tp=4030093644822138240;li=0",
		targetId: "TARGET_ID",
		buttonId: "BUTTON_ID",
	});
</script>

Paste the copied Add to Samsung Wallet script into the index.html file of the sample partner site. Then, add the attributes below, to the samsungWallet.addButton function.

target: "wallet",
showForced: true

target sets the button's name to Samsung Wallet ("wallet") or Samsung Pay ("pay"). By default, the value is "wallet".
showForced is a flag to show or hide the button. By default, the button is hidden. Otherwise, set the flag value to true.
To know the Samsung Wallet or Pay service availability for device and country, see Check service available device.

NoteIncluding the Javascript library in the head tag and adding the rest of the script to the body tag is recommended. Yet, it works if you paste it as is.

Generate and input the CData

The Add To Samsung Wallet script does not automatically include the CData (encrypted card data) as it requires encryption for security purposes. CData is the actual content data of wallet card and it has several formats based on card type.

Download the CData Generator and input your Parner ID

You can use the sample CData Generator created to serve the purpose of this Code Lab only. Download the CData Generation Sample Code.

Locate and open the downloaded file in IntelliJ IDEA. In the project folder, go to src > main > java > JwtGenerator.java. Input your Partner ID as PARTNER_CODE string value.

public class JwtGenerator {
    private static final String PARTNER_ID = "INSERT_YOUR_PARTNER_ID"; //same with partnerCode of Add to Samsung Wallet script

Build your card data

In JwtGenerator.java, uncomment the plainData that corresponds with your selected card type:

// Boarding pass
// String plainData = new PayloadUtil("sample/payload/BoardingPass.json").getSampleBoardingPass();
// Coupon
// String plainData = new PayloadUtil("sample/payload/Coupon.json").getSampleCoupon();
// Ticket
// String plainData = new PayloadUtil("sample/payload/Ticket.json").getSampleTicket();

TipYou can modify the CData Generator to function according to your requirements. For example, you can define the plainData to load and process card data types other than boarding pass, ticket, and coupon.

Go to resources > sample > payload and create a JSON file for your card data.

You can also use the Card Data Builder created for this Code Lab to edit your chosen sample card.

Copy the JSON format string to your JSON file after making your card data.

Secure Your Wallet Card

Next, go to resources > sample > securities.

Add your private key (Partner.key), partner certificate (Partner.crt), and Samsung certificate (Samsung.crt) in this directory to secure your Wallet card.

Partner Private Key: A key required to use with Partner Certificate to sign card data. This safe-keeping key can be created with Certificate Signing Request (CSR) when you joined the partner portal (See Encryption Setting).
Partner Certificate: A certificate required to sign or verify tokenized data. It will be attached to the partner sign-up completion mail.
Samsung Certificate: A certificate required to encrypt card data. It will be attached to the partner sign-up completion mail.

For details about these security factors, see Security.

Input the CData to Add to Samsung Wallet script

Build the project. Right-click on JwtGenerator class and click Run 'JwtGenerator.main()' to create the CData. Different CData must be created for each of the sample partner sites of this Code Lab.

NoteThe generated CData won't expire and can only be used for Code Lab testing. CData is valid only within 30 seconds after creation for security purposes in actual application.

Lastly, go back to the index.html of the chosen partner site and paste the generated CData to the cdata attribute value of the addButton sub-item.

Test the Add to Samsung Wallet button

With the Samsung Wallet app, you can test the Add to Samsung Wallet button functionality integrated into the sample partner sites directly on a mobile device. Access the URL provided by CodeSandbox on Samsung Internet or any browser.

If your device does not support Samsung Wallet such as desktop, laptop, or tablet, you can scan the QR Code to load the page on your Galaxy device.

Click the Samsung Wallet button in the sample partner site to add the card to the Samsung Wallet.

NoteYou can see and monitor wallet card statistics by going to the portal's Dashboard > Wallet Card Statistics.

You're done!

Congratulations! You have successfully achieved the goal of this Code Lab topic.
Now, you can integrate the Add to Samsung Wallet with your website by yourself! If you're having trouble, you may check the complete code below:

To learn more about Samsung Wallet, visit:
developer.samsung.com/wallet