Overview
Samsung Wallet Cards is an e-wallet service that allows customers using Samsung devices to clip various digitized contents on Samsung Wallet. Users can add their ticket, coupon, boarding pass and other types of data into Samsung Wallet using an 'Add to Wallet' link via multiple online channels like App, Web, E-mail, or Social media messages.
This document describes how to implement Samsung Wallet Cards Service features from integration partners' point of view.
Getting started
Account
Samsung Account is necessary to manage your own service for Samsung Wallet. The account is used to sign- up/sign-in on Partner portal.
Onboarding
The interaction keys are issued from a service onboarding step. The partner manager should fill basic information of the company and card details on partner portal, choose the card type and template that fit their contents, which will then provide keys such as Card ID and Partner ID. To ensure safe data communication, make sure to prepare security key factors. Samsung will sign the provided CSR then deliver certificates used to create the secured data.
See the document 'Samsung Wallet Partner Onboarding Guide' for onboarding details.
See the chapter Security for more details.
Add To Wallet
Partner managers have to configure 'Add to Samsung Wallet' button on their contents. The button must configure the link to the promised web page with the specific format. The linked page will initiate a basic process of storing cards on Samsung Wallet service.
See the chapter Implement the button for more details.
Every digitized contents on 'Add-to-wallet' link is identified by a reference ID (refId). If the same reference ID is reused, the existing card will be updated with new data without notice.
See the chapter *Add to Wallet’ Interfaces*for more details.
Samsung Wallet app won't cache every resource. No-cache web contents must be used for interfaces such as CDN. In other words, the app won't consider work with '304 Not Modified'
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.
See the chapter Server interaction for more details.
Service flow
This chapter describes how to bring users' digitized content to Samsung Wallet. Once partner service onboarding complete and templates are ready, it is possible to add contents such as boarding passes, coupons and tickets into Samsung Wallet. See the service flow below.
Preparation
- The contents intended to store on Samsung Wallet must be tokenized as JWT (JSON Web Token) when using Typical flow
- Considering what environments the button will be displayed in such as App, Web, MMS or Email when you plan to integrate this service.
- See the chapter Implement the button for more details.
Add to wallet
-Once users who want to store contents click or tab the linked button, it initiates the process of adding to Samsung Wallet. See 'Add to Wallet’ Interfaces Interfaces for more details
- Partners can consider the option Slim data flow when they provide full content data.
- Samsung will notify the result through server interface named Send Card State. This works as callback for 'Add to Wallet' process delivering events and country code for the user wallet card.
- For interactions after storing contents on Samsung Wallet, server interfaces are needed which is defined on the chapter Server interaction.
Update wallet cards
- If the wallet card contents should be updated by partners, they must call Samsung server API.
- Path parameter 'cc2' must be set to the value brought from callback named 'Send Card State' API which includes 'ADDED' event. See a chapter Samsung Server API for more details.
- Update Notification is for single content.
- Cancel Notification is for calling off every user's wallet card contents related to a specific event.
- Get Card Data payload has the same format of *card information*as the one of 'Add to wallet'.
- Send Card State can also have an event 'DELETED' to notify a wallet card deletion on Samsung Wallet by users.
Card States
Wallet cards have several states for each contents provider’s notifications and user actions. The state diagram below describes Wallet cards’ states from the beginning to the end.
State diagram
