Add Card Links

This section defines the URL contract for each user-initiated add method. Select the method in Choose an Add Method before constructing a link. Treat every generated link as sensitive: expose it only to the intended user and do not log its token or reference value.

Data Transmit Link

The Data Transmit Link carries the protected initial card data from the partner to Samsung Wallet when the user opens the link.

The most common and straightforward method is the Data Transmit Link approach, which securely includes tokenized data in the ATW link. The ATW link format for this method is as follows.

Earlier versions of this specification called this method the Typical flow.

Type	Value	Description
URL	https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}
Path parameters	cardId String(32)	(Required) Wallet card identifier issued from Partner portal when the partner manager signs up for partner services and registers the wallet card they want to service.
Hash path parameters	#Clip String(5)	(Required) Parameters for the Hash link * The first letter is capitalized
Query parameters	cdata String(2048)	(Required) Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. * See Card Specs This must be secured in JWT(JSON Web Token) format. * See Card Data Token (cdata)

Data Fetch Link

The Data Fetch Link carries an opaque partner reference. When the user opens the link, Samsung Wallet calls the partner's Get Card Data endpoint to resolve the card content.

Use this method for sensitive data, late-bound card content or a static entry point that must resolve a user-specific card. Generate pdata so that it cannot be guessed or derived, authorise the retrieval on the partner server and account for the risk that a link may be forwarded.

Earlier versions of this specification called this method the Slim data flow.

Type	Value	Description
URL	https://a.swallet.link/atw/v3/{CertificateId}/{cardId}#Clip?pdata={pdata}
Path parameters	certificateId String(4)	(Conditional) Certificate identifier based on a CSR during onboarding. 4 digits alphanumeric. * Must be generated from Partner Portal
	cardId String(32)	(Required) Wallet card identifier. * It must be generated from Partners Portal.
Hash path parameters	#Clip String(5)	(Required) Parameters for the Hash link
Query parameter	pdata String(128)	(Required) Unique ID defined by content providers. This identifies each user's Wallet Card contents and is used by the partner to manage the added card. * For secure transactions, a Reference ID (refId) must be in a form that cannot be inferred.

Data Action Link

This API is a link-based execution interface that triggers predefined user actions via the adata parameter. When opened, the app/web screen collects user inputs as required. On successful authentication, the flow continues into registration, and the partner must return the necessary card data or identifier to complete the process.

This method invokes the Request Action API. See Action Data for the approved action structure.

Type	Value	Description
URL	https://a.swallet.link/atw/v3/{certificateId}/{cardId}#Clip?adata={adata}
Path parameters	certificateId String(4)	(Conditional) Certificate identifier based on a CSR during onboarding. 4 digits alphanumeric. * Must be generated from Partner Portal * Required if using v3 path
	cardId String(32)	(Required) Wallet card identifier * Must be generated from Partner Portal
Hash path parameters	#Clip String(5)	(Required) Parameters for the Hash link
Query parameter	adata String(16)	(Required) Specified the predefined action to execute when the link is opened. The App/Web UI collects inputs as required by server configuration. By default, once authentication succeeds, the process automatically continues into registration, with the partner returning the necessary card data or identifier for the authenticated user. Allowed values: user_auth