Action Data

This section describes Action Data, which defines actions that can be associated with a wallet card during the Add to Wallet process.

Action Data enables a card to expose predefined actions that can be triggered from Samsung Wallet, allowing partners to define how users interact with the card beyond static presentation.

Overview

Action Data represents a structured definition of actions associated with a wallet card.
These actions are defined at card issuance time and become part of the card data registered in Samsung Wallet.

From the Add to Wallet perspective, Action Data:

• Is optional
• Is defined and delivered during the Add to Wallet process
• Applies uniformly to all cards that require actionable behavior

Applicability and API Usage

Action Data may be used across various card services to support different interaction scenarios.

Typical usage includes:

• Launching application-specific behavior
• Triggering partner-defined actions
• Supporting extended interaction flows initiated from the wallet

API	Role
Get Card Data (Partner API)	Return procedural data during issuance or refresh
Request Action (Partner API)	Primary carrier of Action Data
Send Card Event (Partner API)	Used by partners to report final lifecycle outcomes and terminal events of Wallet Card instances formerly referred to as Send Card State)
Update Notification (Samsung API)	Notify state transitions caused by completed actions

The presence of Action Data does not impose any requirement on how the action is executed at runtime.

Conceptual Model

Action as a Mediated Process

An Action represents a single logical step within a larger workflow.

Responsibilities

• Samsung Wallet Server
  o Initiates or forwards actions
  o Maintains transaction continuity
  o Does NOT own business logic or credentials

• Partner Server
  o Interprets actionType
  o Executes domain-specific logic
  o Returns next-step instructions or execution results

Idempotency is evaluated within the scope of a card program (partner context), primarily based on the card instance identifier (refId) and the requested actionType.
Detailed idempotency and deduplication rules are defined in Section "Idempotency and Request Deduplication"

Idempotency and Request Deduplication

Idempotency Identifier

All APIs defined in this specification use refId as the primary identifier of a card instance.
At minimum, the Wallet backend MUST guarantee idempotent handling of requests scoped by:

• refId
• actionType

This ensures that repeated requests caused by network retries do not result in duplicated side effects.

Idempotency Scope Claification

The refId value is guaranteed to be unique within a given card program (partner context), but is not guaranteed to be globally unique across different partners or programs.

Accordingly, Samsung Wallet evaluates idempotency within the card template scope. Internally, the effective idempotency key MAY be composed of:
(cardId, refId, actionType, actionInstanceId)

Partners are required to ensure uniqueness of refId within their own card template, but are not required to generate globally unique refId values across templates.

Recommended Idempotency Extension

To safely distinguish retries from logically new attempts, the following enhancement is RECOMMENDED:

• Each Action Data request SHOULD include a unique request-level identifier (e.g. actionInstanceId).
• Idempotency should be evaluated using the composite key: (refId, actionType, actionInstanceId)
• If actionInstanceId is not present, the server MUST fall back to (refId, actionType) and MUST NOT reject the request solely due to the absence of actionInstanceId.

Concurrent Action Handling

For a given refId, the server MUST define and enforce valid state transitions.

If an action is received that is not valid for the current state:

• The server MUST reject the request with HTTP 409 (STATE_CONFLICT).
• The response MUST include an appropriate error code describing the conflict.

Common Action Envelope

All actions are defined using a common envelope format.

The envelope includes:

• Action identifier
• Action type
• Action-specific payload

This structure allows Samsung Wallet to interpret and route actions in a consistent manner.

[Common Action Envelope Structure]

Field	Description
actionType String (≤ 32)	(Required) Identifier of the requested action.
actionPayload Object	(Required) Container for action-specific data.
actionPayload.actionDetails Object	(Required) Contextual metadata for the action in Section "actionDetails Object"
actionPayload.actionDetails.actionInstanceId String	(Optional) Unique request-level identifier for in Section "Idempotency and Request Deduplication"
actionPayload.{fields} Object	(Optional) Action-specific payload fields whose semantics are determined solely by actionType.

Normative Rules

• When actionType is present, actionPayload MUST be present.
• The semantic meaning of actionPayload.{fields} is determined solely by actionType.
• Unknown fields MUST be ignored, unless explicitly agreed by both parties.

actionDetails Object

The actionDetails object contains action-specific data required to perform the defined action.
The structure and contents of actionDetails depend on the action type and the intended use case.
The actionDetails object provides contextual metadata for an action.

Field	Description
timestamp String	(Optional) Unix epoch (milliseconds)
event String	(Optional) Logical event (REGISTER, UPDATE, REISSUE, etc.)
reason String	(Optional) Reason for triggering the action
level String	(Optional) INFO, WARN, ERROR
source String	(Optional) WALLET_APP, WALLET_SERVER, PARTNER_SERVER
code String	(Optional) Result or error code
message String	(Optional) Human-readable message

Action Usage Pattern

Action Data may be applied to different usage patterns depending on the card service.

These patterns define how Action Data is interpreted and used after the card is added to Samsung Wallet.

General Action Usage

In general usage scenarios, Action Data is used to define actions that can be initiated by the user from the wallet interface.

These actions are handled according to the action type and associated payload.

Access-Related Action Usage (Optional)

In some card services, Action Data may be used to support access-related interactions.

In such cases:

• Action Data may include access-related information
• The action definition may serve as an entry point for access-related processing

The inclusion of access-related Action Data during Add to Wallet does not, by itself, enable or activate access functionality.
Detailed access-specific behavior is described in the separate Access Guide.