Card Lifecycle

Adding a card is the beginning of the integration, not the end. This chapter covers the interfaces and operational behaviour required to keep a card accurate throughout its lifetime.

At minimum, partners should be able to correlate the ADDED event with their refId, store the callback routing information returned by Samsung Wallet, handle duplicate events safely and retrieve or update card content when their chosen flow requires it.

A card instance continues to exchange state and content after it is added. Design this lifecycle before launch so that the partner can distinguish a completed add, a content refresh, a cancellation, expiry and user deletion.

Lifecycle Flow

1. The user opens an ATW entry point and Samsung Wallet resolves the card through the selected add method.
2. Samsung reports the result through Send Card State (Send Card Event).
3. The partner correlates the event with its Card ID and refId and retains the routing values required for later Samsung API calls.
4. When content changes, the partner calls Update Notification. Samsung can then retrieve the current card data from the partner.
5. When the card is no longer valid, the partner applies the appropriate expiry, redemption or Cancel Notification behaviour for the card type.
6. Samsung can report subsequent user or system state changes, including deletion, through the event callback.

The cc2 path parameter used for Samsung lifecycle APIs must match the value supplied in the ADDED event. The Get Card Data response uses the same card information model as the add flow.

Gift cards and Generic cards currently do not support Update Notification.

Card States

Wallet card states communicate lifecycle changes caused by partner updates, user actions and Samsung Wallet processing. Partners should store the latest accepted state per logical card instance and process event delivery idempotently.

The following diagram shows the supported state transitions.

Registration Uniqueness and Duplicate Handling

Samsung Wallet applies duplicate protection to prevent unintended repeated registration attempts for the same card instance on the same device.

Normative rules

• The partner shall use a stable and unique refId for each logical card instance within the same card programme.
• Repeated registration attempts for the same card instance on the same device may be rejected or coalesced by Samsung Wallet to preserve data integrity.
• Partners must treat repeated user actions, page refreshes, link re-entry and network retries as potentially duplicate-triggering conditions.

Partner responsibilities

• Design Add to Samsung Wallet operations and callbacks to be idempotent.
• Avoid generating multiple logically equivalent registration requests for the same user and card instance while a previous request is still in progress.
• Handle retries without assuming that every request creates a new card instance.
• Before treating the absence of a new card as a failure, check whether the same request was already accepted or remains in progress.

This protection applies to the same logical card instance on the same device. Cross-device registration policy, including phone and wearable combinations under the same Samsung Account, may depend on card programme policy and separate Samsung approval.

Device Information

The standard Data Transmit and Data Fetch flows do not guarantee device-model information in the card provisioning payload. Do not make business-critical provisioning decisions from an assumed model name or hardware identifier.

If compatibility must be checked before presenting or invoking the entry point, use Check Service Availability. A flow that requires additional device properties must be agreed during onboarding.