Getting started

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.

Integration Steps

Partner 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 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 Samsung 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 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.

Preparation

• The contents intended to store on Samsung Wallet must be tokenized as JWT (JSON Web Token)when using Data Transmit Link.
• 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 for more details.
• Partners can consider the option*Data Fetch Link* when they provide full content data.
• Samsung will notify the result through server interface named Send Card State. This works as a 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 content provider’s notifications and user actions. The state diagram below describes wallet card states from beginning to end.

State diagram