Overview

Samsung Wallet Cards is an e-wallet service that allows customers using Samsung devices to add various digitized contents to Samsung Wallet. Users can add their tickets, coupons, boarding passes, and other types of data into Samsung Wallet using an "Add to Wallet" link given in online channels like application notifications, web pages, or email and social media messages.

This document describes how to implement Samsung Wallet Cards service features from the integration partner's point of view.

Getting started

Figure 1: Integration steps

Account

A Samsung account is necessary to manage your own service for Samsung Wallet. The account is used to sign up and sign in to the Partners Portal.

Onboarding

The interaction keys are issued during the service onboarding step. The partner manager needs to fill basic information of the company and card details on the Partners portal, choose the card type and template that fit their contents, and the portal will then provide keys such as Card ID and Partner ID. To ensure safe data communication, make sure to prepare security key factors. Samsung signs the provided CSR then deliver certificates used to create the secured data.

  • Refer to the "Samsung Wallet Partner Onboarding Guide" document for onboarding details and the Security chapter for more details about security.

Figure 2: Service onboarding

Add To Wallet

Partner managers have to configure the "Add to Wallet" button for their contents. The button must configure the link to the promised webpage with the specific format. The linked page initiates the basic process of storing cards on the Samsung Wallet service.

Every digitized content item on the "Add to Wallet" link is identified by a reference ID ("refId"). If the same reference ID is reused, the existing card is updated with new data without notice.

Samsung Wallet application does not cache every resource. No-cache web contents must be used for interfaces such as CDN. In other words, the application ignores work that gives a "304 Not Modified" response code.

Management

The stored wallet card contents on Samsung Wallet can be updated to predefined states. If partners want to manage the contents on Samsung Wallet, interaction between Samsung and partner servers is necessary.

Service flow

This chapter describes how to bring users' digitized content to Samsung Wallet. Once partner service onboarding is complete and card templates are ready, it is possible to add contents such as boarding passes, coupons and tickets into Samsung Wallet. See the service flow below.

Figure 3: General service flow

Preparation

Contents intended to be stored on Samsung Wallet must be tokenized as JWTs (JSON Web Token) when using the Data Transmit Link. When you plan to integrate the Samsung Wallet service, consider what environment the "Add to Wallet" button is displayed in, such as an application, website, MMS, or email.

Add to Wallet

Once users who want to store content click or tap the linked button, it initiates the process of adding the content to Samsung Wallet. Partners can consider the Data Fetch Link option when they provide full content data. Samsung notifies the partner of the result through a server interface called Send Card State. This works as callback for the "Add to Wallet" process, delivering events and a country code for the user wallet card. For interactions after storing contents on Samsung Wallet, server interfaces are needed.

Update Wallet Cards

If the wallet card contents should be updated by partners, they must call the Samsung server API. The path parameter "cc2" must be set to a value returned from the "Send Card State" callback API, which includes the "ADDED" event.

Card States

Wallet cards have several states for each content provider’s notifications and user actions. The state diagram below describes wallet card states from beginning to end.

State diagram

Figure 4: Card state diagram