Introduce Loyalty Cards to Your Application with Samsung Wallet
M. A. Hasan Molla
Engineer, Samsung Developer Program
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.
- Log in to the Wallet Partners Portal.
- Select Wallet Cards from the sidebar and then navigate to Create Wallet Card.
- Follow the instructions in the General information section to complete the form.
- Select "Loyalty card" from the Wallet Card Template menu.
- 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:
|
| 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"
}
}
]
}
}
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.
- Sign in to the Add to Wallet Test Tool.
- Enter the private key in the Enter Partner Private Key field.
- Select the loyalty card we have created and then enter the JSON in the data field.
- 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.
