Overview

This section describes the Add to Samsung Wallet process, which enables partners to register cards in Samsung Wallet and define their baseline data, presentation, and capabilities.

Add to Wallet is the standard and mandatory process for publishing wallet cards. The lifecycle, portal operations, and REST APIs described in this section apply to all supported card types.

Most card services rely solely on the Add to Wallet process and do not require any additional feature integration.

Scope

Add to Samsung Wallet defines:

• Card registration and lifecycle management
• Template configuration and publication
• Card metadata, layout, and Action Data definition
• Capability declaration, including optional NFC support

The behaviors and state transitions described in this section represent the canonical integration path for wallet cards.

Optional Feature Extensions

Some card programs may support additional device-level capabilities beyond standard card presentation.
Where applicable, such features are treated as optional extensions to the base Add to Wallet process.
Detailed technical and operational requirements for those extensions are described in separate documentation.

Service Flow

The Add to Samsung Wallet (ATW) service provides a set of interfaces that enable users to easily add digital content to their Samsung Wallet, enhancing convenience by allowing users to store, manage, and access items such as loyalty cards, tickets, boarding passes, and more directly within the app. The service involves several steps, from content preparation to updates and managing card states.

Preparation

Steps to prepare

• 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.

Refer to Implement the button section for more details.

Add to Wallet

Steps to 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.
• If you are providing the full pass content, use the Data Transmit Link option.

• Samsung will notify the result through server interface named Send Card State(Send Card Event). This works as a callback for 'Add to Wallet' process delivering events and country code for the user wallet card.
• To handle interactions after storing content in Samsung Wallet, server interfaces are required. These interfaces are defined in the Updating Wallet Card Specs.
• See API Guidelines for more details.

Update Wallet Cards

Steps to update wallet cards

Partners may need to update or modify the content stored in Samsung Wallet. For example, a user might accumulate more loyalty points, or flight details may change. To update the wallet card content, partners must call the Samsung Server API.

• The cc2 path parameter must match the cc2 value from the Send Card State(Send Card Event) API notification triggered by the ADDED event.
• Refer to Samsung Server API section for more details.
• Update Notification is for single content.
• Cancel Notification is for calling off every user's wallet card content 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(Send Card Event) can also have an event 'DELETED' to notify a wallet card deletion on Samsung Wallet by users.
• Gift cards and Generic cards currently do not support Update Notification functionality.

Card States

Wallet cards within Samsung Wallet can have various states (e.g., active, expired, used, suspended) for each content provider’s notifications and user actions.

The state diagram below describes wallet card states from beginning to end.

State diagram