Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials
blogintroduction smartphones have become an essential part of our everyday lives. users are continually searching for more convenient ways to perform their tasks on their smartphones, driving them toward services with greater usability. as smartphones advance, our lives become simpler. galaxy users have completely embraced the convenience of paying with samsung pay, and no longer carry physical payment cards. this led to the evolution of samsung pay into samsung wallet, incorporating biometric-authentication-based security solutions and adding various features to replace conventional wallets. since june 2022, samsung wallet has been expanding its service area based on the existing samsung pay launching countries. this article aims to introduce samsung wallet and guide you through the integration process of the "add to samsung wallet" feature, which allows you to digitize various content and offer them as wallet cards. notice this article introduces non-payment service cards. if you want to learn more about the payment service of samsung wallet, visit the samsung pay page. you can get information on online payment services such as in-app payments, web checkout, and w3c payments. add to samsung wallet service let's delve deeper into the "add to samsung wallet" feature. digitized content registered in samsung wallet comes in the form of cards called wallet cards. registering a wallet card is effortless: simply click the "add to samsung wallet" button, and the card is stored securely on users’ galaxy smartphones. "add to samsung wallet" button and wallet card notice the benefits of using wallet cards can be found in the commercial video forgetting can be awesome. wallet cards the "add to samsung wallet" service is an open platform that supports offering various types of content such as wallet cards. we are streamlining service integration with content providers across different regions and adding useful features. boarding pass event ticket loyalty gift card coupon id card generic card pay as you go (in progress) reservation (in progress) digital key (in progress) notice generic card supports unstructured forms of cards. be a samsung wallet partner partner onboarding to begin offering content through samsung wallet, you must first register as a partner on the samsung wallet partner portal. the integration process is detailed on the samsung developer portal. to join the samsung wallet partner portal, create a samsung account that is used as the service administrator. wallet card management once enrolled, you can create service cards on the wallet cards menu. each card is assigned a card id representing the service, and you can set the card type and linking information. you can manage cards according to their status – test or live. configuring wallet card notice after completing all required forms for the wallet card, click the launch button to request card activation. before providing the service to actual users, remember to turn off the 'test mode.' how to safely secure user data key generation and certificate request the registration process includes certificate exchange to securely transmit service data. refer to the diagram and developer guide, security key & certificate creation guide, to complete the certificate registration and partner enrollment smoothly. certificates exchange process ensuring data security to prevent forgery and leakage of user card data, secure tokenization processing is required. json web token (jwt), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. in particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used. process of generating and verifying security tokens notice depending on how partners provide content services to users, you can choose how to deliver data to the samsung wallet service. two ways to transfer wallet card data add to samsung wallet interface provides two methods for partners to deliver users digital content as wallet cards. data transmit link the general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the samsung wallet service when the user clicks the button. as long as samsung wallet support is confirmed, you can generate a link containing the user's card data and configure the "add to samsung wallet" button to run the link when pressed, either on an application or web page. data transmit process data fetch link another method to transfer wallet card data is to include only the refid, which represents the user's content, in the "add to samsung wallet" link and transmit it to the samsung wallet service. when a user clicks the "add to samsung wallet" button, samsung servers refer to the get card data api information set on the wallet card and retrieve user content using the received refid to complete registration. data fetch process this method is suitable for providing user's data through email or mms messages where static links cannot be avoided. there is an option to secure these static links. data fetch process for static links setting up data synchronization on the partner portal, you can set up the wallet card information and configure the server interaction api that the content provider needs to prepare. this api is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on samsung wallet. register wallet cards when a user card is added to samsung wallet, samsung wallet servers use the send card state api to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with samsung wallet. when a wallet card is registered, added event is sent to the partner's server update wallet cards changes to the synchronization target content can be notified to the samsung wallet service through the update notification api. here, the value that distinguishes each piece of content is the refid that the partner must provide when registering the users’ wallet card. through the get card data api, samsung wallet servers can check the latest content information any time. if updates occur on the partner's side, updated event notifications should be sent to the samsung server in case users withdraw content from the partner's side in case users delete cards from samsung wallet notice both servers should verify requests using the authorization header of the api request. this authorization token is in jwt format, familiar from card data security. effortless wallet card registration with just one click this feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or mms message. various service channels javascript library for web developers we provide a javascript library and a user guide, implement the button, to help integrate your web pages. creating buttons and links in your app for configuring buttons in applications, utilize the button image resources. providing services via mms, email, or qr codes to provide services through fixed links, check out the details of the data fetch link. these static links can also be used by scanning qr codes. experience the service and practice you can experience service integration development using the codelab and use the testing tool to preregister the wallet cards created on the partner portal, which could be helpful. conclusion we've looked at how to provide digital content through the "add to samsung wallet" feature. we continuously update the guides on the developer portal, so please refer to them when preparing for integration. summary the "add to samsung wallet" service welcomes participation from content service partners and developers. for inquiries or technical support, please contact us through the form provided on the developer portal. i hope this post has been helpful, and now i'll conclude my writing here. thank you. this post was written based on the sdc23 korea session.
Choi, Jonghwa
Develop Samsung Wallet
doc6 1 code lab exercise for add to wallet integration exercise this code lab exercise is designed to help partners apply their knowledge of samsung wallet by guiding them through a complete hands-on integration in approximately 30 minutes, participants will create and test a working “add to wallet” implementation using sample data the exercise is divided into 10 structured sections; each focused on a key step in the integration workflow these sections are designed to be completed in sequence for the best learning experience objective overview set up your environment start your project create wallet cards launch wallet cards apply the add to wallet script generate and input the cdata test the "add to wallet" button you're done! if you have read through all the materials in this section, please don't hesitate to try the code lab exercise it will be worth it!
Develop Samsung Wallet
docatw 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 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-cdata token should expire in 30 seconds after creation, so cdata token needs to be created right after users actually click ‘add to wallet’ button to implement ‘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 3 4 1 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 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 buttontype string optional “add to wallet” button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] * see image resources authtoken string optional token generated when “qrcode” is used * required only if the “buttontype” is set to “qrcode” model string optional device model to display button* by default, value from user-agent is used if no value from user-agent, the button is displayed * to display buttons only on devices supporting samsung wallet, explicitly include the model name * for example, you can retrieve the device model name e g , sm-s928f from the browser's user-agent 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 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 custom style target string optional option to choose button’s target name * default “wallet” 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 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 samsungwallet addbutton { cardid "card_id", cdata "cdata", partnercode "partner_code", targetid "target_id", buttonid "button_id", rdclickurl "rd_click_url", rdimpressionurl "rd_impression_url", } button attributes attributes 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 * seesecurity 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 buttontype string optional “add to wallet” button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] * see image resources authtoken string optional token generated when “qrcode” is used * required only if the “buttontype” is set to “qrcode” model string optional device model to display button* by default, value from user-agent is used if no value from user-agent, the button is displayed * to display buttons only on devices supporting samsung wallet, explicitly include the model name * for example, you can retrieve the device model name e g , sm-s928f from the browser's user-agent 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 rdclickurl string required url of logging a button click event * value granted from the partners portal rdimpressionurl string required url of 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” 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 usage of onclickbutton handler the onclickbutton handler allows to define what happens when a user clicks the ‘add to wallet’ button we recommend that you 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 attributes description options button attributes optional attributes of the current button callback function optional callback function to pass the flag to proceed default false promise resolve function optional promise-resolved value to pass the flag to proceed default false callback to web button process from callback attributes for es5 in an es5 ecmascript 5 environment, you can use the callback attribute in your web button implementation to control the flow of the "add to wallet" process by executing the callback function with a boolean flag {callback flag } you can determine whether or not to proceed to the next step in the wallet integration onclickbutton function options, callback { // todo partner's process callback flag } callback to web button process from returning promise for es6 in an es6 environment, by returning a promise with a resolving flag, you can proceed to the next add to wallet process onclickbutton async options => { return new promise async resolve, reject => { // todo partner's process await resolve flag } } note-the card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the ‘add to wallet’ button samsung wallet on the app this section outlines how to implement the “add to wallet” button within a native application e g , android or ios steps to implement ‘add to wallet’ in a native app download the official ‘add to wallet’ button graphics from the designated repository based on your service environment for details on available assets and usage guidelines, see the image resources section before displaying the button, use the ‘check service available devices’ api to determine whether the user's device supports samsung wallet interpret the api response as follows if "available" true → device is supported → show the ‘add to wallet’ button if "available" false → device is not supported → do not show the button implement a jwt web link on the button triggered action note-the card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “add to wallet” button app button on android [sample code implementation] public class walletcodesample { protected final static string tag = "samsungwalletsample"; protected static final string host = "https //api-us3 mpay samsung com"; protected static final string path = "wallet/cmn/v2 0/device/available"; /** * sample entry point of the usage */ public static void main { executors newsinglethreadexecutor submit -> { final string modelname = build model; final string countrycode = null; // optional country code iso_3166-2 final string servicetype = "wallet"; // required, fixed for samsung wallet final string partnercode = null; // required try { walletcodesample sample = new walletcodesample ; boolean iswalletsupported = sample checkwalletsupported modelname, countrycode, servicetype, partnercode ; string msg = string format "query for model %s , countrycode %s , servicetype %s , partnercode %s / wallet supported? %s ", modelname, countrycode, servicetype, partnercode, iswalletsupported ; log d tag, msg ; } catch exception e { // failed to check due to some reasons log e tag, e getmessage , e ; } } ; } /** * please see the wallet api spec document > '6 6 check service available devices' for more details * * @return true if wallet supported, otherwise false * @throws exception throws exception when it's not possible to get status due to any reasons */ public boolean checkwalletsupported @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype, @nonnull string partnercode throws exception { if modelname == null || modelname isempty { log e tag, "model name is required parameter" ; throw new exception "something went wrong failed to get device model name " ; } if servicetype == null || servicetype isempty { log e tag, "servicetype is required parameter" ; throw new exception "something went wrong failed to get device servicetype " ; } if partnercode == null || partnercode isempty { log e tag, "partnercode is required parameter" ; throw new exception "something went wrong failed to get device partnercode " ; } string urlstring = makeurl modelname, countrycode, servicetype ; log i tag, "urlstring " + urlstring ; try { url url = new url urlstring ; httpurlconnection connection = httpurlconnection url openconnection ; connection setrequestproperty "partnercode", partnercode ; connection setrequestmethod "get" ; int responsecode = connection getresponsecode ; log i tag, "responsecode " + responsecode ; bufferedreader bufferedreader; if responsecode == 200 { bufferedreader = new bufferedreader new inputstreamreader connection getinputstream ; } else { bufferedreader = new bufferedreader new inputstreamreader connection geterrorstream ; } stringbuilder sb = new stringbuilder ; string inputline; while inputline = bufferedreader readline != null { log i tag, inputline ; sb append inputline ; } connection disconnect ; bufferedreader close ; // parse result jsonobject jsonobject = new jsonobject sb tostring ; string resultcode = jsonobject getstring "resultcode" ; string resultmessage = jsonobject getstring "resultmessage" ; if "0" equals resultcode && "success" equals resultmessage { return jsonobject getboolean "available" ; } else { throw new exception "something went wrong, resultcode " + resultcode + " , resultmessage " + resultmessage + " " ; } } catch ioexception e { log e tag, e getmessage , e ; throw new exception "something went wrong ioexception , " + e getmessage ; } catch jsonexception e { log e tag, e getmessage , e ; throw new exception "something went wrong, receive wrong formatted response, " + e getmessage ; } } protected string makeurl @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype { stringbuilder sb = new stringbuilder ; sb append host append '/' ; sb append path ; sb append '?' append "servicetype" append '=' append servicetype ; sb append '&' append "modelname" append '=' append modelname ; if countrycode != null && !countrycode isempty { sb append '&' append "countrycode" append '=' append countrycode ; } return sb tostring ; } } samsung wallet via mma 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 platforms overview integrating samsung wallet into mms or email involves sending a web link that allows users to add a wallet card without needing to load the full javascript api this approach is ideal for environments such as sms/mms messages email communications note-these methods do not support dynamically controlling button visibility based on device compatibility guide to configuring wallet code for email and mms messages set up the data fetch link, including the necessary server apis to retrieve the wallet card data create a unique ‘reference id’ for each transaction or request ensure the ‘reference id’ is complex and secure to prevent the inference of sensitive information send the message containing the web link via a preferred platform e g , email or mms for mms, the web link will show up as a ‘smart suggestion’ on samsung devices, providing a streamlined user experience for reference, a sample web link can be found on the wallet cards guide on the partners portal for card data, samsung wallet asks the partner system to provide card details through the server api duplicate requests are prohibited on the same device to ensure data integrity 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 these methods do not support controlling “add to wallet” button visibility mms link url link url attributes description url string required “add to wallet” link url * see data transmit link * see data fetch link [email on web button link] <a href="url"> <img src="image_url"> <img src="rd_impression_url" style="width 1px; height 1px;"> </a> attributes 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 3 4 2 statistics service samsung wallet provides valuable statistical data related to the integrated services, accessible via the partners portal this data helps track key events, such as button impressions and user interactions, to optimize your service and improve the overall user experience note-statistics api sample code - the actual code sample is at the wallet script guide section in ‘wallet cards’ menu on the partner portal event notification api https //us-rd mcsvc samsung com/statistics/{event}/addtowlt?{parameters}&utm_source=partner&utm_medium={channel} {event} for each event in the following situations - impression when the “add to wallet” button has been shown - click when the “add to wallet” button has been clicked {parameters} includes key factors to figure out the service {channel} - app "samsung wallet" button in a native application - web "samsung wallet" button on the web - email "samsung wallet" button in an email for details, please visit 'wallet cards' menu on the partner portal
Develop Samsung Wallet
docatw"• "atw" 'add to samsung wallet' • "vww" verify with samsung wallet' 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 * refer to security for more details partnercode |string required partner code * value granted from the partners portal buttonid string required dom element id for the "verify with samsung wallet" web button for samsung wallet buttontype string optional "verify with samsung wallet" button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] authtoken string optional token generated when “qrcode” is used * required only if the “buttontype” is set to “qrcode” model string optional device model to display button* by default, value from user-agent is used if no value from user-agent, the button is displayed * to display buttons only on devices supporting samsung wallet, explicitly include the model name * for example, you can retrieve the device model name e g , sm-s928f from the browser's user-agent inline string optional flag to display the "verify with samsung wallet" image button in one-line format default true one-line locale string optional locale of the "verify with samsung wallet" image button 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 "verify with samsung 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 custom style onshowbutton function optional callback handler functions for the button’s on-show event onclickbutton function optional callback handler functions 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 description type string required service type default is "atw"• "atw" 'add to samsung wallet' • "vww" verify with samsung wallet' 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 * refer to security for more details partnercode string required partner code * value granted from the partners portal targetid string required dom document object model element id to place the "verify with samsung wallet" web button for samsung wallet buttonid string required dom element id for the "verify with samsung wallet" web button for samsung wallet buttontype string optional "verify with samsung wallet" button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] authtoken string optional token generated when “qrcode” is used * required only if the “buttontype” is set to “qrcode” model string optional device model to display button* by default, value from user-agent is used if no value from user-agent, the button is displayed * to display buttons only on devices supporting samsung wallet, explicitly include the model name * for example, you can retrieve the device model name e g , sm-s928f from the browser's user-agent inline string optional flag to display the "verify with samsung wallet" image button in one-line format default true one-line locale string optional locale of the "verify with samsung wallet" image button 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 "verify with samsung 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 custom style onshowbutton function optional callback handler functions for the button’s on-show event onclickbutton function optional callback handler functions 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 description options button attributes optional attributes of the current button callback function optional callback function to pass the flag to proceed default false promise resolve function optional promise-resolved value to pass the flag to proceeddefault 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 } } 4 4 2 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
Develop Samsung Wallet
docatw service provides a set of interfaces that enable users to easily add digital content to their samsung wallet, enhancing convenience by allowing users to store, manage, and access items such as loyalty cards, tickets, boarding passes, and more directly within the app the service involves several steps, from content preparation to updates and managing card states 3 1 1 service flow the add to samsung wallet atw service provides a set of interfaces that enable users to easily add digital content to their samsung wallet, enhancing convenience by allowing users to store, manage, and access items such as loyalty cards, tickets, boarding passes, and more directly within the app the service involves several steps, from content preparation to updates and managing card states 3 1 2 preparation steps to prepare the contents intended to store on samsung wallet must be tokenized as jwt json web token when using data transmit link considering what environments, the button will be displayed in such as app, web, mms, or email when you plan to integrate this service refer to implement the button section for more details note-the data transmit link is used for communication between the partner’s server and samsung wallet this link sends any additional information related to the card such as updates or notifications about the card’s status 3 1 3 add to wallet steps to add to wallet once users who want to store contents click or tab the linked button, it initiates the process of adding to samsung wallet see add to wallet interfaces for more details if you are providing the full pass content, use the data fetch link option note-the data fetch link enables the partner's backend system to pull content dynamically when a user clicks the "add to wallet" button, the system fetches the necessary content e g , card details, event data, loyalty points using this link samsung will notify the result through server interface named send card state this works as a callback for 'add to wallet' process delivering events and country code for the user wallet card to handle interactions after storing content in samsung wallet, server interfaces are required these interfaces are defined in the chapter titled "server interaction" 3 1 4 update wallet cards steps to update wallet cards partners may need to update or modify the content stored in samsung wallet for example, a user might accumulate more loyalty points, or flight details may change to update the wallet card content, partners must call the samsung server api the cc2 path parameter must match the cc2 value from the send card state api notification triggered by the added event refer to samsung server api section for more details update notification is for single content cancel notification is for calling off every user's wallet card content related to a specific event get card data payload has the same format of card information as the one of 'add to wallet' send card state can also have an event 'deleted' to notify a wallet card deletion on samsung wallet by users gift cards and generic cards currently do not support update notification functionality 3 1 5 card states wallet cards within samsung wallet can have various states e g , active, expired, used, suspended for each content provider’s notifications and user actions the state diagram below describes wallet card states from beginning to end
Develop Samsung Wallet
docatw link the atw link format for this method is as follows note-the name data transmit link has been changed from typical flow type value description url https //a swallet link/atw/v3/{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 * see security [example] https //a swallet link/atw/v3/1656147182764415319#clip?cdata=eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0zwqgdgltzsisinbhcnruzxjjrci6inbhcnruzxigsuqifq … … … … dn0_oz3xcr0juq3mlszliutxfotewnz0mqj7kinjysnm5xfwqt5vcn20peebelgux8vjxly4_9g4bhq-hd4o9poyutuawew yzdlmtfho -nycel3t0yznzad2kck_hrtwigeerhlgn6ydaq_fpfdslxsa3zjtnpg3wcuqew5cidpbpfswbqlropqepnawg5nlm3dkaa4a1dzazmbsr1bgzhrh_viknx3cy5mo0jnbexl_yiz5_wb379uyswumqipitzvg2ijyvfht17i4 data fetch link the data fetch link allows partners to retrieve card details after the card has been added to the samsung wallet in cases involving sensitive data or when providing static links, data fetch link method is highly recommended links using this approach include only a unique reference id, and wallet cards are added by querying data through get card data path as specified in partner portal note- the name data fetch link has been changed from slim data flow please be aware that if the link is exposed to unintended users, it can be exploited please prepare the integration with this in mind it is crucial to ensure that the refid, used for a reference value, is generated in a manner that is not easily deducible by potential attackers type value description url https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateidstring 4 conditional ertificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardidstring 32 required wallet card identifier * it must be generated from partners portal hash path parameters #clipstring 5 required parameters for the hash link query parameter pdatastring 2048 required unique id defined by content providers this has identification for each user's wallet card contents * for secure transactions, a reference id refid must be in a form that cannot be inferred example - https //a swallet link/atw/v3/ymtt/1656147182764415319#clip?pdata=sighcziwm9g 3 3 2 updating wallet card specs when users add cards to samsung wallet, their data can be updated through server interactions to manage these updates, partners need to configure their api settings via the partner portal follow the steps below to manage and update the cards added to samsung wallet samsung server will notify the result of 'add to wallet' via send card state partners get the callback url for samsung server api from send card state payload using the callback url, partners can make actions for the added cards via samsung server api depending on the interfaces, samsung server triggers specific operations for example, when update notification is called, samsung server calls partners' server to look up the updated contents ![] https //d3 unf4s5rp9dfh cloudfront net/samsungwallet_doc/updating-wallet-card-specs png partner server api samsung server can call the following api by using endpoint on the registered card information if the partner server manages an inbound allow list, contact us to register samsung server ip address get card data the get card data allows partners to retrieve the most up-to-date information about a card that has already been added to samsung wallet this api is crucial for ensuring that the partner’s system has accurate and current details about a user's card, whether for display, transaction validation, or other purposes [request] type value description method get url {partner server url}/cards/{cardid}/{refid}?fields={fields} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * refer to the 'add to wallet' interfaces refid string 32 required a unique content identifier defined by the content provider query parameter fields string 128 optional attributes which intended to retrieve can be specified using commas , as separators e g balance,barcode value payload n/a example get /cards/12584806754/ref-20230304-0003 [response] type value description http status 200 ok 204 no content payload option1 cdata string 4096 conditional card object json * this field needs to be encrypted * see security payload option2 card object conditional card information * card object as an alternative to cdata * if cards includes sensitive data, it is highly recommended using cdata card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required timestamp of data epoch timestamp in milliseconds data[] updatedat long 13 required timestamp of data epoch timestamp in milliseconds data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, canceled, pending, suspended * see card states for details data[] language string 8 required default content language code e g , en, ko data[] attributes object required card data attributes data[] attributes {fields} attribute fields by card type *see wallet cards data[] localization[] array of object optional information for multilingual support localization[] language string 8 required multilingual content language code e g , en, ko localization[] attributes {fields} for displaying a given language, "data[] attributes" can be replaced by localized versions *see wallet cards [example option1 ] { "cdata" "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 eyjzdwiioiixmjm0nty3odkwiiwibmftzsi6ikpvag4grg9liiwiawf0ijoxnte2mjm5mdiyfq sflkxwrjsmekkf2qt4fwpmejf36pok6yjv_adqssw5c" } [example option2 ] { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-0002", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet" /* refer to wallet cards */ }, "localization" [{ "language" "ko", "attributes" { "title" "삼성월렛" } }] }] } } [example filtered using select parameter ] get /cards/12584806754/ref-20230304-0003?select=idphoto { "card" { "type" "ticket", "subtype" "entrances", "data" [{ "refid" "ref-20230304-0003", "createdat" 1612660039000, "language" "en", "attributes" { "idphoto" "{idphoto data}" } }] } } or { "cdata" tokenize{data} } [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request send card state the send card state is used to manage the state or history of the card using this api if the card state is changed on the samsung device, samsung calls this api using a refid [request] type value description method post url {partner server url}/cards/{cardid}/{refid} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * refer to the 'add to wallet' interfaces refid string 32 required a unique content identifier defined by the content provider query parameters cc2 string 2 required country code cc2 for samsung server api event string 16 required events on wallet carde g , added, updated, deleted, provisioned* see card states for details payload callback string 1024 optional callback url for samsung server api [example] post /cards/12584806754/ref-20230304-001?cc2=us&event=added { "callback" "https //us-tsapi walletsvc samsung com" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request samsung server api the samsung server api allows partners to notify their content changes to samsung wallet depending on your service requirements, you can choose from private domain or public domain to send notifications the domain selection depends on your system's needs and security preferences service domain environment domain public domain https //tsapi-card walletsvc samsung com private domain ‘callback’ field from send card state api request payload key components private domain recommended for ip registration - if your service requires registering static ip addresses on your system, we recommend using the private domain when you use the private domain, you will receive a callback url in the send card state api response this url will direct your system to the correct endpoint to send content updates or changes public domain recommended for no ip registration - if your service does not require ip registration or has more flexible network access, you can use the public domain the public domain api endpoint allows easier integration without requiring specific ip addresses to be registered however, it does require a country code cc2 as a path parameter for each request this ensures that content is correctly routed based on the user's region or country to configure the api integration for different environments e g , testing, production , you must first register a new card service with samsung this process will assign you a new card id for use in your api calls the card id is crucial for identifying and tracking the specific card you are interacting with to ensure safe and secure communication, servers should configure token-based authentication for information, refer to the authorization token update notification allows partners to notify samsung wallet when there are changes or updates to the content of a wallet card this ensures that the card information within samsung wallet remains up-to-date and accurate [request] type value description method post url {cc2}/wltex/cards/{cardid}/updates headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, suspended * see send card state for details data[] fields string 128 optional wallet cards attributes which has been updated can be specified using commas , as separators it is used when 'data[] state' is updated e g balance,barcode value* supported wallet card types generic [example] post /wltex/cards/12584806754/notification [headers] authorization eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] case 1 in general cases { "card" { "type" "ticket", "data" [ { "refid" "ref-ticket-0001", "state" "updated" } ] } } case 2 in case of deletion { "card" { "type" "boardingpass", "data" [ { "refid" "ref-boardingpass-0001", "state" "deleted" } ] } } case 3 when a specific field is updated { "card" { "type" "idcard", "data" [ { "refid" "ref-idcard-0001", "state" "updated", "fields" "balance" } ] } } [response] type value description http status 200 ok204 no content payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request cancel notification allows partners to inform samsung wallet when a card such as for performances, sports, movies, or journeys needs to be cancelled when a cancellation occurs, this api enables partners to set the related card s to an expired status this ensures that users no longer have valid access to events or services that have been cancelled, such as a concert, flight, or movie screening [request] type value description method post url {cc2}/wltex/cards/{cardid}/cancels headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> *see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from the partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] eventid string 32 conditional required if card type has been set as ‘ticket’ data[] vehicle number string 32 conditional required if "card type" has been set as "boardingpass" data[] estimated oractualstartdate long 13 data[] state string 16 required wallet card state e g , canceled* see card states for details [example] post /wltex/cards/12584806754/notification [headers] authorization eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] * a movie ticket has been canceled { "card" { "type" "ticket", "data" [ { "refid" "event-722164a1a7", "state" "canceled" } ] } } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request
tutorials mobile
blogatw/v1/{card id}#clip?cdata={cdata token} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. cdata query parameter contains the encrypted card data in jwt format. for more information, see the "cdata token generation" section below. if the encrypted card data is longer than 2048 bytes, or you do not want to include the tokenized data in the url, store and reference the card data on your server. create the url in the following format: https://a.swallet.link/atw/v1/{card id}#clip?pdata={reference id} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. pdata query parameter is the unique identifier for the card data stored on your server. for more information on “add to wallet” links, see add to wallet interface. cdata token generation the card data in basic json format must be provided as a jwt (json web token). for token generation details, see security. you can also study the cdata generation sample code. to ensure your cdata token is valid, keep the following requirements in mind: pay attention to the mandatory fields in the card object. all timestamps are utc epoch time in milliseconds. card data attributes vary based on the card type. for detailed card data specifications, see wallet cards. your private key must match the key used for the security certificate signed by samsung. if you are using the correct private key, the following commands generate the same hash: $ openssl rsa -noout -modulus -in partner.key | openssl md5 $ openssl x509 -noout -modulus -in partner.crt | openssl md5 generated jwt tokens expire in 30 seconds. the “add to wallet” link must be used within this time. otherwise, you must generate a new token and new link. next steps to integrate the “add to wallet” feature as a button in your application or website, see implement the button. you can update the information on a card that has been stored in a user’s samsung wallet by communicating between your server and the samsung server. for information, see server interaction. if you have any questions or face difficulties implementing the content in this article, you can contact samsung developer support. related resources samsung wallet documentation integrate “add to samsung wallet” button into partner services code lab
M. A. Hasan Molla
tutorials mobile
blogatw/v1/{card id}#clip?cdata={cdata token} for more information about this endpoint, see data transmit link. binding.addtowalletbutton.setonclicklistener { coroutinescope(dispatchers.main).launch { val response = apiclient.apiservice.getmovie(position) if(response.issuccessful && response.body()!=null){ startactivity(intent( intent.action_view, uri.parse("http://a.swallet.link/atw/v1/3aabbccddee00#clip?cdata=${response.body()!!.jwt}"))) // replace '3aabbccddee00' part with your card id } } } notethe generated cdata is valid for 30 seconds, so it is recommended to generate the cdata only when the "add to samsung wallet" button is clicked. if the cdata has expired by the time the token is sent to samsung wallet, the user can receive a "request timed out" error. generate signed wallet card data the server application must be configured to receive the card data request from the mobile application and return a signed jwt token. this part of the tutorial uses the spring boot framework. configuring the server project to create and configure a server application to generate and sign wallet card data: in the spring initializr tool or any supported java ide, create a spring boot project and open the sample code. to configure the server to receive rest api requests from the mobile application, add the "spring web" dependency to the project. define a token data class. make sure it has the same attributes as the tokenresponse data class defined in the mobile application. data class token(val status:string, val jwt:string initialize a tokencontroller class that receives the incoming requests and returns a token object in response. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { return token("success", "{dummy_cdata}") // cdata generation logic } } the cdata generation and signing logic is described in the next section. implementing card data signing logic for easier understanding, this section describes a simplified implementation of the cdata generation sample code. in the server application project, copy the following credential files to the "sample/securities/" directory. samsung public key from the samsung certificate ("samsung.crt") partner public key from your partner certificate ("partner.crt") partner private key from the private key file ("partner.key") to handle the certificate files and signing algorithms, add the following dependencies to the server application's "build.gradle" file: implementation 'com.nimbusds:nimbus-jose-jwt:9.37.3' implementation 'org.bouncycastle:bcprov-jdk18on:1.77' in a new "jwtgen.kt" file, define a readcertificate() method that reads the public keys from the certificates and a readprivatekey() method that reads the private key from the key file. private val partner_id = "4048012345678912345" // replace with your partner id private val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) private val partnerpublickey = readcertificate(getstringfromfile("sample/securities/partner.crt")) private val partnerprivatekey = readprivatekey(getstringfromfile("sample/securities/partner.key")) fun readprivatekey(key: string): privatekey { val keybyte = readkeybyte(key) lateinit var privatekey: privatekey val pkcs8spec = pkcs8encodedkeyspec(keybyte) try { val kf = keyfactory.getinstance("rsa") privatekey = kf.generateprivate(pkcs8spec) } catch (e: invalidkeyspecexception) { e.printstacktrace() } catch (e: nosuchalgorithmexception) { e.printstacktrace() } return privatekey } fun readcertificate(cert: string): publickey { lateinit var certificate: certificate val keybyte = readkeybyte(cert) val `is`: inputstream = bytearrayinputstream(keybyte) try { val cf = certificatefactory.getinstance("x.509") certificate = cf.generatecertificate(`is`) } catch (e: certificateexception) { e.printstacktrace() } return certificate.publickey } private fun readkeybyte(key: string): bytearray { val keybyte: bytearray val bais = bytearrayinputstream(key.tobytearray(standardcharsets.utf_8)) val reader: reader = inputstreamreader(bais, standardcharsets.utf_8) val pemreader = pemreader(reader) var pemobject: pemobject? = null try { pemobject = pemreader.readpemobject() } catch (e: ioexception) { e.printstacktrace() } keybyte = if (pemobject == null) { base64.getdecoder().decode(key) } else { pemobject.content } return keybyte } fun getstringfromfile(path: string?): string { try { val file = file(objects.requirenonnull(classloader.getsystemclassloader().getresource(path)).file) return string(files.readallbytes(file.topath())) } catch (e: ioexception) { throw runtimeexception(e) } } generating card data cdata token generation is implemented in the "jwtgen.kt" file: read the file containing raw json data that defines the ticket data structure. for this demonstration, use the "ticket.json" file in the "sample/payload/" directory of the cdata generation sample code. generate or fill in the required ticket details. for example, the "{title}" and "{seatnumber}" fields are replaced with the movie title and seat number. for information about the complete json structure, see wallet cards. convert the json data to a jwe object. encrypt the jwe object with the samsung public key. build the custom jws header for samsung wallet cards. sign and validate the complete jws object with your partner private and public key using the rs256 asymmetric algorithm. this is the cdata token. private val currenttimemillis = system.currenttimemillis() private val plaindata:string = getstringfromfile("sample/payload/ticket.json") .replace("{refid}", uuid.randomuuid().tostring()) .replace("{language}", "en") .replace("{createdat}", currenttimemillis.tostring()) .replace("{updatedat}", currenttimemillis.tostring()) .replace("{issuedate}", currenttimemillis.tostring()) .replace("{startdate}", (currenttimemillis + timeunit.days.tomillis(1)).tostring()) .replace("{enddate}", (currenttimemillis + timeunit.days.tomillis(1) + +timeunit.hours.tomillis(2)).tostring()) fun generatecdata(moviename: string, movieticktno:string): string{ // modify data as needed val data = plaindata.replace("{title}", "\"$moviename\"") .replace("{seatnumber}","\"$movieticktno\"") //print(data) return generate(partner_id, samsungpublickey, partnerpublickey, partnerprivatekey, data) } private fun generate(partnerid: string, samsungpublickey: publickey, partnerpublickey: publickey, partnerprivatekey: privatekey, data: string): string { val jweenc = encryptionmethod.a128gcm val jwealg = jwealgorithm.rsa1_5 val jweheader = jweheader.builder(jwealg, jweenc).build() val encryptor = rsaencrypter(samsungpublickey as rsapublickey) val jwe = jweobject(jweheader, payload(data)) try { jwe.encrypt(encryptor) } catch (e: joseexception) { e.printstacktrace() } val payload = jwe.serialize() val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", "2") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } returning the signed token in the server application code, when the server receives a request at the movie/{movieid} endpoint, the tokencontroller class calls the jwtgen.generatecdata() method with the movie id, which generates and returns the cdata jwt token in the api response. in this tutorial, since the movie ticket list was predefined in the mobile application project, make sure the same movie data class and list are defined here too. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { val movielists = listof<movie>( movie("the wallet", "samsung studios", "a-01"), movie("crying sea", "laplace studio","h-07"), movie("canoe", "terra productions", "r-03") ) if( movieid>2){ // implement your verification logic return token("failure", "") } else{ val cdata = jwtgen.generatecdata(movielists[movieid].name, movielists[movieid].ticketnumber) return token("success", cdata) } } } testing the application to test your "add to wallet" integration: connect the server and the mobile device to the same network. launch the server and mobile applications. in the mobile application, tap a movie ticket in the list. its detail page opens. tap add to samsung wallet. the server generates and returns the cdata token. the samsung wallet application launches on the device and the movie ticket information is added to it. figure 3: ticket added to samsung wallet summary implementing the "add to wallet" feature enables your users to add your digital content, such as tickets, passes, and loyalty cards, to the samsung wallet application on their mobile device as wallet cards. in addition to implementing the "add to samsung wallet" button in your mobile application, you must also create a server application that securely generates and signs the wallet card data and returns it to the mobile application for transmitting to samsung wallet. for more information about adding "add to wallet" to your application, see implementing atw button. you can also study the extended sample application (clicking this link downloads the sample code) and the api reference. if you have questions about or need help with the information presented in this article, you can share your queries on the samsung developers forum. you can also contact us directly for more specialized support through the samsung developer support portal. resources click the links below to download the sample code. android app sample code extended android app sample code cdata generation server sample code
Mobassir Ahsan
tutorials
blogatw/v3/{certificateid}/{cardid}#clip?pdata={pdata} so, for example, if your certificateid is a123, cardid is 3h844abcdefg00, and refid is ref-001, then the slim api url for the add to wallet operation is: https://a.swallet.link/atw/v3/a123/3h844abcdefg00#clip?pdata=ref-001 to add the card to their wallet using this method, the user needs to simply visit this url from their device. once the user clicks the link, the samsung wallet server requests the card data from the previously configured get card data api and adds the wallet card to the device. notethe only information required to add a card to the device is the pdata (also known as refid). ensure that this value is a unique hash identifier so that it cannot be easily compromised by third parties figure 1: adding a card to the wallet using data fetch link updating card data using an update notification samsung wallet allows partners to update any issued card’s data using the previously configured get card data api. the card data can be updated in one of the following two ways: the card data is refreshed automatically every time the user opens the card in the detail view. the card data update is triggered manually when the partner sends an update notification. in this case, the card data is updated even when samsung wallet is running in the background, and it is not necessary to open the card in the detail view. when an update notification is sent, the state of the card is immediately updated on the device. afterwards, when the user opens samsung wallet in their device, the card data attributes are refreshed by calling the get card data api. this ensures that the wallet card data is always updated right before the user views it. in order to update card data manually and notify the user about the change, we need to configure the changes in the card data and then send an update notification to the samsung wallet server. once the update notification api is called following the specification, the card’s status and data are updated on the user’s device automatically. samsung wallet uses the refid as the unique identifier of samsung wallet cards. therefore, the refid of the specific card must be included in the payload of the update notification request in order to update the card. the complete specification for the update notification api can be found in the documentation: method: post api path: the request needs to be sent at:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/updates for the samsung wallet server domain url, we can either use the public domain (https://tsapi-card.walletsvc.samsung.com) or the private domain we received in our api callback. request header: the header must contain the authorization, x-smcs-partner-id, and x-request-id request header fields. the samsung wallet server uses this header information to verify the authenticity of the request. additionally, the header also needs to specify the content-type header, which must be set to application/json. request payload: the payload of the update notification must contain the card type, refid, and the new state of the card. optionally, the payload can also contain the fields to be updated so that only those specific fields are retrieved and updated. the payload must be in the following json format: { "card": { "type": "{card type}", "data": [ { "refid": "{ref id}", "state": "{update/deleted/expired}", "fields": "{fields, comma-separated, optional}" } ] } } steps for using the update notification: configure the authorization token. prepare the card data in your server for updating. prepare the header and payload with the refid of the selected card for updating. send the post request to the samsung wallet server for updating. once you send the update notification post request following the specification, the samsung wallet server updates the card on the user’s device. let us modify the data of the previously added card from our server and then call the update notification api. configuring the authorization token all samsung wallet server apis require the use of a bearer authorization token in order to ensure the security and authenticity of the request. you can find the complete specification of the authorization token required by samsung wallet in the documentation the authorization token generation process is very similar to generating cdata, except that for cdata, the payload needs to be encrypted first. for the authorization token, the payload is in plaintext and only contains the api path for verification. to create the bearer authorization token: configure the json payload that describes the method and api path of the request. configure a custom jws header following the jwt format specification. create a jws object using the payload and custom jws header. sign and validate the complete jws object with your partner private and public keys using the rs256 asymmetric algorithm. the complete function to generate the authorization token is given below: fun generateauthorizationtoken(): string{ val payload:string = getstringfromfile("sample/payload/api_path.json") .replace("{refid}", refid) .replace("{method}","get") .replace("{path}","/wltex/cards/cardid/updates/") val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("auth") .customparam("partnerid", partner_id) .customparam("certificateid", "a123") .customparam("ver", "3") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } preparing card data for update once the update notification is sent, the samsung wallet server queries the get card data api endpoint for the updated card data and then updates the wallet card with the latest data provided by the api. so before calling the update notification, make sure the card data provided by the api is up-to-date. for our example, let us change the value of the seatnumber field from a-07 to e-05 before calling the update notification api. prepare the request header and payload for the update notification the post request header contains the following fields: authorization, x-smcs-partner-id, and x-request-id. for our example, we set our partner id as the x-smcs-partner-id, a randomly generated code as x-request-id, and generate a bearer token following the authorization token generation process mentioned previously and use it as the authorization field value. next, we set the json payload, according to the previously mentioned format: { "card": { "type": "ticket", "data": [ { "refid": "ref-001", "state": "updated" } ] } } since the fields field is optional, we have omitted it in this example. sending the update notification to the samsung wallet server once everything is ready, we send the update notification post request to the samsung wallet server. we can use any method to send the request, such as postman, curl, or a plain http request. make sure that the update notification is sent immediately after generating the authorization token, as the token only has a ttl (time to live) of 30 seconds. once the update notification is sent, the user should immediately receive a “card information updated” push notification informing them of the card update. afterwards, the next time the user opens the samsung wallet application, the card details are up-to-date and the user can see their new seat number in their card. figure 2: updating card data using an update notification cancelling an event using a cancel notification there are times when you might need to cancel an event and recall all the issued wallet cards for it. in such case, samsung wallet makes it possible to cancel all issued cards with a specific eventid and send a notification regarding the cancelation to all users with the cards associated with the event. therefore, it is no longer necessary to modify issued cards one-by-one using their refid. instead the card issuer can cancel all cards under the event at one time. the process of sending a cancel notification is the same as the update notification process, except for the following differences: the payload needs to contain the eventid instead of the refid the state must always be canceled the post request endpoint url is:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/cancels you can find the complete specification for the cancel notification api in the samsung wallet documentation. now let us send a cancel notification following the same process as update notification: configure the authorization token. prepare the payload with the eventid for cancellation. send the post request to the samsung wallet server for cancellation. for our example, we add a few cards with the same event id to our wallet in different devices, then send a cancel notification following the specification. once the cancel notification is sent, all samsung wallet cards with the given eventid are deleted automatically from all devices and the affected users receive a "ticket canceled" push notification. figure 3: canceling an event using a cancel notification conclusion in this article, we have learned how to configure our server to use the get card data api, as well as how to use various samsung wallet server apis to add, update, delete, and cancel samsung wallet cards from user devices. if you have any further queries regarding this process, feel free to reach out to us through the samsung developers forum.
Mobassir Ahsan
Learn Code Lab
codelabatw button guide to determine where to incorporate the generated cdata and gain further insights into this process you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can utilize the add to samsung wallet service by yourself! to learn more about samsung wallet, visit developer samsung com/wallet
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.