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
docatw"• "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 * refer to usage of onclickbutton handler for more details 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 * refer to usage of onclickbutton handler for more details 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 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 } } 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 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, defines interfaces for users to conveniently add digital contents to samsung wallet service flow preparation 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 see the chapter implement the button for more details 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 partners can consider the option*data fetch link* when they provide full content data 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 for interactions after storing contents on samsung wallet, server interfaces are needed which is defined on the chapter server interaction update wallet cards if the wallet card contents should be updated by partners, they must call samsung server api path parameter 'cc2' must be set to the value brought from callback named 'send card state' api which includes 'added' event see a chapter samsung server api for more details update notification is for single content cancel notification is for calling off every user's wallet card contents 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 card states wallet cards have several states for each content provider’s notifications and user actions the state diagram below describes wallet card states from beginning to end state diagram
Develop Samsung Wallet
docatw 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/atw/v1/{cardid}#clip?cdata={cdata}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 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 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/v1/{cardid}#clip?pdata={pdata} https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateid string 4 conditional certificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardid string 32 required wallet card identifier * it must be generated from partners portal hash path parameters #clip string 5 required parameters for the hash link query parameter pdata string 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 example web link https //a swallet link/atw/v1/1656147182764415319#clip?pdata=sighcziwm9g https //a swallet link/atw/v3/ymtt/1656147182764415319#clip?pdata=sighcziwm9g updating wallet cards the added users’ cards allow updating its data using server interactions find the card details to configure api on partner portal if partners want to manage the added cards 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 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 returns the current information of the card 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 * see 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 the card includes sensitive data, it is highly recommended to use 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-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet" *see 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 fromfulfilling the request 503 service unavailable server is not ready to handle the request send card state partners can 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 /wallet/api_new/references/security html x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * see the ["add to wallet" interfaces]["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 partners can notify their contents changes with the following api service domain environment domain public domain https //tsapi-card walletsvc samsung com private domain ‘callback’ field from send card state api request payload the domains can be selectively used depending on your service requirement if the service needs to register static ips on your system, we recommend using private domain in this case, use the domain received in the request 'callback' field from send card state api if the service does not require ip registration, public domain can be a good choice in this case, country code cc2 is required as a path parameter to configure integration for each environment, register a new card service and get new card id to guarantee safe communication, servers should configure token-based authentication see authorization token for the details update notification if wallet card data content is updated, send a notification to the samsung server 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 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 card states 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 bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o 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 ok 204 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 somethingthat 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 fromfulfilling the request 503 service unavailable server is not ready to handle the request cancel notification if a cancelation happens for events such as performances, sports, movies, and journeys, partners can send a notification about it and set all of the related cards to expire this api does not support updates for specific attributes on the card 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 required if "card type" has been set as "boardingpass" data[] estimated oractualstartdate long 13 data[] state string 16 required wallet card state for example canceled* see card states for details example post /wltex/cards/12584806754/cancelation [headers] authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140004 [payload] * a movie ticket has been canceled { "card" { "type" "ticket", "data" [ { "eventid" "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 somethingthat 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 fromfulfilling the request 503 service unavailable server is not ready to handle the request implementing button for wallet integration, you need to insert ‘add to wallet’ script into your system we usually follow the procedures below to implement the ‘add to wallet’ button first, proceed with script composition with the sample script on the partners portal or see the integration sample code second, create tokenized card data cdata and insert the data token into the script above card data is the actual content data of wallet cards and has several formats based on card type please see generate_cdata sample code for detail importantcdata 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 samsung wallet on the web this section explains how to implement an "add to wallet" button using javascript in a 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're 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 type required description 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 * see security partnercode string y partner code * value granted from the partners portal buttonid string y dom element id for the "add to wallet" web button for samsung wallet buttontype string n "add to wallet" button type [ "btnsw" / "btnatsw", default btnsw ] * see image resources inline string n flag to display the "add to wallet" image button in one-line format default true one-line locale string n locale of the "add to wallet" image button * see image resources 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 "add to 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 target string n option to choose button’s target name * default “wallet” 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 * see usage of onclickbutton handler samsungwallet addbutton function this function allows you to explicitly render the samsung wallet api for the "add to wallet" web button 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 unlike the samsung wallet html tag, you must use camelcase in the button attributes in function case attributes type required description 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 * see security partnercode string y partner code * value granted from the partners portal targetid string y dom document object model element id to place the "add to wallet" web button for samsung wallet buttonid string y dom element id for the "add to wallet" web button for samsung wallet buttontype string n "add to wallet" button type "btnsw" and "btnatsw" default btnsw * see image resources inline string n flag to display the "add to wallet" image button in one-line format default true one-line locale string n locale of the "add to wallet" image button * see image resources rdclickurl string y url of logging a button click event * value granted from the partners portal rdimpressionurl string y url of logging a button impression event *value granted from the partners portal showforced string n flag to force the "add to 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 a custom style target string n option to choose button’s target name * default “wallet” 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 * see usage of onclickbutton handler usage of onclickbutton handler you can choose whether to proceed with the next "add to wallet" step using a promise or a callback function, if you register a callback handler in onclickbutton 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 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 'add to 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 ‘add to wallet’ process onclickbutton async options => { return new promise async resolve, reject => { // todo partner's process await resolve flag } } importantthe 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 the following outline explains how to implement the "add to wallet" button on a native application get button graphic resources from a repository depending on your service environment for more information, see image resources check availability by calling the "check service available devices" apo, then determine whether to show up the "add to wallet" button on the user device a if "available" on response has "true" -> support b if has "false" -> not support implement a jwt web link on the button triggered action app button reference 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 ; } } importantthe 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 an mms/email the following guides how to configure wallet code on email and mms messages implement the data fetch link process, including server apis you need to create a unique "reference id" for security reasons, make sure the "reference id" is complex enough that no important information can be inferred deliver a message including the web link through the chosen message platform for mms, the designed link shows up as a "smart suggestion" on samsung devices you can find a sample web link 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 link to “add to wallet” on an mms/email you can add an “add to wallet” web button even 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 type required description url string y “add to wallet” link url * see [data transmit link][data transmit link] * see [data fetch link][data transmit 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 type required description url string y “add to wallet” link url * see [data transmit link][data transmit link] * see [data fetch link] [data transmit link] image_url string y button’s image resource url * see image resources rd_impression_url string y impressions logging url * value granted from the partners portal statistics service samsung wallet serves useful statistics data of the integrated service on the partners portal the data configured by making simple api calls for each event such as button impression and click these are necessary to provide better services as well notestatistics api sample code you can find actual code sample at wallet script guide section in [‘wallet cards’ menu on the partner portal ][wallet cards] 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
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
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
Develop Samsung Wallet
docatw/v1/cards/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required wallet card identifier granted through the partner portal body parameters cdata object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object card object required wallet card object card type string 16 required wallet card type *see wallet cards card subtype string 16 required wallet card sub 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 data creation timestamp epoch timestamp in milliseconds *utc±00 00 data[] updatedat long 13 required data update timestamp epoch timestamp in milliseconds *utc±00 00 data[] language string 8 required default card language code e g en, ko data[] attributes object required attributes container data[] attributes {fields} required attributes fields by card type*see wallet cards data[] localization[] array of object optional localized language container *see wallet cards 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 account object conditional user account object account type string 16 required type of user identifier, e g phonenumber, email account value string 64 required user identifier example * example card object { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678” } } * example post /atw/v1/cards/1656147182764415319 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr [payload] { "cdata" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload n/a example 200 ok [result]] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable
tutorials mobile
blogatw button documentation. card specifications to complete the "add to samsung wallet" button implementation, you must generate the card data token and create a final url. for more information, see add to samsung wallet. let’s start by reviewing the generic card specifications to generate the card data token. the generic card follows the specifications below. for more information on them, see the generic card section. name description title the main title of the generic card. in the sample card, the title is "card title." in the image below, the title is "insurance identification card." subtitle the subtitle of the generic card. in the sample card, it is "card subtitle". providername use this field to set the card provider name. for more information, check the card json example below. however, the provider name depends on your card type and should be modified accordingly. eventid enter an id as an event identifier. in case your card is prepaid, for example a gift card, or if you have vouchers to events, such as concerts, it is possible to define an event id. for instance: "event-001". groupingid enter an identifier to group related cards. startdate enter the starting date and the epoch timestamp in milliseconds. startdate.relativenotitime enter the amount of time within which you want to provide a notification to the user. the notification time is the relative time from the startdate. the value can be up to 2880 milliseconds. enddate enter the end date and the epoch timestamp in milliseconds. enddate.relativenotitime enter the amount of time within which you want to provide a notification to the user. the notification time is the relative time from the enddate. the value can be up to 2880 milliseconds. logoimage set the logo image url. the file size must not exceed 256 kb. also this image can be set from the template editor. logoimage.darkurl set the logo image url for the dark mode. the file size must not exceed 256 kb. logoimage.lighturl set the logo image url for the light mode. the file size must not exceed 256 kb. bgimage set the background image url. the file size must not exceed 512 kb. text{i} set the label-text value that should be displayed for each field containing the details of your card. the label is defined in the template editor, shown in the image below. to set the value of the label, update the json file. image{i} enter the image url, such as: "https://www.samsung.com/images/image1.png". this url is just an example, you must update it according to your needs. this field only works in generic card type3. we have used a type1 card in the example. so this field in the example json has no effect on the card. you can find all three card type sample uis here. image{i}.lighturl enter the image url in light mode, such as: "https://www.samsung.com/images/light.png". this url is just an example, you must update it according to your needs. image{i}.darkurl enter the image url in dark mode, such as: "https://www.samsung.com/images/dark.png". this url is just an example, you must update it according to your needs. serial{i} set the serial for barcode or qr code. serial{i}.serialtype serial presentation type. for more information on the presentation types (serialtype), see references. serial{i}.ptformat set the presentation format. for more details on the presentation formats (ptformat), see references. serial{i}.ptsubformat set the presentation subformat here. for more details on the barcode formats (ptsubformat), see references. serial{i}.errorcorrectionlevel set the error correction levels in this field. the amount of redundancy or error correction data included in the code varies. qr codes offer four levels of error correction: l, m, q, and h. the qr field looks like the following in your card: privacymodeyn set the user authentication if required. set the value to "y" or "n" bgcolor set the card art color. fontcolor set the card art font color. nonetworksupportyn set the value to "y" to open the wallet card when under the "no network" status. otherwise, set the value to "n" noticedesc set the the notice description here. see the image below of how it is added to card. applinklogo add the application link logo url in this field. applinkname add the application link name in this field. applinkdata add the application link url in this field. locations list of locations where the card will be used. this information can be used to provide location-based services. samsung wallet can use this information to show maps, names of places, and addresses. for more information on the locations field and json format, check references. card json example in previous sections, you have learned about the card specifications. next, let’s implement the generic card fields according to your needs. in this section, as the aim is to create an insurance card, you must use the fields accordingly. samsung provides a specifically formatted json structure. you need to configure the card data objects within the structure’s data array. for more details, see the generic card section. { "card": { "type": "generic", "subtype": "others", "data": [ { "createdat": 1709712961000, "updatedat": 1709712961000, "language": "en ", "refid": "933533e1-9284-461c-905f-bc177526a8d1", "attributes": { "title": "insurance identification card", "subtitle": "insurance card", "providername": "samsung insurance co.", "eventid": "1", "groupingid":"1", "startdate": 1731299205000, "startdate.relativenotitime": 500, "enddate": 1731320805000, "enddate.relativenotitime": 400, "logoimage": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "logoimage.darkurl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "logoimage.lighturl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "bgimage": "", "text1": "1234567", "text2": "samsung insurance co.", "text3": "jaqueline m", "text4": "samsung motors 2014 galaxy5", "text5": "11sam23sung3t", "text6": "(031)000-1235", "image1": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "image1.darkurl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "image1.lighturl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "serial1.value": ">1180mm2241b7c 0000000000000298060000000000 0 090870907 ", "serial1.serialtype": "qrcode", "serial1.ptformat": "qrcode", "serial1.ptsubformat": "qr_code", "serial1.errorcorrectionlevel": "m", "privacymodeyn": "y", "bgcolor": "#3396ff", "fontcolor": "#ffffff", "nonetworksupportyn": "n", "noticedesc": "{\"count\":2,\"info\":[{\"title\":\"notice1\",\"content\":[\"description1\",\"description2\"]},{\"title\":\"notice2\",\"content\":[\"description1\",\"description2\"]}]}", "applinklogo": "https://www.samsung.com/logo.png", "applinkdata": "https://www.samsung.com/", "applinkname": "samsung insurance co.", "locations": "[{\"lat\": 37.2573276, \"lng\": 127.0528215, \"address\": \"suwon\", \"name\": \"digital city\"}]" } } ] } } generic card testing with the "add to wallet" test tool now, you can test the generic card with the "add to wallet" test tool provided by samsung. just follow these steps: sign in to the add to wallet test tool. for more information, see the samsung wallet test tool. enter the private key in the "enter partner private key" field. in this tool, you find all cards that you have created from the samsung wallet partner site in the "select card" section. for more information, see the samsung wallet partner site. select the generic card that you have just created. now select json from the data field and modify the existing json data fields according to the card specification details. after modifying the json data fields, check if the json is valid. finally, if the private key is valid, the "add to samsung wallet" button becomes active at the bottom of the page. then, just click add to samsung wallet to finish adding the generic card. if you use the provided example json and add the card to the wallet, the card looks like the following: server integration in this step, server configuration is needed because the generated jwt token expires after 30 seconds. developers are advised to only generate this token after a user has clicked the "add to wallet" button. as you have already performed testing with the "add to wallet" test tool, you need to configure your server. for more information on the implementation of both the "add to samsung wallet" button and server-side logic, see implementing "add to wallet" in an android application. this article explains how you can distribute your card with your android application and how to generate the jwt token at runtime, after pressing the "add to samsung wallet" button. conclusion you have now learned the basics for how to set up a generic card and test it for your business needs. in case you have further questions, contact samsung developer support. related resources utilize the add to samsung wallet service for digital cards introduce loyalty cards to your application with samsung wallet implementing "add to wallet" in an android application seamlessly integrate "add to wallet" for samsung wallet
M. A. Hasan Molla
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.