Tutorials

Get Started with "Add to Samsung Wallet"

Choi, Jonghwa

Server Engineer, Digital Wallet team

Introduction

Smartphones have become an essential part of our everyday lives. Users are continually searching for more convenient ways to perform their tasks on their smartphones, driving them toward services with greater usability. As smartphones advance, our lives become simpler.

Galaxy users have completely embraced the convenience of paying with Samsung Pay, and no longer carry physical payment cards. This led to the evolution of Samsung Pay into Samsung Wallet, incorporating biometric-authentication-based security solutions and adding various features to replace conventional wallets. Since June 2022, Samsung Wallet has been expanding its service area based on the existing Samsung Pay launching countries.

This article aims to introduce Samsung Wallet and guide you through the integration process of the "Add to Samsung Wallet" feature, which allows you to digitize various content and offer them as Wallet Cards.

Add to Samsung Wallet Service

Let's delve deeper into the "Add to Samsung Wallet" feature. Digitized content registered in Samsung Wallet comes in the form of cards called Wallet Cards. Registering a Wallet Card is effortless: simply click the "Add to Samsung Wallet" button, and the card is stored securely on users’ Galaxy smartphones.

Add to Samsung Wallet Button and Wallet Card — "Add to Samsung Wallet" Button and Wallet Card

Notice
The benefits of using Wallet Cards can be found in the commercial video Forgetting Can Be Awesome.

Wallet Cards

The "Add to Samsung Wallet" service is an open platform that supports offering various types of content such as Wallet Cards. We are streamlining service integration with content providers across different regions and adding useful features.

Boarding Pass
Event Ticket
Loyalty
Gift Card
Coupon
ID Card
Generic Card
Pay As You Go (In Progress)
Reservation (In Progress)
Digital Key (In Progress)

Notice
Generic Card supports unstructured forms of cards.

Be a Samsung Wallet Partner

Partner Onboarding

To begin offering content through Samsung Wallet, you must first register as a partner on the Samsung Wallet Partner Portal. The integration process is detailed on the Samsung Developer Portal. To join the Samsung Wallet Partner Portal, create a Samsung Account that is used as the service administrator.

Text

Wallet Card Management

Once enrolled, you can create service cards on the Wallet Cards menu. Each card is assigned a Card ID representing the service, and you can set the card type and linking information. You can manage cards according to their status – test or live.

Notice
After completing all required forms for the Wallet Card, click the Launch button to request card activation.
Before providing the service to actual users, remember to turn off the 'Test Mode.'

How to Safely Secure User Data

Key Generation and Certificate Request

The registration process includes certificate exchange to securely transmit service data. Refer to the diagram and developer guide, Security Key & Certificate Creation Guide, to complete the certificate registration and partner enrollment smoothly.

Ensuring Data Security

To prevent forgery and leakage of user card data, secure tokenization processing is required. JSON Web Token (JWT), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. In particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used.

Process of Generating and Verifying Security Tokens

Notice
Depending on how partners provide content services to users, you can choose how to deliver data to the Samsung Wallet service.

Two Ways to Transfer Wallet Card Data

Add to Samsung Wallet Interface provides two methods for partners to deliver users digital content as wallet cards.

Data Transmit Link

The general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the Samsung Wallet service when the user clicks the button. As long as Samsung Wallet support is confirmed, you can generate a link containing the user's card data and configure the "Add to Samsung Wallet" button to run the link when pressed, either on an application or web page.

Data Fetch Link

Another method to transfer wallet card data is to include only the refId, which represents the user's content, in the "Add to Samsung Wallet" link and transmit it to the Samsung Wallet service. When a user clicks the "Add to Samsung Wallet" button, Samsung servers refer to the Get Card Data API information set on the Wallet Card and retrieve user content using the received refId to complete registration.

This method is suitable for providing user's data through email or MMS messages where static links cannot be avoided. There is an option to secure these static links.

Data Fetch Link (MMS/Email) — Data Fetch Process for Static Links

Setting Up Data Synchronization

On the partner portal, you can set up the wallet card information and configure the Server Interaction API that the content provider needs to prepare. This API is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on Samsung Wallet.

Register Wallet Cards

When a user card is added to Samsung Wallet, Samsung Wallet servers use the Send Card State API to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with Samsung Wallet.

Update Wallet Cards

Changes to the synchronization target content can be notified to the Samsung Wallet service through the Update notification API. Here, the value that distinguishes each piece of content is the refId that the partner must provide when registering the users’ wallet card.

Through the Get Card Data API, Samsung Wallet servers can check the latest content information any time.

Update Wallet Cards — If updates occur on the partner's side, UPDATED event notifications should be sent to the Samsung server

User Withdrawal — In case users withdraw content from the partner's side

Update Wallet Cards 3 — In case users delete cards from Samsung Wallet

Notice
Both servers should verify requests using the authorization header of the API request. This Authorization Token is in JWT format, familiar from card data security.

Effortless Wallet Card Registration with Just One Click

This feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or MMS message.

Javascript Library for Web Developers

We provide a JavaScript library and a user guide, Implement the Button, to help integrate your web pages.
Text

Creating Buttons and Links in Your App

For configuring buttons in applications, utilize the button Image Resources.

Providing Services via MMS, Email, or QR Codes

To provide services through fixed links, check out the details of the Data Fetch Link. These static links can also be used by scanning QR codes.

Experience the Service and Practice

You can experience service integration development using the CodeLab and use the Testing Tool to preregister the wallet cards created on the partner portal, which could be helpful.

Conclusion

We've looked at how to provide digital content through the "Add to Samsung Wallet" feature. We continuously update the guides on the developer portal, so please refer to them when preparing for integration.

The "Add to Samsung Wallet" service welcomes participation from content service partners and developers. For inquiries or Technical Support, please contact us through the form provided on the developer portal.

I hope this post has been helpful, and now I'll conclude my writing here.
Thank you.

This post was written based on the SDC23 Korea Session.