Implementing VWW button

For Samsung Wallet integration, partners will need to insert an "Verify with Samsung Wallet" script into their systems. To implement an "Verify with Samsung Wallet" button, partner should follow the procedure below:

1. First, proceed with script composition with the sample script on the Partner Portal or refer to the Integration sample code.
2. Create the tokenized card data (Cdata). Card data is the actual content of the wallet card and it has several formats based on the card type. Refer to the CData Generation Sample Code for details.

Important

The card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the "Verify with Samsung Wallet” button.

For "Verify with Samsung Wallet" integration, you may also need some base data. You can find that and other necessary information on Partners Portal

Implementing VWW button on the Web

This section explains how to implement an "Verify with Samsung Wallet" button using JavaScript in a web view.

Web Button Reference with Importing API JavaScript

If partner implement the "Verify with Samsung 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, partners should include the following standard JavaScript:

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

Partners can use these tags or JavaScript functions for the web button if they are rendering HTML and have proper partner permissions. Partners 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 "Verify with Samsung Wallet" web button for Samsung Wallet.

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

Button attributes

Attribute	Type	Required	Description
type	String	Y	Service type. Default is "atw" • "atw" : 'Add to Samsung Wallet' • "vww" : Verify with Samsung Wallet'
cardid	String	Y	Wallet card identifier * Value granted from the Partners Portal.
cdata	String	Y	Encrypted card object (JSON). * This field needs to be encrypted. * Refer to Security for more details.
partnercode	String	Y	Partner code. * Value granted from the Partners portal.
buttonid	String	Y	DOM element ID for the "Verify with Samsung Wallet" web button for Samsung Wallet
buttontype	String	N	"Verify with Samsung Wallet" button type. ["btnSW" / "btnVWSW", default : btnSW]
inline	String	N	Flag to display the "Verify with Samsung Wallet" image button in one-line format. Default: true (one-line).
locale	String	N	Locale of the "Verify with Samsung Wallet" image button.
rdclickurl	String	Y	URL for logging a button click event. * Value granted from the Partners Portal.
rdimpressionurl	String	Y	URL for logging a button impression event. * Value granted from the Partners Portal.
showforced	String	N	Flag to force the "Verify with Samsung Wallet" button to be displayed. Default: false.
mediatheme	String	N	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)	N	Load the button with custom style
onshowbutton	Function	N	Callback handler function for the button’s on-show event
onclickbutton	Function	N	Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value.

samsungWallet.addButton Function

This function allows partners to explicitly render the Samsung Wallet API for the "Verify with Samsung Wallet" web button.

samsungWallet.addButton({
    type: "vww",
    cardId: "CARD_ID",
    cdata: "CDATA",
    partnerCode: "PARTNER_CODE",
    targetId: "TARGET_ID",
    buttonId: "BUTTON_ID",
    buttonType: "btnVWSW",
    RDClickUrl: "RD_CLICK_URL",
    RDImpressionUrl: "RD_IMPRESSION_URL",
})

Button attributes
Unlike the samsung:wallet HTML tag, you must use camelCase in the button attributes in function case.

Attribute	Type	Required	Description
type	String	Y	Service type. Default is "atw" • "atw" : 'Add to Samsung Wallet' • "vww" : Verify with Samsung Wallet'
cardId	String	Y	Wallet card identifier * Value granted from the Partners Portal.
cdata	String	Y	Encrypted card object (JSON). * This field needs to be encrypted. * Refer to Security for more details.
partnerCode	String	Y	Partner code. * Value granted from the Partners portal.
targetId	String	Y	DOM (Document Object Model) Element ID to place the "Verify with Samsung Wallet" web button for Samsung Wallet
buttonId	String	Y	DOM Element ID for the "Verify with Samsung Wallet" web button for Samsung Wallet
buttonType	String	N	"Verify with Samsung Wallet" button type. ["btnSW" / "btnVWSW", default : btnSW]
inline	String	N	Flag to display the "Verify with Samsung Wallet" image button in one-line format. Default: true (one-line).
locale	String	N	Locale of the "Verify with Samsung Wallet" image button.
RDClickUrl	String	Y	URL for logging a button click event. * Value granted from the Partners Portal.
RDimpressionurl	String	Y	URL for logging a button impression event. * Value granted from the Partners Portal.
showForced	String	N	Flag to force the "Verify with Samsung Wallet" button to be displayed. Default: false.
mediaTheme	String	N	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)	N	Load the button with custom style
onShowButton	Function	N	Callback handler function for the button’s on-show event
onClickButton	Function	N	Callback handler function for the button’s on-click event. If you register the handler function, you must return a callback or promise value.

Usage of onClickButton Handler

Partners can choose whether to proceed with the next "Verify with Samsung Wallet" step using a promise or a callback function, if they register a callback handler in onClickButton.

We recommend that partner add the process of generating JWT cdata (add cdata to options.cdata) to this handler, because of the cdata expiration time.

The function parameters are defined as follows.

Attribute	Type	Required	Description
options	Button attributes	N	Attributes of the current button
callback	Function	N	Callback function to pass the flag to proceed. Default: false.
(Promise resolve)	Function	N	Promise-resolved value to pass the flag to proceed Default: false.

• Callback to web button process from callback attributes (for ES5)

By executing a callback function with a flag, you can proceed to the next 'Verify with Samsung Wallet' process.

onClickButton: function (options, callback) {
    // TODO partner's process
    callback(flag)
}

• Callback to web button process from returning Promise (for ES6)

By returning a promise with a resolving flag, you can proceed to the next ‘Verify with Samsung Wallet’ process.

onClickButton: async (options) => {
    return new Promise(async (resolve, reject) => {
        // TODO partner's process (await)
        resolve(flag)
    })
}

Implementing VWW button on the App

This section explains how to implement an "Verifying with Samsung Wallet" button in the partner’s app.
Please download below sample code and refer it

Refer to Android Sample Code

Data Transmit 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.

• The name Data Transmit Link has been changed from Typical flow.

Type	Value			Description
URL	https://a.swallet.link/vww/v1/{cardId}#Clip?cdata={cdata}
Path parameters	cardId	String	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	Required	Parameters for the Hash link * The first letter is capitalized
Query parameters	cdata	String	Required	Actual payload data in basic JSON format to communicate between partners and Samsung Wallet. This must be secured in JWT(JSON Web Token) format. * Refer to Security for more details.

Example

https://a.swallet.link/vww/v1/1656147182764415319#Clip?cdata=eyJjdHkiOiJKV1QiLCJhbGciOiJsInRpbWVzdGFtcCI6ImNyZWF0ZWQgdGltZSIsInBhcnRuZXJJRCI6InBhcnRuZXIgSUQifQ.
… … … …
Dn0_oZ3xcr0JuQ3mlSzLIUTxFoTewnZ0MQj7kiNjysNm5Xfwqt5vcN20PeebeLgUx8VJXLy4_9G4BHQ-hd4O9POYuTuAWew.YzdlMTFhO -NYCeL3T0YzNzAD2KcK_HrtwIGEErHLGn6ydaq_fpFdSlxsA3ZJtNpg3wcuqEw5cIdpbPFswbQLropqEpNawg5nlm3DKAA4a1dzaZMbSR1BGZHrH_vIKnx3CY5MO0jNBexl_YIZ5_wB379UYSwumQiPiTZVg2IjYvfht17I4