Security Model at a Glance

This chapter defines the trust model, key material and JOSE tokens used by Samsung Wallet Cards. Complete the certificate and token work before generating test card links or exposing server-to-server endpoints.

Complete this chapter after onboarding and before implementing an Add to Samsung Wallet flow. It establishes the certificate, authorisation-token, and card-data-token requirements used by the integration chapters that follow.

This section provides a high-level view of the trust model and security artifacts used in Samsung Wallet Cards integrations.

Use this section as implementation context when preparing onboarding certificates, generating Authorization Tokens, generating cdata, or configuring secure partner/server API communication. The detailed construction rules are defined in the following Security subsections and should be referenced together with the relevant Add to Samsung Wallet or Samsung Server API flow.

Samsung Wallet Cards security is based on:

  • Certificate-based trust established during onboarding (CSR-based).

  • Signed JWT (JWS) for REST API authorisation and request binding.

  • JWS-wrapped JWE for confidential transport of card/authentication payloads (cdata).

  • Reference identifiers (refId / pdata) for indirection-based flows (Data Fetch Link).

Actors and Trust Anchors

This subsection defines the participating systems and the trust anchors used to establish and validate secure communication.

Actors

  • Partner Portal: Used by partners to configure service settings and register certificate-related onboarding information.

  • Partner Server (Backend): Generates security tokens (Authorization Token, cdata), exposes Partner APIs (e.g., Get Card Data), and receives callbacks/events.

  • Samsung Wallet Server (Backend): Validates partner-issued tokens, processes encrypted payloads, calls Partner APIs, and exposes Samsung Server APIs.

  • Client (Samsung Wallet App / Web JS): Initiates ATW/VWW flows carrying either cdata or pdata.

Trust Anchors

  • Partner Private Key: Used by the partner to sign JWS and (where applicable) to support encryption workflows.

  • Onboarding certificate artifacts: A certificate identifier (certificateId) and partner identifier (partnerId) are used to reference onboarding artifacts in tokens and selected API flows.

Security Artifacts and Where They Apply

This subsection summarizes the primary security artifacts and the interfaces where they are used.

Artifact

 Purpose

 Where used
Authorization Token (JWT / JWS)

 REST API authorisation + request binding

 REST API calls (both Samsung↔Partner directions) include the Authorization header.
Card Data Token (cdata) (JWS-wrapped JWE)

 Confidential + integrity-protected card payload transport

 ATW/VWW Data Transmit Link and web/app button flows.
Reference ID (refId / pdata)

 Indirection identifier for Data Fetch Link

 Data Fetch Link uses pdata(refId) and requires high-entropy/unpredictable generation.