Bring Your Custom Card to Samsung Wallet
M. A. Hasan Molla
Engineer, Samsung Developer Program
Samsung Wallet is introducing a new feature called "Generic Card" for partners who cannot use other card types to fulfill their business requirements. This provides flexibility to modify various field labels for the card, according to the partners’ business needs.
Other cards, such as boarding passes and coupons serve a specific purpose, and their field labels cannot be modified. However, with a generic card, the label can be modified so it can be used for multiple purposes.
In this article, you learn how to modify a generic card to use it as an insurance card. We will explain the details specification with example of the generic card. At the end of the article a guide will be provided to implement this card for your reference, to help you modify your generic card according to your needs.
Card setup
Before you begin creating a new card template, log in to the Samsung Wallet Partner site and create a generic card.
- Log in to the Samsung Wallet Partner site.
- Go to the Wallet Cards and then Create Wallet Card. For more details about creating a card, check the Manage Wallet Cards documentation.
- Select Generic Card from the available card templates.
- Modify the card information.
When you have finished editing card information, launch the card to complete card setup. For more information on how to launch the card, see Launch Wallet Cards.
Template editor
Use the template editor to modify the card template.
- From the "CardArt" view, you can modify the card color, set a background image or change the logo image properties.
- From the "Enlarge" view, you can modify the {{text1}} and {{text2}} labels. However, only the label itself can be changed in the Template Editor. To set the label value, you need to update the JSON file.
- From the "Detail" view, you can modify the "TextGroup" and "AppLink" properties. Modify the text label according to your needs. It is also possible to add new text fields, with a maximum of 12 text fields allowed.
After every modification, click Save. Finally, apply all changes by clicking Apply. If you want to preview your changes, just click Preview.
Add to Samsung Wallet
Now that the card has been created in the site, it is ready to be distributed to fulfill your business needs.
- Implement the "Add to Samsung Wallet" functionality to the platform where you are planning to distribute the cards.
- When users click "Add to Samsung Wallet," the card is added to the Wallet application on the user’s Galaxy device. This functionality can be added through the application/mobile web, MMS, or email.
- Additionally, you can use a QR code on a computer web browser and KIOSK. Samsung provides a Codelab guide for developers so that they can easily understand the implementation. For additional information on the Codelab guide, read Utilize the Add to Samsung Wallet service for digital cards. Further details can also be found in the Implementing ATW button documentation.
Card specifications
To complete the "Add to Samsung Wallet" button implementation, you must generate the Card Data token and create a final URL. For more information, see Add to Samsung Wallet. Let’s start by reviewing the generic card specifications to generate the Card Data token. The generic card follows the specifications below. For more information on them, see the Generic Card section.
| Name | Description |
|---|---|
| Title | The main title of the generic card. In the sample card, the title is "Card Title." In the image below, the title is "Insurance Identification Card." 
|
| Subtitle | The subtitle of the generic card. In the sample card, it is "Card Subtitle". |
| providerName | Use this field to set the card provider name. For more information, check the Card JSON Example below. However, the provider name depends on your card type and should be modified accordingly. |
| eventId | Enter an ID as an event identifier. In case your card is prepaid, for example a gift card, or if you have vouchers to events, such as concerts, it is possible to define an event ID. For instance: "event-001". |
| groupingId | Enter an identifier to group related cards. |
| startDate | Enter the starting date and the epoch timestamp in milliseconds. |
| startDate.relativeNotiTime | Enter the amount of time within which you want to provide a notification to the user. The notification time is the relative time from the startDate. The value can be up to 2880 milliseconds. |
| endDate | Enter the end date and the epoch timestamp in milliseconds. |
| endDate.relativeNotiTime | Enter the amount of time within which you want to provide a notification to the user. The notification time is the relative time from the endDate. The value can be up to 2880 milliseconds. |
| logoImage | Set the logo image URL. The file size must not exceed 256 KB. Also this image can be set from the Template Editor.
|
| logoImage.darkUrl | Set the logo image URL for the dark mode. The file size must not exceed 256 KB. |
| logoImage.lightUrl | Set the logo image URL for the light mode. The file size must not exceed 256 KB. |
| bgImage | Set the background image URL. The file size must not exceed 512 KB. |
| text{i} | Set the label-text value that should be displayed for each field containing the details of your card. The label is defined in the Template Editor, shown in the image below.  To set the value of the label, update the JSON file. 
|
| image{i} | Enter the image URL, such as: "https://www.samsung.com/images/image1.png". This URL is just an example, you must update it according to your needs. This field only works in Generic Card Type3. We have used a Type1 card in the example. So this field in the example JSON has no effect on the card. You can find all three card type sample UIs here. |
| image{i}.lightUrl | Enter the image URL in light mode, such as: "https://www.samsung.com/images/light.png". This URL is just an example, you must update it according to your needs. |
| image{i}.darkUrl | Enter the image URL in dark mode, such as: "https://www.samsung.com/images/dark.png". This URL is just an example, you must update it according to your needs. |
| serial{i} | Set the serial for barcode or QR code. |
| serial{i}.serialType | Serial presentation type. For more information on the Presentation Types (serialType), see References. |
| serial{i}.ptFormat | Set the presentation format. For more details on the presentation formats (ptFormat), see References. |
| serial{i}.ptSubFormat | Set the presentation subformat here. For more details on the barcode formats (ptSubFormat), see References. |
| serial{i}.errorCorrectionLevel | Set the error correction levels in this field. The amount of redundancy or error correction data included in the code varies. QR codes offer four levels of error correction: L, M, Q, and H. The QR field looks like the following in your card:
|
| privacyModeYn | Set the user authentication if required. Set the value to "Y" or "N" |
| bgColor | Set the card art color. |
| fontColor | Set the card art font color. |
| noNetworkSupportYn | Set the value to "Y" to open the wallet card when under the "No network" status. Otherwise, set the value to "N" |
| noticeDesc | Set the the notice description here. See the image below of how it is added to card. 
|
| appLinkLogo | Add the application link logo URL in this field. |
| appLinkName | Add the application link name in this field. |
| appLinkData | Add the application link URL in this field.
|
| locations | List of locations where the card will be used. This information can be used to provide location-based services. Samsung Wallet can use this information to show maps, names of places, and addresses. For more information on the locations field and JSON format, check References. 
|
Card JSON example
In previous sections, you have learned about the card specifications. Next, let’s implement the generic card fields according to your needs. In this section, as the aim is to create an insurance card, you must use the fields accordingly.
Samsung provides a specifically formatted JSON structure. You need to configure the card data objects within the structure’s data array. For more details, see the Generic Card section.
{
"card": {
"type": "generic",
"subType": "others",
"data": [
{
"createdAt": 1709712961000,
"updatedAt": 1709712961000,
"language": "en ",
"refId": "933533e1-9284-461c-905f-bc177526a8d1",
"attributes": {
"title": "Insurance Identification Card",
"subtitle": "Insurance Card",
"providerName": "Samsung Insurance Co.",
"eventId": "1",
"groupingId":"1",
"startDate": 1731299205000,
"startDate.relativeNotiTime": 500,
"endDate": 1731320805000,
"endDate.relativeNotiTime": 400,
"logoImage": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png",
"logoImage.darkUrl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png",
"logoImage.lightUrl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png",
"bgImage": "",
"text1": "1234567",
"text2": "Samsung Insurance Co.",
"text3": "Jaqueline M",
"text4": "Samsung Motors 2014 Galaxy5",
"text5": "11SAM23SUNG3T",
"text6": "(031)000-1235",
"image1": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png",
"image1.darkUrl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png",
"image1.lightUrl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png",
"serial1.value": ">1180MM2241B7C 0000000000000298060000000000 0 090870907 ",
"serial1.serialType": "QRCODE",
"serial1.ptFormat": "QRCODE",
"serial1.ptSubFormat": "QR_CODE",
"serial1.errorCorrectionLevel": "M",
"privacyModeYn": "Y",
"bgColor": "#3396ff",
"fontColor": "#FFFFFF",
"noNetworkSupportYn": "N",
"noticeDesc": "{\"count\":2,\"info\":[{\"title\":\"NOTICE1\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]},{\"title\":\"NOTICE2\",\"content\":[\"DESCRIPTION1\",\"DESCRIPTION2\"]}]}",
"appLinkLogo": "https://www.samsung.com/logo.png",
"appLinkData": "https://www.samsung.com/",
"appLinkName": "Samsung Insurance Co.",
"locations": "[{\"lat\": 37.2573276, \"lng\": 127.0528215, \"address\": \"Suwon\", \"name\": \"Digital City\"}]"
}
}
]
}
}
Generic card testing with the "Add to Wallet" test tool
Now, you can test the generic card with the "Add to Wallet" test tool provided by Samsung. Just follow these steps:
- Sign in to the Add to Wallet test tool. For more information, see the Samsung Wallet Test Tool.
- Enter the private key in the "Enter Partner Private Key" field.
- In this tool, you find all cards that you have created from the Samsung Wallet Partner site in the "Select Card" section. For more information, see the Samsung Wallet Partner site.
- Select the generic card that you have just created.
- Now select JSON from the Data field and modify the existing JSON data fields according to the card specification details.
- After modifying the JSON data fields, check if the JSON is valid.
- Finally, if the private key is valid, the "Add to Samsung Wallet" button becomes active at the bottom of the page. Then, just click Add to Samsung Wallet to finish adding the generic card.
If you use the provided example JSON and add the card to the wallet, the card looks like the following:
Server integration
In this step, server configuration is needed because the generated JWT token expires after 30 seconds. Developers are advised to only generate this token after a user has clicked the "Add to Wallet" button. As you have already performed testing with the "Add to Wallet" test tool, you need to configure your server.
For more information on the implementation of both the "Add to Samsung Wallet" button and server-side logic, see Implementing "Add to Wallet" in an Android Application. This article explains how you can distribute your card with your Android application and how to generate the JWT token at runtime, after pressing the "Add to Samsung Wallet" button.
Conclusion
You have now learned the basics for how to set up a generic card and test it for your business needs. In case you have further questions, contact Samsung Developer Support.
