Overview
Samsung Wallet Cards is an e-wallet service allows customers using Samsung devices to clip various digitized contents on Samsung Wallet. Users can add their own 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 SNS messages.
This document describes how to implement Samsung Wallet Cards Service features in 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. Basically partner manager should fill basic information of company and card details on partner portal, should choose type and template which fit their contents, then can get the keys such as Card ID and Partner ID. To ensure safe data communication, don't miss preparing security key factors. Samsung will sign CSR they provided, then delivers certificates used to create secured data.
See a document 'Samsung Wallet Partner Onboarding Guide' for onboarding details.
See a chapter Security for details.
Add To Wallet
Partner managers have to configure 'Add to Samsung Wallet' button on their contents. The button must configure to link to the promised web page with the specific format. Then the linked page will initiate a basic process of storing cards on Samsung Wallet service.
See a chapter Implement the button for details.
The 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 any notice.
See a chapter Add to Wallet’ Interfaces for details.
Samsung Wallet app won't cache every resources. Must use no-cache web contents for the interfaces such like 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 both servers between Samsung and partner is necessary.
See a chapter Server interaction for details.
Service flow
This chapter describes the way to bring users' digitized content to Samsung Wallet. Once partner service onboarding has been done and templates are ready, it is possible to add contents such like 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) in case of Typical flow
- Considering what environments the button to be shown such as App, Web, MMS or Email when you plan to this service integration.
- See a chapter Implements the button for details.
Add to wallet
- Once users who want to store contents click/tab the linked button, it works every process for adding Samsung Wallet. See 'Add to Wallet’ Interfaces for details.
- Partners can consider the option Slim data flow by when they provide full content data.
- Samsung will notify the result thru 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 interaction after storing contents on Samsung Wallet, server interfaces are needed which is defined on a chapter Server interaction.
Update wallet cards
- If the wallet card contents should be updated by partners, they must call Samsung server API.
- A path parameter 'cc2' must be set the value bring from callback named 'Send Card State' API includes 'ADDED' event. See a chapter Samsung Server API for details.
- Update Notification is for a single content.
- Cancel Notification is for calling off the every users' wallet card contents related a specific event.
- Get Card Data payload has the same format of card information with the one of 'Add to wallet'.
- Send Card State also can have an event 'DELETED' to notify a wallet card deletion on Samsung Wallet by users.
Card States
Wallet cards can be several states by for each contents provider's notifications and user actions. The below state diagram describes Wallet cards states from the beginning to the end.
State diagram
