Introduce Loyalty Cards to Your Application with Samsung Wallet

Introduction

The Samsung Wallet application lets you store cards that can be used for various purposes. If you want to provide reward points to your members, use the newly introduced loyalty card type, also known as a membership card.

In this article, we show how you can create a loyalty card in the Wallet Partners Portal. We also provide guidelines to implement the card, so that you can integrate the loyalty card into your application.

Card setup

Before adding the card to Samsung Wallet, create your card in the Wallet Partners Portal.

1. Log in to the Wallet Partners Portal.
2. Select Wallet Cards from the sidebar and then navigate to Create Wallet Card.
3. Follow the instructions in the General information section to complete the form.
4. Select “Loyalty card” from the Wallet Card Template menu.
5. Select your location from the Main (Headquarters) Location menu. If you get a “country not supported” error during a later phase, contact Samsung Developer Support.

After completing the form, save the card. All created cards are listed in the Manage Wallet Card view. You can view, edit, and delete the card information from this view. Finally, launch the card.

Card specification

Once a card is created in the Wallet Partners Portal, the card can be implemented in the partner application so that the user can purchase and use it. To do so, implement the “Add to Samsung Wallet” button in your application. For this purpose, generate a Card Data Token and create a final URL. This URL is integrated with the “Add to Samsung Wallet” button to add the card to Samsung Wallet.

For generating a Card Data Token, you need to define the Wallet card data. The loyalty card follows the specification below.

Name	Description
title	Required. The main title of the loyalty card. In the sample card, this field has the value “Card Title”.
eventId	Optional. The event ID. Use this ID to find and process an action to an event to all loyalty cards with the same ID.
groupingId	Optional. Identifier to group related cards.
subtitle1	Optional. An auxiliary field for showing supporting information about your card.
logoImage	Optional. Logo image displayed in the card item. The image size must be a maximum of 256 KB.
logoImage.darkUrl	Optional. Logo image displayed in the card item in dark mode. The image size must be a maximum of 256 KB.
logoImage.lightUrl	Optional. Logo image displayed in the card item in light mode. The image size must be a maximum of 256 KB.
providerName	Required. Provider name for the loyalty card.
startDate	Optional. Card validity start date. The date format is an epoch timestamp in milliseconds.
endDate	Optional. Card validity end date. The date format is an epoch timestamp in milliseconds.
locations	Optional. List of locations where the card can be used. This information can be used to provide location-based service and Samsung Wallet can use this information to show maps, place names and addresses. You can find more about the location field and the JSON format in the documentation.
noticeDesc	Optional. The Notices section can be used for any additional information for your card. You can use HTML tags without any CSS or script in this field. For the test card, this field contains the following list: <ul>    <li>Loyalty card notice. <a href=”https://www.samsung.com/”>Learn more.</a></li>    <li>Loyalty card notice.</li> </ul>
csInfo	Optional. Customer service information visible to the card user. This information is stored as key-value pairs with the following keys that correspond with the categories of information shown to the user: callemailwebsite
appLinkLogo	Required. Application link logo URL
appLinkName	Required. Application link name
appLinkData	Required. Application link destination URL
bgImage	Optional. Background image for the card
bgColor	Optional. Background color for the card. If you use bgColor together with bgImage, they are displayed in a predefined ratio. To only display a background image, omit the bgColor value. The following image shows the difference between a scenario where both bgImage and bgColor are used (left) to one where only bgImage is used (right).
fontColor	Optional. Font color on the card art.
barcode.value	Optional. Barcode data and serial number.
barcode.serialType	Optional. Barcode presentation type. For more details, see the Presentation Types (serialType) table.
barcode.ptFormat	Optional. Barcode presentation format. You can find all supported presentation formats in the Presentation Formats (ptFormat) table.
barcode.ptSubFormat	Optional. Barcode format. Some commonly used barcode formats are listed in the Barcode Formats (ptSubFormat) table.
barcode.errorCorrectionLevel	Optional. QR code error correction level. Four error correction levels are available: L/M/Q/H.
merchantId	Optional. Merchant identifier. Use this field if you have merchant ID.
merchantName	Optional. Merchant name.
amount	Optional. Total amount of points or initial balance. It is recommended to use a one-letter currency symbol. Use any of these formats: $1,000 or 1,000P.
balance	Optional. Available points or remaining balance. Use the same format as the amount field.

Card JSON example

The card data must be in the JSON format and needs to follow the specific structure.

The example below shows a card data sample that we have used to implement the loyalty card used in this content. Modify the card data as per your card information. Find more about the card data format in the Wallet Cards documentation.

{
    "card": {
        "type": "loyalty",
        "subType": "others",
        "data": [
            {
                "refId": "9400ae65-751b-4327-866c-37e8c228f1c4",
                "createdAt": 1672574400000,
                "updatedAt": 1672574400000,
                "language": "en",
                "attributes": {
                    "title": "Card Title",
                    "eventId": "event-001",
                    "groupingId": "group-001",
                    "orderId": "order-001",
                    "subtitle1": "Card Subtitle",
                    "logoImage": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg",
                    "logoImage.lightUrl": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg",
                    "logoImage.darkUrl": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg",
                    "providerName": "Provider Name",
                    "startDate": 1715533051242,
                    "endDate": 1715833051242,
                    "noticeDesc": "<ul><li>Loyalty card notice. <a href=\"https://www.samsung.com/\">Learn more.</a></li><li>Loyalty card notice.</li></ul>",
                    "csInfo": "{\"website\":\"https://homepage.com/cs\",\"email\":\"cs@email.com\",\"call\":\"555 333 111\"}",
                    "appLinkLogo": "https://play-lh.googleusercontent.com/ZnFa1roZ7hpv9j-jIAcBjmjuDl2x-FnuwTE0OYvbbcwvf5VPzOQQiKBXGK7d-APTvag=w240-h480-rw",
                    "appLinkName": "Loyalty Card Link",
                    "appLinkData": "www.samsung.com",
                    "bgImage": "https://djcpagh05u38x.cloudfront.net/wlt/us/stg/x1IWgocnRoqA5DmWPykfKQ/QUPknpwnTMqt7letkguFag.png",
                    "bgColor": "#ffffff",
                    "fontColor": "#ffffff",
                    "locations": "[{\"lat\":48.861614505643196,\"lng\":2.380811870098114,\"address\":\"38 Rue Saint-Maur, 75011 Paris\",\"name\":\"Atelier des Lumieres\"}]",
                    "amount": "$1,000",
                    "balance": "$100",
                    "barcode.value": "CS16138353212584806754FG1802",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptSubFormat": "QR_CODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.errorCorrectionLevel": "M",
                    "merchantId": "123344433",
                    "merchantName": "MerchantName"
                }
            }
        ]
    }
} 

Copychange color theme

Test with the Add to Wallet test tool

Once the card data specification details and the JSON structure of the loyalty card are established, we can test the “Add to Samsung Wallet” functionality.

First, we use the Add to Wallet Test Tool as this tool provides minimal card data in JSON format by default. After that, you can modify the JSON data and test the cards as you want.

Follow the instructions below to use the Add to Wallet Test Tool. For more details, refer to the Add to Wallet Test Tool documentation.

1. Sign in to the Add to Wallet Test Tool.
2. Enter the private key in the Enter Partner Private Key field.
3. Select the loyalty card we have created and then enter the JSON in the data field.
4. Finally add the card to Samsung Wallet.

Create JWT token

If testing with Add to Wallet Test Tool is successful, you can implement the “Add to Samsung Wallet” functionality with your application or website and handle the Card Data Token generation process on your server. Finally, generate the URL and integrate it with the “Add to Samsung Wallet” button.

For more details on the implementation, check out our Implementing “Add to Wallet” in an Android Application article, which is a complete guide to implementing the “Add to Samsung Wallet” button on an Android application and handling the Card Data Token generation process on the server side.

Conclusion

Once the implementation of both the application and server is completed, you can integrate the loyalty card with your production server and perform a full test on the loyalty card. After the test is done, an admin will check and set the card as Active.

While implementing your card, follow the steps shown in Seamlessly Integrate “Add to Wallet” for Samsung Wallet, as this article focuses on the common mistakes.

If you have any questions or face difficulties implementing the card, you can contact Samsung Developer Support.