Implementing ATW Button

To integrate the Add to Wallet (ATW) functionality into your system, you need to embed the provided ATW script and configure it using tokenized card data. This allows users to securely add digital cards to Samsung Wallet.

Follow the steps below to implement the ATW button:

  • Script Composition: Begin by composing the integration script using the sample code provided on the Samsung Wallet Partners Portal. Alternatively, refer to the Integration Sample Code for detailed instructions.
  • Create Tokenized Card Data (Cdata): Next, generate the Cdata (tokenized card data) and insert the corresponding Cdata token into the script. Cdata represents the actual content of the wallet card and comes in various formats depending on the card type. For more information, refer to the Generate_Cdata Sample Code.

Note: The Cdata token should expire in 30 seconds after creation, so the cdata token needs to be created right after the user actually clicks the 'Add to Wallet' button.

To implement the 'Add to Wallet' button, you may need some base data. You can find the base data and other necessary information on Partner portal's Wallet card page.

Samsung Wallet on the Web

This section explains how to implement the Add to Wallet button using JavaScript within a web environment or web view.

Web Button Reference with importing API JavaScript

If you implement the "Add to Wallet" button using this script, the button is shown only on the devices that support Samsung Wallet.
To automatically parse <samsung:wallet> HTML tags when the page is loaded, include the following standard JavaScript:

<script src="https://us-cdn-gpp.mcsvc.samsung.com/lib/wallet-card.js" type="text/javascript"></script>

You can use these tags or JavaScript functions for the web button if you are rendering HTML and you have proper partner permissions. You can also use the script by referring to the various attributes.

samsung:wallet HTML Tag

The 'samsung:wallet' namespace tag defines the placement and various attributes of the "Add to Wallet" web button for Samsung Wallet.

<samsung:wallet
  cardid="CARD_ID"
  cdata="CDATA"
  partnercode="PARTNER_CODE"
  buttonid="BUTTON_ID"
  rdclickurl="RD_CLICK_URL"
  rdimpressionurl="RD_IMPRESSION_URL"
></samsung:wallet>

Button attributes

Attribute

 Description
cardid
String

 (Required)
Wallet card identifier.
* Value granted from the Partners Portal.
cdata
String

 (Required)
Encrypted card object (JSON).
* This field needs to be encrypted.
* See Security
pdata
String

 (Optional)
Reference ID of the Wallet Card content.
* Use instead of cdata when using Data Fetch Link.
* Value granted from the Partners Portal.
partnercode
String

 (Required)
Partner code.
* Value granted from the Partners Portal.
buttonid
String

 (Required)
DOM element ID for the "Add to Wallet" web button for Samsung Wallet.
certificateid
String

 (Optional)
Certificate identifier based on CSR during onboarding.
* Required when using Data Fetch Link with V3 path.
buttontype
String

 (Optional)
"Add to Wallet" button type.
["btnSW" / "btnATSW" / "qrcode", default: btnSW]
* See Image resources
inline
String

 (Optional)
Flag to display the "Add to Wallet" image button in one-line format.
Default: true (one-line).
locale
String

 (Optional)
Locale of the "Add to Wallet" image button.
* See Image resources
language
String

 (Optional)
Language of the "Add to Wallet" image button.
Default: navigator.language
rdclickurl
String

 (Required)
URL for logging a button click event.
* Value granted from the Partners Portal.
rdimpressionurl
String

 (Required)
URL for logging a button impression event.
* Value granted from the Partners Portal.
showforced
String

 (Optional)
Flag to force the "Add to Wallet" button to be displayed.
Default: false.
mediatheme
String

 (Optional)
Load the button's resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly.
Default: default.
* default: Load the button's theme according to the prefers-color-scheme policy.
* inversion: Load the inverse of the default button's theme.
* lightonly: Load the light theme of the default button.
* darkonly: Load the dark theme of the default button.
style
String
(CSSStyleDeclaration)

 (Optional)
Load the button with a custom style.
target
String

 (Optional)
Option to choose button's target name.
* default: "WALLET"
type
String

 (Optional)
Service type.
["atw" / "vww", default: "atw"]
* "atw": Add to Wallet
* "vww": Verifying with Wallet
model
String

 (Optional)
Device model name for device compatibility checks.
* If not provided, the device model is automatically detected.
onshowbutton
Function

 (Optional)
Callback handler function for the button's on-show event.
onclickbutton
Function

 (Optional)
Callback handler function for the button's on-click event.
If you register the handler function, you must return a callback or promise value.
* See Usage of onClickButton Handler
authtoken
String

 (Optional)
Authentication token for creating a shortened URL.
* Only applicable when buttontype is "qrcode".
qrcodeexpirydate
String

 (Optional)
Expiry date for QR code generation.
* Only applicable when buttontype is "qrcode".
* If empty, defaults to 10 years of validity.

samsungWallet.addButton Function

The samsungWallet.addButton function is used to explicitly render the Add to Wallet button on your web page using the Samsung Wallet JavaScript API.

  • Data Transmit Link Example: samsungWallet.addButton
samsungWallet.addButton({
    cardId: "CARD_ID",
    cdata: "CDATA",
    partnerCode: "PARTNER_CODE",
    targetId: "TARGET_ID",
    buttonId: "BUTTON_ID",
    RDClickUrl: "RD_CLICK_URL",
    RDImpressionUrl: "RD_IMPRESSION_URL",
    onShowButton: () => {},
    onClickButton: async (options) => {
        options.cdata = 'CDATA'
    }
});
  • Data Fetch Link Example: samsungWallet.addButton
samsungWallet.addButton({
    cardId: "CARD_ID",
    pdata: "PDATA",
    partnerCode: "PARTNER_CODE",
    targetId: "TARGET_ID",
    buttonId: "BUTTON_ID",
    certificateId: "CERTIFICATE_ID",
    RDClickUrl: "RD_CLICK_URL",
    RDImpressionUrl: "RD_IMPRESSION_URL",
    onShowButton: () => {},
    onClickButton: async (options) => {
        options.pdata = 'PDATA'
    }
});

Button attributes

Attribute

 Description
cardId
String

 (Required)
Wallet card identifier.
* Value granted from the Partners Portal.
cdata
String

 (Optional)
Encrypted card object (JSON).
* This field needs to be encrypted.
* See Security
* Either cdata or pdata must be provided.
pdata
String

 (Optional)
Reference ID of the Wallet Card content.
* Use instead of cdata when using Data Fetch Link.
* Either cdata or pdata must be provided.
partnerCode
String

 (Required)
Partner code.
* Value granted from the Partners Portal.
targetId
String

 (Required)
DOM (Document Object Model) Element ID to place the "Add to Wallet" web button for Samsung Wallet.
buttonId
String

 (Required)
DOM Element ID for the "Add to Wallet" web button for Samsung Wallet.
certificateId
String

 (Optional)
Certificate identifier based on CSR during onboarding.
* Required when using Data Fetch Link with V3 path.
buttonType
String

 (Optional)
"Add to Wallet" button type.
["btnSW" / "btnATSW" / "qrcode", default: btnSW]
* See Image resources
inline
String

 (Optional)
Flag to display the "Add to Wallet" image button in one-line format.
Default: true (one-line).
locale
String

 (Optional)
Locale of the "Add to Wallet" image button.
* See Image resources
language
String

 (Optional)
Language of the "Add to Wallet" image button.
Default: navigator.language
RDClickUrl
String

 (Required)
URL for logging a button click event.
* Value granted from the Partners Portal.
RDImpressionUrl
String

 (Required)
URL for logging a button impression event.
* Value granted from the Partners Portal.
showForced
String

 (Optional)
Flag to force the "Add to Wallet" button to be displayed.
Default: false.
mediaTheme
String

 (Optional)
Load the button's resources from the media theme policy. There are 4 themes: default, inversion, lightonly, and darkonly.
Default: default.
* default: Load the button's theme according to the prefers-color-scheme policy.
* inversion: Load the inverse of the default button's theme.
* lightonly: Load the light theme of the default button.
* darkonly: Load the dark theme of the default button.
style
Object
(CSSStyleDeclaration)

 (Optional)
Load the button with a custom style.
target
String

 (Optional)
Option to choose button's target name.
* default: "WALLET"
type
String

 (Optional)
Service type.
["atw" / "vww", default: "atw"]
* "atw": Add to Wallet
* "vww": Verifying with Wallet
model
String

 (Optional)
Device model name for device compatibility checks.
* If not provided, the device model is automatically detected.
onShowButton
Function

 (Optional)
Callback handler function for the button's on-show event.
onClickButton
Function

 (Optional)
Callback handler function for the button's on-click event.
If you register the handler function, you must return a callback or promise value.
* See Usage of onClickButton Handler
authToken
String

 (Optional)
Authentication token for creating a shortened URL.
* Only applicable when buttonType is "qrcode".
qrCodeExpiryDate
String

 (Optional)
Expiry date for QR code generation.
* Only applicable when buttonType is "qrcode".
* If empty, defaults to 10 years of validity.

samsungWallet.updateButton Function

The samsungWallet.updateButton function updates an existing "Add to Wallet" button's options.

samsungWallet.updateButton("BUTTON_ID", {
    cdata: "NEW_CDATA",
    style: "width:200px;"
});

samsungWallet.removeButton Function

The samsungWallet.removeButton function removes an existing "Add to Wallet" button from the DOM.

samsungWallet.removeButton("BUTTON_ID");

Usage of onClickButton Handler

The onClickButton callback handler function is invoked when the button is clicked. If you register the handler function, you must return a callback or promise value.

The callback function receives two arguments:

  • options — The current button options object. You can dynamically update properties such as cdata or pdata before the wallet action is triggered.
  • callbackClicked — A function that accepts a boolean flag. If called with true, the default click action (navigation to the wallet URL) is triggered.

If the handler function returns/resolves to true, the default click action is also triggered automatically.

Example:

samsungWallet.addButton({
    cardId: "CARD_ID",
    cdata: "CDATA",
    partnerCode: "PARTNER_CODE",
    targetId: "TARGET_ID",
    buttonId: "BUTTON_ID",
    onClickButton: async (options, callbackClicked) => {
        // Dynamically generate cdata after user clicks
        options.cdata = await generateCdata();
        // Trigger the default wallet navigation
        callbackClicked(true);
        // Or simply return true;
    }
});

Button Type Reference

buttonType Value

 Description
btnSW

 Samsung Wallet image button (default)
btnATSW

 Add To Samsung Wallet image button
qrcode

 QR code containing the wallet link

Service Type Reference

type Value

 Description
atw

 Add to Wallet (default)
vww

 Verifying with Wallet

Media Theme Reference

mediaTheme Value

 Description
default

 Load the button's theme according to the prefers-color-scheme policy
inversion

 Load the inverse of the default button's theme
lightonly

 Load the light theme of the default button
darkonly

 Load the dark theme of the default button

Samsung Wallet via MMS or Email

This section outlines how to configure and deliver Samsung Wallet cards through MMS or email, enabling users to add cards to Samsung Wallet directly from their messaging platform.

Note: These methods do not support dynamically controlling button visibility based on device compatibility.

Link to 'Add to Wallet' on MMS/Email

You can include an "Add to Wallet" web button in environments where the JavaScript API cannot be loaded, such as SMS or email.

MMS Link

URL Format: https://a.swallet.link/atw/v1/{Card_ID}#Clip?cdata={your_encrypted_data}

Email Link

<a href="ADD_TO_WALLET_URL">
    <img src="BUTTON_IMAGE_URL" />
    <img src="RD_IMPRESSION_URL" style="width:1px; height:1px;" />
</a>
Attribute

 Description
URL
String

 (Required)
"Add to Wallet" link URL.
* See Data Transmit Link
* See Data Fetch Link
IMAGE_URL
String

 (Required)
Button's image resource URL.
* See Image resources
RD_IMPRESSION_URL
String

 (Required)
Impressions logging URL.
* Value granted from the Partners Portal.