Card Data Token (cdata) — JWS-wrapped JWE

This section defines cdata, a tokenized container that securely transports card/authentication payloads with confidentiality (JWE) and integrity/authenticity (outer JWS).

Where cdata Is Used

This subsection defines the interfaces where cdata may appear.

cdata is used in:

  • ATW/VWW Data Transmit Link flows (e.g., ...#Clip?cdata={cdata}).

  • Web/app button flows carrying an encrypted card object payload.

Token Lifetime and Generation Timing

This subsection defines the time sensitivity of cdata and recommended generation timing.

cdata is time-sensitive and SHOULD be used within 30 seconds after creation. It SHOULD be generated immediately when the user actually attempts Add to Samsung Wallet (for example, right after the user clicks the button) to avoid expiry before use. Pre-generating cdata at page render time is not recommended because it may cause timeout or validation errors before the token is processed.

Data Structures (cdata)

Outer JWS Header (cdata)

This subsection defines the JWS header for the outer signature wrapper.

Field

 Description
alg
String(16)

 (Required)
Signing algorithm
e.g., RS256
cty
String(16)

 (Required)
Content type
Set as "CARD"
ver
String(4)

 (Required)
Token version
Set as "3"
certificateId
String(64)

 (Required)
Certificate identifier.
Assigned after CSR/certificate registration and can be checked in the Partner Portal.
If multiple certificates are registered, use the certificateId that corresponds to the certificate used
for the request or token.
partnerId
String(16)

 (Required)
Partner identifier assigned at Partner Portal registration (same as partnerCode).
utc
Long(13)

 (Required)
Creation time (epoch ms)
Used for expiry / anti-replay time checks.
i.e., UTC+0

Inner JWE Header (cdata)

This subsection defines the header for the encrypted payload.

Field

 Description
alg
String(16)

 (Required)
Key management algorithm
e.g., RSA1_5
enc
String(16)

 (Required)
Content encryption algorithm,
Set as "A128GCM"

JWE Compact Serialization (Informational)

This subsection describes how the JWE token is represented for transport.

The JWE token is represented as five dot-separated segments in compact serialization form.