Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
Develop Samsung Wallet
docadd to samsung wallet button when user tries to click "add to samsung wallet button", user can dd boarding passes, tickets, coupons, membership card, gift cards and more to the wallet app on their samsung galaxy device follow these guidelines when using the button in your apps, web pages, and email, or when using the qr code on pc browser or kiosk app/mobile web add the "add to samsung wallet" button according to the instructions at [implement the button] /implement-the-button html place the button on the page where the user sees the qr code or barcode for the first time, such as a booking completion or purchase completion page place the button just below or close to the qr code or barcode that can be saved in samsung wallet mms to implement “add to samsung wallet” in an mms message, place the coupon or other content that can be saved to samsung wallet in the message and include the “add to samsung wallet” link at the bottom of the message in an mms message on a samsung mobile device where samsung wallet one ui version 5 0 is installed, the “add to samsung wallet” button is automatically displayed when the "add to samsung wallet" link is included in the message e-mail to add boarding passes, event tickets, coupons, memberships, and gift cards to samsung wallet, users can click “add to samsung wallet” in emails opened on samsung galaxy or galaxy tab devices with samsung wallet installed show the “add to samsung wallet” button with the mobile invitation, booking details, purchase details, or sign-up details included in the email place the button just below or close to the qr code or barcode that can be saved in samsung wallet pc/kiosk place the “add to samsung wallet” qr code on the right side of completion pages for purchases, bookings, and membership card sign-ups, and for coupons, gift cards, and tickets notice for details on how to apply a custom button in the integration, please refer to implementing atw button about atw button images, please refer to image resources for more details
Develop Samsung Wallet
docverify with samsung wallet mdl online rp introduction the following document provides details to online relying party partner to integrate with samsung wallet to get digital credentials data issued to samsung wallet devices from trusted issuers one of the main motivations to introduce this technology is to enable samsung wallet customers to utilize the digital id in their wallets to simplify their online interactions that require identity verification the following are some of the use-cases we expect to satisfy with our online rp support samsung online relying party supports two modalities online same-device rpapp-to-walletapp and online same-device web-to-wallet app we currently do not support cross-device functionality the identity verification as part of samsung wallet is accomplished with the "verify with samsung wallet" button get started to utilize online relying party use-cases, rp partners first need to on-board on the samsung wallet portal pre-requisites – technical and system requirements samsung wallet currently supports same-device rp functionality only device and android os version limitations are given below driver's licenses or state ids can be added to the following galaxy devices galaxy s series - s20 or later galaxy z series - z flip 5g, z fold 5g, z flip 2, and fold 2 or later galaxy a series - a53, a54 mobile driver's license or state id is only available on devices running android 12 s or later app2app sdk rpsdk requirements minimum android sdk rpsdk requires a minimum api level of 26 kotlin 1 7 10 is required integration steps the following steps describe the integration process step1 samsung wallet portal on-boarding please refer wallet portal on-boarding information review the samsung wallet portal on-boarding guide register in the samsung wallet portal and proceed with on-boarding process create a wallet card as the 'relying party' type in wallet portal step2 select app2app or web2app select the integration model app2app or web2app follow steps listed in each subsection implement functions implement verify with samsung wallet follow steps listed in implementing vww button app2app implement partner app with rp sdk follow steps listed in the app2app sdk integration specs web2app implement server apis follow steps listed in the web2app api integration specs step3 test 'verify with samsung wallet' function and release the function to user test overall 'verify with samsung wallet' function remove test mode in wallet portal after test is done expose the 'verify with samsung wallet' function to the user in partner side wallet portal on-boarding information please review the attached partner on-boarding guide for the samsung wallet portal the rp partner needs registration information on the wallet portal wallet portal currently offers 'add to wallet' & ‘verify with wallet’ functionality to rp partners please proceed with the registration by referring to the url of the developer site below connect to partner portal the wallet partners portal access is via url below partner onboarding partner onboarding partner on-boarding details are accessed via url below connect to the wallet partners portal manage wallet cards to use the online rp function, you need to create a card as a relying party type refer to the manage wallet cards overall managing process the following image illustrates the process of managing samsung wallet cards create wallet cards draft status partners can create and manage their wallet cards with this step-by-step guide manage wallet cards partners can manage all registered wallet cards partners can edit wallet cards and check their status general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the samsung wallet item description testing mode all data generated during testing mode is periodically deleted be sure to turn off the 'testing mode' setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name automatically generated partner app package name partner app package name wallet card template pre-defined partner’s wallet card template type > sub type > design type wallet card custom setting type authentication issuer set the authentication issuer for the relying party service to be provided as this wallet card please select authentication issuers from the identity provider groups only authentication issuers with the same “service location” as the relying party service are displayed ※ the identity provider of the “authentication issuer”is supported depending on the "service location" set partner get card data url through which a partner receives a card data inquiry api callif a partner uses this api, enter the url otherwise, leave it blank ※ the attribute could be activated with the approval of a manager partner send card state url through which a partner receives a card data inquiry api callif a partner uses this api, enter the url otherwise, leave it blank ※ the attribute could be activated with the approval of a manager samsung server ips samsung wallet server ips which need to be allowed at the partner’s firewall separately described for inbound and outbound calls service location select a regional limit for the wallet card if there was no selected location, the wallet card is shown in all locations if the specified location was selected, the wallet card is shown only in the selected location users can 'verify with samsung wallet' only in service locations where the wallet service is provided ※ the identity provider of the “authentication issuer” is supported depending on the "service location" set main headquarters location check to set it as a 'main location' as the company's main service country head office for creating and proceeding with wallet cards, notification e-mails such as wallet card approval requests are sent only to the selected main location wallet card data save in server set whether to store wallet card data in the server to protect personal information if the card has sensitive information, you can contact the developer support team not to save it description description of the wallet card select template partners can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id ※ for rp partners select "relying party type > other sub type" to set the relying party wallet card partners can select the type of wallet card needed to register from the 'select wallet card template' pop-up first, select the wallet card type and then select the wallet card sub type to select one of the templates belonging to it wallet card custom setting you must set the attributes of the "wallet card custom setting" according to the wallet card ttype you selected ※ for rp partners the "authentication issuer" attribute is a unique property of the relying party card the identity provider of the authentication issuer is supported depending on the "service location" set e g if service location is in the us, the authentication issuer field only supports an identity provider belonging to the us when the parent hierarchy value is checked, its children values created later are automatically checked in the united states, the authentication issuer is the state government, and the driver's license can be understood as an mdl mobile driver's license view wallet card partners can view all the registered information, edit and delete the wallet card launch wallet cards verifying status partners can launch and activate cards you can activate a card by clicking the launch button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, partners can modify and re-launch the administrator registers the reason for rejection when rejecting a launched wallet card partners will receive an email from the system, including the reason for rejection partners can apply for launching again by checking the reason for rejection and modifying the wallet card information testing mode partners can test a card internally to make sure everything works before officially release to the users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to ‘active’ after administrator approval when the card is activated, it becomes visible to the user verify with samsung wallet integration to integrate the wallet, you need to run the ‘verify with samsung wallet’ script into your system the verify with samsung wallet script is available for both web and android platforms each system has a different composition to implement the verify with samsung wallet button, follow the steps below in order create tokenized card data cdata card data is the actual content data of wallet card and it has several format based on card type please refer to generate_cdata sample code for detail copy the sample verify with samsung wallet script from partner portal’s wallet card page and replace cdata with the data token created above apply the script to your system please see web_integration sample code and app_integration sample code for detail ※ for rp partners the guide below is about 'verify with samsung wallet' please note that the 'verify with samsung wallet' guide is provided as sample code it will be updated on the portal before service opening refer to the 8 implementing vww button below are ‘verify with samsung wallet’ script guide in partner portal to integrate the ‘verify with samsung wallet’ you may need some base data you can find this base data and other necessary information on thepartner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis sequence/flow diagram this section describes the flows that are two currently supported the app2app and web2app ones rp partners should select the model based on their integration preference same-device app2app via native wallet sdk diagram with numbered flows explanation of each flow 2 load button resources the verify with samsung wallet integration and the sample code are both supported 3 check service available devices this is the process of checking whether the device supports the verify with samsung wallet function rp partners can implement it by referring to the provided sample code 4 show button with web link you can implement it by referring to the provided sample code refer to the data transmit link 6 tokenize card data as jwt this step generates cdata and card data token refer to https //developer samsung com/wallet/api/implement-the-button html refer to the wallet card and relying party 7 verify with samsung wallet link the link will invoke the walletapp using applink technology in the meantime, the app2app sdk makes a direct connection between the walletapp and partnerapp 10 getmdocrequestdata deviceengagementbytes the walletapp makes deviceengagementbytes according to the iso-18013-5 and send it to the partnerapp 11 sendmdocrequestdata sessionestablishment the partnerapp build sessionestablishmentbytes iso-18013-5 and encrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations 13 sendmdocresponse encryptedresponse the walletapp sends an encrypted iso-18013-5 response payload to the partnerapp same-device web2app via wallet api diagram with numbered flows explanation of each flow 2 load button resources verify with samsung wallet integration and the sample code both supported 3 check service available devices this is the process of checking whether the device supports the verify with samsung wallet function rp partners can implement this by referring to the provided sample code 4 show button with web link rp partners can implement this by referring to the provided sample code refer to the data transmit link 6 tokenize card data as jwt this step generates cdata, card data token refer to https //developer samsung com/wallet/api/implement-the-button html refer to the wallet card and relying party 7 verify with samsung wallet link the link will invoke the walletapp using the applink technology 10 transfer deviceengagement the walletapp makes deviceengagementbytes according to the iso-18013-5 and sends it to the partnerserver through the wallet server 11 to ~12 request key api send key the wallet backend server converts the data received from the request and cardid information into jwt jws + jwe and delivers it to the partner server the partner server must decrypt the jwt jws + jwe data again the partnerapp build sessionestablishmentbytes iso-18013-5 and encrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations the partner server must create and transmit the data fields required for authentication as jwt jws + jwe in response to the wallet backed server partners should refer to the code links below for encryption, decryption, requiredata 14 send mdoc response the walletapp sends an encrypted iso-18013-5 response payload to the partnerserver through the wallet server 15 request auth api send authentication data the authentication data card information received in step 14 is converted into jwt jws+jwe and transmitted to the partner server the partner server must decrypt the jwt jws + jwe data again pp partner can refer to the code links below for decryption, verify cross-device not supported currently, samsung wallet does not support cross-device functionality this functionality will be added soon data transmit link this is how rp partners can create a data transmit link it is a method of safely including tokenized data within the verify with samsung wallet vww link the format of the vww link for this method is as follows the name data transmit link has been changed from typical flow item value description url https //a swallet link/vww/v1/{cardid}#clip?cdata={cdata} path parameters cardid string 32 required wallet card identifier issued from partner portal when the partner manager signs up for partner services and registers the wallet card they want to service hash path parameters #clip string 5 required parameters for the hash link* the first letter is capitalized query parameters cdata string 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 the chapter 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 wallet cards refer to the wallet cards this chapter defines wallet card data fields for the attributes object of each wallet card type the structure for configuring wallet cards follows the defined specification configuring the card data in the specified formatted json structure is required see the details for each card type type value description card object card object required card information card type string 16 required wallet card type card subtype string 16 required allet card sub type card data[] array of object required wallet card data containerallows up to 6 objects at once data[] refid string 32 required a unique content identifier definedby the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds utc±00 00 data[] updatedat long 13 required data creation timestamp epoch timestamp in milliseconds utc±00 00 data[] language string 8 required default content language code e g , en, ko data[] attributes object required card data attributes * refer to the following chapters for each type data[] attributes {fields} attribute fields by card type data[] localization[] array of object optional information for multilingual support localization[] language string 8 required multilingual content language code e g , en, ko, etc localization[] attributes {fields} for displaying a given language,‘data[] attributes’ can be replaced bylocalized versions * refer to the following chapters for each type 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 for each type }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] } } to ensure secure card data transmission, it must be tokenized in jwt format for this purpose, partner will need the certificate obtained using the partner's email account when signing up for the partner portal for detailed information on secure data tokenization, partners can refer to the security chapter *image resources provided by urls can be cached therefore, for the image resource to be replaced immediately, the corresponding url path must be changed relying party ‘relyingparty’ cards are used for verifier authentication when partners create the verify with samsung wallet button, they will need to create cdata this is the data spec included when creating the cdata of relayingparty type wallet card type wallet card subtype relyingparty others type value description attributes{fields} 1 logoimage string 256 required url of the logo image the file size must not be greater than 256 kb 2 logoimage darkurl string 256 required url of the logo image the file size must not be greater than 256 kb 3 logoimage lighturl string 256 required url of the logo image the file size must not be greater than 256 kb 4 fontcolor string 8 optional display color of the font during user authentication 5 providername string 32 required display name during user authentication 6 clienttype string 32 required information on whether the client operates as an application or web 7 clientpackagename string 32 optional package name for when the client operates as an app example { "card" { "type" "relyingparty", "subtype" "others", "data" [ { "refid" "0613001", "createdat" 1686657600000, "updatedat " 1686657600000, "language" "en", "attributes" { "logoimage" "https //samsung com", "logoimage darkurl" "https //dark samsung com", "logoimage lighturl" "https //light samsung com", "fontcolor" "black", "providername" "company name", "clienttype" "app", "clientpackagename" "com companyname app" } } ] } } implementing vww button for samsung wallet integration, partners will need to insert an "verify with samsung wallet" script into their systems to implement an "verify with samsung wallet" button, partner should follow the procedure below first, proceed with script composition with the sample script on the [partners portal][partners portal] or refer to the integration sample code create the tokenized card data cdata card data is the actual content of the wallet card and it has several formats based on the card type refer to the cdata generation sample code for details important the card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the "verify with samsung wallet” button for "verify with samsung wallet" integration, you may also need some base data you can find that and other necessary information on partners portal implementing vww button on the web this section explains how to implement an "verify with samsung wallet" button using javascript in a web view web button reference with importing api javascript if partner implement the "verify with samsung wallet" button using this script, the button is shown only on the devices that support samsung wallet to automatically parse <samsung wallet> html tags when the page is loaded, partners should include the following standard javascript <script src="https //us-cdn-gpp mcsvc samsung com/lib/wallet-card js" type="text/javascript"></script> partners can use these tags or javascript functions for the web button if they are rendering html and have proper partner permissions partners can also use the script by referring to the various attributes samsung wallet html tag the ‘samsung wallet’ namespace tag defines the placement and various attributes of the "verify with samsung wallet" web button for samsung wallet <samsung wallet type="vww" authtoken="auth_token" cardid="card_id" cdata="cdata" partnercode="partner_code" buttonid="button_id" buttontype="btnvwsw" rdclickurl="rd_click_url" rdimpressionurl="rd_impression_url"></samsung wallet> button attributes attribute type required description type string y service type default is "atw"• "atw" 'add to samsung wallet' • "vww" verify with samsung wallet' authtoken string y api auth tokenit would be generated on the partners portal 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 button attributes samsungwallet addbutton { type "vww", authtoken "auth_token", 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' authtoken string y api auth tokenit would be generated on the partners portal 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 app2app sdk integration specs description & use rp sdk is an app2app sdk for samsung wallet driver's license service online scenarios this sdk provides an implementation for direct communication between the samsung wallet and partner applications build the settings rpsdk requires additional dependencies with dependencies { implementation "rp-sdk-1 0-release aar" implementation "androidx core core-ktx 1 3 2" implementation "androidx lifecycle lifecycle-runtime-ktx 2 7 0" implementation "androidx lifecycle lifecycle-livedata-core-ktx 2 7 0" implementation "io reactivex rxjava2 rxjava 2 2 21" implementation "io reactivex rxjava2 rxkotlin 2 4 0" implementation "io reactivex rxjava2 rxandroid 2 1 1" implementation "com squareup okhttp3 okhttp 4 11 0" implementation "com google code gson gson 2 10 1" implementation "org bouncycastle bcprov-jdk15to18 1 66" implementation "com nimbusds nimbus-jose-jwt 9 37 3" } androidmanifest xml <manifest xmlns android="http //schemas android com/apk/res/android"> <uses-permission android name="android permission internet" /> <queries> <package android name="com samsung android spay" /> </queries> </manifest> r8 / proguard the specific rules are already bundled into the aar which can be interpreted by r8 automatically sdk method app2app sdk supports one method request signature & parameters of the request method fun request targetpackagename string, requestid string, applink string, onresponselistener onresponselistener? = null parameter name description targetpackagename the pakcage name to connect to requestid a random string to identify each request applink the applink built by samsung mcs server guide onresponselistener a listener to receive each events or requests sample code binding button setonclicklistener { rpclientapis request "com samsung android spay", uuid randomuuid tostring , applink, object rpclientapis onresponselistener { override fun ongetmdocrequestdata deviceengagementbytes bytearray bytearray? { log i tag, "ongetmdocrequestdata $deviceengagementbytes " /** * 1 prepare mdoc request data iso-18013-5 * 2 build sessionestablishmentbytes iso-18013-5 * 3 encrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations **/ return "encryptedsessionestablishmentbytes" } override fun onmdocresponse encryptedresponse bytearray { log i tag, "onmdocresponse $encryptedresponse " /** * 1 decrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations * 2 cbor decode it **/ } override fun onmdocresponsefailed exception exception { log i tag, "onmdocresponsefailed $exception " } } } error code explanation the below exceptions might occur through the onmdocresponsefailed callback exceptions name description rpcommunicationexception this error occurs when the data requested by the listener is incorrect rpconnectionfailedexception this occurs when the app 2 app communication between apps is not working this usually occurs when the target package name is written incorrectly web2app api integration specs the api specifications that need to be implemented by the rp partner are described below called by samsung to the rp partner send key send the wallet application key info and return the data field types requested to the client for authentication of the mdl [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/key headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details path parameters cardid string 32 required wallet card identifier * refer to "add to wallet" interfaces for more details refid string 32 required unique content identifier defined by the content provider query parameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, and it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "relyingparty", "subtype" "others", "designtype" "us-01" }} example post {partner server url}/rp/v1 0/{cardid}/{refid}/key content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyymdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtfoddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxscxltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdbyny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nuedrvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmjnq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0zvenbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzddevfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnplekwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgfmodhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvxvketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nxm46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvuqncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuqhtjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbwycvx8wa” } [response] type value description http status code 200 ok payload data string 3000 required jwt data encrypted with the data field types requested to the client for authentication of the mdl [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request send authentication data the data is encrypted according to the requested data and then transmitted along with the data card information [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/auth headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details pathparameters cardid string 32 required wallet card identifier * refer to "add to wallet" interfaces for more details refid string 32 required unique content identifier defined by the content provider queryparameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "idcard","subtype" "drivers","designtype" "us-01" }} example post {partner server url}/rp/v1 0/{cardid}/{refid}/key content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyy mdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd 4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtf oddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad 0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxsc xltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01 yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdby ny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv 3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nued rvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmj nq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0z venbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y 0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzdde vfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnple kwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgf modhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu 5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvx vketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nx m46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvu qncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih 3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuq htjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbw ycvx8wa” } [response] type value description http status code 200 ok400 bad request [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to somethingthat is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request code explanation based on the sample code jwt jws + jwe decryption between the wallet backed server and partner server 1 verify by generateing a jws using the body data // generate jws by the body data private static signedjwt parsejwt final string data { try { return signedjwt parse data ; } catch parseexception e { log error "parserjwt error class {}, error message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "parserjwt error" ; } } // verify jws using samsung public key public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } 2 decrypt the jwe using the jws jweobject parse signedjwt getpayload tostring public static string getdecryptedpayloadfrom final key privatekey, final jweobject data { try { data decrypt new rsadecrypter privatekey privatekey ; // decryption jwe using partner private key return data getpayload tostring ; } catch joseexception e { log error "joseexception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "getdecryptedpayloadfrom error" ; } } 3 convert to the format send by the client public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } generate mdocestablishment 1 generate rsa key per refid public class transactioncontext { private final keypair keypair; // rsa key private final byte[] clientengagement; // body data received through key api, base64url decoded value @equalsandhashcode exclude private int encryptmessagecounter = 0; // count value when encrypted @equalsandhashcode exclude private int decryptmessagecounter = 0; // count value when decrypted } private cache<string, transactioncontext> contextcache; // rsa key management per refid with memory cache // generate and store rsa key per refid only once upon first request public transactioncontext settransactioncontext final string key, final string base64encodedclientengagement { log info "base64encodedclientpublickey {}", base64encodedclientengagement ; this contextcache put key, new transactioncontext keyutils generatekeypair , base64utils decode base64encodedclientengagement getbytes ; return this gettransactioncontextby key ; } // part of retrieving ras key based on refid public transactioncontext gettransactioncontextby final string key { return optional ofnullable this contextcache getifpresent key orelsethrow -> { log info "{} is empty", key ; return new customexception httpstatus bad_request, "no key matching the refid" ; } ; } 2 create request field values @override public mono<list<string>> createrequest final partnerinputdto inputdto { final string mockdata = "{ \"doctype\" \"org iso 18013 5 1 mdl\", \"namespaces\" { \"org iso 18013 5 1\" { \"sex\" false, \"portrait\" false, \"given_name\" false, \"issue_date\" false, \"expiry_date\" false, \"family_name\" false, \"document_number\" false, \"issuing_authority\" false }, \"org iso 18013 5 1 aamva\" { \"dhs_compliance\" false, \"edl_credential\" false } } }"; return mono just collections singletonlist mockdata ; } 3 generate establishment @allargsconstructor public class establishment { private final transactioncontext context; // info of client public key , partner private key, public key private final list<string> strreqs; // data field information required for authentication to the client private final keyring keyring; // rsa key information for jwt jws + jwe encryption and decryption between wallet backed server and partner server } protected cborobject generate { final cborobject sessionestablishment = cborobject newmap ; sessionestablishment set e_reader_key, cborobject fromobjectandtag keyutils getereaderkey context , tag_size ; // generate onekey by public key in transactioncontext sessionestablishment set data, cborobject fromobject cipherutils encrypt context, generaterequestformat getrequestcborobjectsfrom strreqs ; // add request data field information for authentication return sessionestablishment; } generate the response value jwt jws + jwe 1 generate establishment with jwe public static string encryptedstringjwe final key publickey, final string data { // please enter samsung public key and establishment data final jweobject jwe = new jweobject new jweheader builder jwealgorithm rsa_oaep_256, encryptionmethod a128gcm build , new payload data ; try { jwe encrypt new rsaencrypter rsapublickey publickey ; return jwe serialize ; } catch joseexception e { log error "encryptedstringjwe exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "encryptedstringjwe error" ; } } 2 generate jws by jwe public static jwsheader getdefaultjwsheader final string ver, final string certificateid, final string partnerid { return new jwsheader builder jwsalgorithm rs256 contenttype "auth" customparam "partnerid", partnerid // partner id customparam "ver", ver // version customparam "certificateid", certificateid // partner crt id customparam utc, timeutils toutcepochmillifrom timeutils calculateutclocaldatetimefromnow 0 build ; } public static string generatesignedstringjws final jwsheader jwsheader, final key privatekey, final key publickey, final string payload { try { final jwsobject jwsobj = new jwsobject jwsheader, new payload payload ; jwssigner signer = new rsassasigner new rsakey builder rsapublickey publickey privatekey rsaprivatekey privatekey build ; jwsobj sign signer ; return jwsobj serialize ; } catch joseexception e { log error "encryptedstringjws exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "generatesignedstringjws error" ; } } 3 generate jwt jws + jwe public partneroutputdto topartneroutputdto { final cborobject generate = this generate ; final string establishment = base64 geturlencoder encodetostring generate encodetobytes ; final string strjwe = jwtutils encryptedstringjwe keyring gettargetpublickey , establishment ; final jwsheader jwsheader = jwtutils getdefaultjwsheader keyring getversion , keyring getcertificateid , "partnerid" ; return new partneroutputdto jwtutils generatesignedstringjws jwsheader, keyring getsourceprivatekey , keyring getsourcepublickey ,strjwe ; } authentication processing for values in data fields requested for authentication 1 retrieve transactioncontext value stored in cache using refid value @override public mono<transactioncontext> getcontext final partnerinputdto inputdto { return mono just this transactioncontextmanager gettransactioncontextby inputdto getrefid ; } 2 processes the decryption process of the request body data like jwt jws + jwe decryption between wallet backed server and partner server 3 generate mdocresponse public class mdocresponse { private final transactioncontext context; // managed tranactioncontext by refid private final byte[] data; // base64url decoded data after decrypting jwt jws + jwe data public mdocresponse final transactioncontext context, final string inputdto { this context = context; this data = base64utils decode inputdto getbytes standardcharsets utf_8 ; } } 4 get the field values requested for authentication from the data in mdocresponse public string getdata { // sessiondata = { // ? "data" bstr ; encrypted mdoc response or mdoc request // ? "status" uint ; status code // } final cborobject response = cborobject decodefrombytes data ; checktype response, cbortype map ; final cborobject data = response get data ; checktype data, cbortype bytestring ; return cborobject decodefrombytes isencryptedmode ? cipherutils decrypt this context, data getbytestring data getbytestring tojsonstring ; } 5 create a session value using the transactioncontext value managed by refid and then decrypt it private static byte[] processcipher final ciphermode ciphermode, final transactioncontext context, final byte[] bytes { // ciphermode encrypt or decrypt, bytes data passed by the client try { cipher cipher = cipher getinstance "aes/gcm/nopadding" ; final int counter = ciphermode encrypt == ciphermode ? context getencryptmessagecounter context getdecryptmessagecounter ; gcmparameterspec parameterspec = new gcmparameterspec 128, getsessionkeyiv ciphermode identifier, counter ; cipher init ciphermode ciphermode , getsecretkeyspec context, ciphermode info , parameterspec ; return cipher dofinal bytes ; } catch invalidalgorithmparameterexception | nosuchpaddingexception | illegalblocksizeexception | nosuchalgorithmexception | badpaddingexception | invalidkeyexception e { log error "error type {}, message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "processcipher error" ; } } 6 examining data received from the client @override public mono<void> authentication final string response { log info "response info {}", response ; return mono empty ; }
Develop Samsung Wallet
docadd to samsung wallet 'add to samsung wallet' service also known as atw, defines interfaces for users to conveniently add digital contents to samsung wallet service flow user-initiated links 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/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 * refer to security for more details 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/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateid string required certificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardid string required wallet card identifier * it must be generated from partners portal hash path parameters #clip string required parameters for the hash link query parameter pdata string 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 provider-initiated api register card api this is an api that allows partners to provide wallet cards to users request payload must include user information then the user device is notified of card registration through a push notification card data specification card id {card id} is an id issued when the partner manager signs up for partner services and register the wallet card they want to service refer to partner onboarding guide document for details cdata actual payload data in basic json format to communicate between partners and samsung wallet see the details on the below sheet card data token the specific wallet card data mentioned as cdata must be secured in jwt json web token format see a chapter security for details request type value description method post url /atw/v1/cards/{cardid} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer * see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string x-smcs-cc2 string 2 required country code iso-3166-1 alpha-2 of user account path parameters cardid string 32 required wallet card identifier granted from partner portal body parameters cdata object 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 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 container of attributes data[] attributes {fields} required attributes fields by card type *see wallet cards data[] localization[] array of object optional container of localizationed language*see wallet cards localization[] language string 8 required multilingual contenct 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 required type of user identifiere g phonenumber, email account value string required user identifier example success * 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
Develop Samsung Pay
docthe following figure illustrates the ui flow for the “open banking app” option in the samsung wallet application
Learn Code Lab
codelabverify your id with samsung wallet objective learn how to verify a user's identity with the id information registered in their samsung wallet app partnership request to create, manage, and monitor performance of wallet cards with the samsung wallet partners site, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more by visiting samsung wallet partner onboarding process, here in samsung developers notein accordance with the applicable samsung wallet partners agreements, this code lab covers the setup and use of the verify with samsung wallet service for purposes of integrating samsung wallet with partner sites and apps the use cases and corresponding code samples included are representative examples only and should not be considered as either recommended or required overview verify with samsung wallet enables users to utilize the digital id added to their wallets to simplify online transactions that require an identity verification a mobile device with samsung wallet installed is required to verify the user’s identity through this feature this feature uses the relying party card type to verify a user's identity using the id information stored in samsung wallet this feature supports app-to-app app2app and web-to-app web2app integration models the web2app integration supports the partner's mobile web application to request a verification to the samsung wallet app the app2app integration supports the partner’s mobile application to request a verification to the samsung wallet app when the partner site requests the user to verify their identity, the verify with samsung wallet button is displayed the user is redirected to the samsung wallet app where they verify their identity via pin or biometrics once verified, the user's identity information is sent to the partner and the transaction will proceed noteas of 2024, this feature is only available in the united states and can be used by the state government with mobile driver's license mdl support for more information, visit https //developer samsung com/dashboard/support for detailed description, see verify with samsung wallet set up your environment notefor sdc24 attendees, skip this step as it's already done for you proceed to 7 create a verify with samsung wallet button for app2app integration or 9 test the verify with samsung wallet button for web2app integration you will need the following access to samsung wallet partners site samsung galaxy device that supports samsung wallet app samsung wallet app latest version android studio latest version recommended java se development kit jdk 11 or later supported mobile driver's license be added to samsung wallet app internet browser, such as google chrome openssl intellij idea or any java ide optional sample code here is a sample code for you to start coding in this code lab download it and start your learning experience! verify with wallet sample code for app2app integration 802 3 kb start the onboarding process partners can manage wallet cards and monitor performance with the samsung wallet partners site to join as partner generate a private key and certificate signing request csr using the openssl command you can follow the instructions in security factors notea private key enables encryption and is the most important component of certificates while csr, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country proceed to register in the samsung wallet partners site using your samsung account follow the samsung wallet partner onboarding process upload the generated csr for data encryption in encryption setting management section after registration, you will receive a welcome email noteupon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes signed certificate used along with the private key to sign data samsung certificate used to encrypt card data and validate authentication tokens in server api headers create a relying party wallet card follow the steps below to create a wallet card in samsung wallet partners site go to wallet cards > manage wallet card and click add wallet card in wallet card template field, choose [wallet] relying party as wallet card type and relyingparty > others as sub type select the design type and click done in wallet card custom setting, click change, and choose drivers as authentication issuer you can also select specific mdls such as below notethe authentication issuer is a unique property of the relying party card type the identity provider of the authentication issuer is supported depending on the service location set for example, if the service location is in the united states, the authentication issuer field only supports any identity provider in the united states region in main headquarters location, select united states once finished, select save to view all registered information launch wallet cards you can launch and request activation of the cards by clicking the launch button upon agreeing to proceed, the launch button text changes to launched and the card status becomes verifying create a verify with samsung wallet button app2app for the app2app integration, you need to setup the button inside the mobile application in android studio, click open locate the downloaded android project rpclient_codelab from the directory and click ok go to app > kotlin+java > com samsung android sample rpclient > presentation > partners and, in the partnersrequestfragment kt file, add the verify with samsung wallet button inside the oncreateview function glide with this load partner getverifybuttonimage into binding verifybutton set up a click listener for the verifybutton binding verifybutton setonclicklistener { /// add the requestdata variable to prepare the request fields /// add the applink variables to request the card information /// call the applink method to request verification } inside the listener, add the requestdata variable to prepare the request fields for verification val requestdata = demodata requestdata add the applink variables to request the card information val applink = rpclientapis buildapplink partnerid = partner getpartnerid , cardid = partner getcardid , payload = partner buildapp2apppayload , samsungpublickey = partner getsamsungpublickey , partnerpublickey = partner getpartnerpublickey , partnerprivatekey = partner getpartnerprivatekey , isstagingserver = true the data being requested are as follows partnerid = gets the partner id from the identification card used cardid = gets the card id from the identification card used payload = builds the app2app payload samsungpublickey = gets the samsung public key partnerpublickey = gets the partner's public key partnerprivatekey = gets the partner's private key isstagingserver = checks if the application runs on a staging environment noterequested data such as partnerid, public keys, and private keys are generated during the onboarding process, while cardid is generated when you create a wallet card however, in this code lab, these data is already predefined and included in the sample mobile app call the applink method to request verification this method creates a channel between the test app and samsung wallet app to create the request and response data for the verification process applink? let { log i tag, applink rpclientapis request "com samsung android spay", uuid randomuuid tostring , applink, object rpclientapis onresponselistener { override fun ongetmdocrequestdata deviceengagementbytes bytearray bytearray? { log i tag, "deviceengagementbytes=${deviceengagementbytes tohex }" val keypair = securerepository generateeckeypair log i tag, "requestdata=$requestdata" val encryptedsessionestablishmentbytes = securerepository buildsessionestablishment requestdata, deviceengagementbytes, keypair log i tag, "encryptedsessionestablishmentbytes=${encryptedsessionestablishmentbytes? tohex }" return encryptedsessionestablishmentbytes } override fun onmdocresponse encryptedresponsebytes bytearray { log i tag, "encryptedresponsebytes=${encryptedresponsebytes tohex }" try { val plainresponse = securerepository decryptmdocresponse encryptedresponsebytes log i tag, "plainresponse=${plainresponse? toprettyjson }" val responsedata = plainresponse? toprettyjson onresponse postvalue responsedata } catch e exception { e printstacktrace } } override fun onmdocresponsefailed exception exception { log i tag, "onmdocresponsefailed ${exception} " onerror postvalue exception } } } run and test the application app2app go to build > build app bundle s / apk s > build apk s to build the application install the apk file to your mobile device and test the sample app as follows open the sample app and choose sdc code lab press the verify with samsung wallet button once you are redirected to the samsung wallet app, press the verify button the samsung wallet app shows a checkmark to indicate that the identity has already been verified while the sample app displays a verification success screen test the verify with samsung wallet button web2app for the web2app integration, you can use the test tool to test the verify with samsung wallet button open a web browser on your computer or galaxy mobile device and go to the following link partner walletsvc samsung com/addtowallettest go to verify with wallet tab and click choose key file to upload your private key in the select card dropdown menu, select the card you created to display its details navigate to the form tab and modify the data as desired you can change the logo image or provider name press the verify with samsung wallet button once you are redirected to samsung wallet, press the verify button the samsung wallet app shows a checkmark to indicate that the identity has already been verified go back to the test tool, open the mdoc tab, and click the check result button it displays a result success popup when the verification process is successful tokenize card data and implement the verify with wallet button to your service optional notethis step is optional, but if you want to learn how to integrate the verify with wallet button into your services like an android app, web app, or email, you can follow these steps the samsung wallet partners site provides generated verify with samsung wallet scripts for each wallet card you create you can simply copy and paste these scripts into your partner apps web and android or include them in emails/mms messages to implement the verify with wallet button, follow these steps go to the [verify with wallet script guide] section of the card you created click show to view the available scripts and then copy the appropriate script for your service develop a program that can generate tokenized card data cdata the cdata represents the actual content of the wallet card and comes in different formats depending on the card type you can check the cdata generation sample code for reference the cdata is derived from the card data, which is in json format for testing purposes, you can utilize the generated json from the test tool follow the implementing button guide to determine where to incorporate the generated cdata and gain further insights into this process you are redirected back to your app and your identity is verified you're done! congratulations! you have successfully accomplished the topic of this code lab now, you are ready to verify your id with the verify with samsung wallet button into your application on your own! to learn more about samsung wallet, visit developer samsung com/wallet
Learn Code Lab
codelabutilize the add to samsung wallet service for digital cards notescenes in the demo video are simulated and does not represent any real-world conditions or outcomes objective learn how to use the add to samsung wallet service so that users can store digital contents, such as boarding passes, tickets, and coupons, to their samsung wallet app partnership request to create, manage, and monitor performance of wallet cards with the samsung wallet partners site, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more by visiting samsung wallet partner onboarding process, here in samsung developers overview samsung wallet is an application that securely stores essential items such as boarding passes, tickets, and coupons, making them easily accessible from anywhere with this app, users can access various partner wallet cards in one place, simply by swiping up from the bottom of the screen the add to samsung wallet service provides interfaces for users to conveniently add digital content to samsung wallet here are examples of the supported wallet cards boarding pass journey information such as flights, trains, and buses can be provided as notifications, allowing easy retrieval when checking in by configuring server synchronization, updates to journey information such as gate changes, schedule changes, or cancellations can be received by the users ticket notifications about events and additional information, including benefits, can be provided based on real-time utilization of performances, sports games, movies, and admission tickets, status updates related to expiration and availability can be provided gift card gift card, also referred to as a prepaid card, provides real-time balance and transaction history loyalty loyalty cards function as membership credentials, managing membership information through these cards, loyalty points can be administered and redeemed id id cards can fulfill identification verification purposes, such as identity cards, employee cards, and licenses physical documents can be represented through wallet cards, and near field communication nfc -based authentication can be provided reservation reservation cards can contain diverse online booking details, including rental cars, restaurants, and accommodations ongoing reservation information can be managed as a journey pay as you go pay as you go cards allow users to register services that can be charged and utilized according to their preference for convenient use generic card generic cards enable users to create customized cards by selecting preferred card template layouts and designing elements notedepending on your country or region, some card types are not supported if you need assistance, please contact us at developer samsung com/dashboard/support the image below shows the process of managing wallet cards for more information, refer to manage wallet cards set up your environment notefor sdc24 attendees, skip this step as it's already done for you you will need the following latest version of samsung wallet app from galaxy store samsung galaxy device that supports samsung wallet access to samsung wallet partners site internet browser, such as chrome openssl intellij idea or any java ide optional start the onboarding process partners can manage wallet cards and monitor performance with the samsung wallet partners site to join as partner generate a private key and certificate signing request csr using the openssl command you can follow the instructions in security factors notea private key enables encryption and is the most important component of certificates while csr, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country proceed to register in the samsung wallet partners site using your samsung account follow the samsung wallet partner onboarding process upload the generated csr for data encryption in encryption setting management section after registration, you will receive a welcome email noteupon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes signed certificate used along with the private key to sign data samsung certificate used to encrypt card data and validate authentication tokens in server api headers create a wallet card follow the steps below to create a wallet card in samsung wallet partners site click the wallet cards menu and choose create wallet card fill out the general information form with the details of the wallet card in wallet card template, choose a card type and sub type select the design type and click done you can choose from various types of wallet card templates optimized for partners after inputting all necessary details, click save to set the wallet card status to draft launch the wallet card you can launch and request activation of the card by clicking the launch button upon agreeing to proceed, the launch button text changes to launched and the card status becomes verifying add the card to samsung wallet using the test tool open a web browser on your computer or galaxy mobile device, and go to the following link partner walletsvc samsung com/addtowallettest go to add to wallet tab and click choose key file to upload your private key in the select card dropdown menu, select the created card to display the card details and populate sample data navigate to the form tab and modify the card data as desired notethe structure for configuring wallet cards follows the defined specification you can refer to the full list of card-specific attributes specification scroll down to the bottom of the page and click the add to samsung wallet button click done when a preview of the card shows on your mobile screen with a message indicating that the card has been added to your wallet once the card is added to your samsung wallet app, you can check its details by clicking on it noteyou can also go to the playground tab and add cards to the samsung wallet app even without creating a card on the wallet partners site update the status of the added card if a server api info partner get card data and partner send card state is registered in the wallet card, real-time updates of the user's registered cards can be provided notefor more information, see server interaction modify and update the card's status by utilizing the push notification feature of the test tool navigate to the push notification tab ensure that the correct private key is uploaded and the same card as in the add to wallet tab is selected copy the ref id value from the add to wallet tab and paste it into ref id field in the push notification tab in the status field, enter one of the following card states expired, redeemed, held, suspended, or deleted the current state is set to active then, click the request push notification button check the card in the samsung wallet app to confirm the change tokenize card data and implement the add to samsung wallet button to your service optional notethis step is optional, but if you want to learn how to integrate the add to samsung wallet button into your services like an android app, web app, or email, you can follow these steps the samsung wallet partners site provides generated add to samsung wallet scripts for each wallet card you create you can simply copy and paste these scripts into your partner apps web and android or include them in emails/mms messages to implement the add to wallet button, follow these steps go to the [add to wallet script guide] section of the card you created click show to view the available scripts and then copy the appropriate script for your service develop a program that can generate tokenized card data cdata the cdata represents the actual content of the wallet card and comes in different formats depending on the card type you can check the cdata generation sample code for reference the cdata is derived from the card data, which is in json format for testing purposes, you can utilize the generated json from the test tool follow the implementing atw 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 Pay
doccommon flow once setup is complete, you’re ready to add the samsung pay sdk flutter plugin code within your partner app for calling the samsung pay sdk’s apis and receiving callbacks the following functionalities are ready to call through apis checking samsung wallet status activating the samsung wallet app updating the samsung wallet app checking samsung wallet status the first step in implementing the samsung pay sdk flutter plugin within your partner app is to create the samsungpaysdkflutter instance, this will check the samsung wallet status on the device it's determine the support for samsung wallet or lack thereof , and whether or not to display the samsung pay button to the user for selection as a payment option the samsung pay button also lets issuer apps add a card to samsung wallet in both instances, the partner app must have valid partnerinfo to pass to samsungpay for caller verification to set its partnerinfo, the partner app passes its serviceid sid and servicetype, both of which are assigned by the samsung pay developers portal when you create the service this will be used for checking blocked list and version control between the samsung pay sdk flutter plugin and the samsung wallet app on the device you must set the servicetype in partnerinfo to call other samsung wallet apis string serviceid; map<string,dynamic> data; static final samsungpaysdkflutterplugin = samsungpaysdkflutter partnerinfo serviceid 'partner_app_service_id', data {spaysdk partner_service_type servicetype app2app name tostring } ; after setting partnerinfo, your partner app can now call getsamsungpaystatus this method of the samsungpay class must be called before using any other feature in the samsung pay sdk flutter plugin future<void> getsamsungpaystatus statuslistener? statuslistener the result is delivered to statuslistener and provides onsucccess and onfail events check the android sdk common flow for more details the following sample code shows how to use the getsamsungpaystatus api method myhomepage samsungpaysdkflutterplugin getsamsungpaystatus statuslistener onsuccess status, bundle async { showstatus status, bundle ; }, onfail errorcode, bundle { showerror errorcode, bundle ; } ; activating the samsung walllet app the samsungpaysdkflutter class provides the following api method to activate the samsung wallet app on a device future<void> activatesamsungpay activatesamsungpay is called to activate the samsung wallet app on the same device on which the partner app is running first, the partner app must check the samsung wallet status with a getsamsungpaystatus call if the status is spay_not_ready and extra_error_reason is error_spay_setup_not_complete, the partner app needs to display an appropriate message to user, then call activatesamsungpay to launch the samsung wallet app so the user can sign in here’s an example of how to code this samsungpaysdkflutterplugin activatesamsungpay ; updating the samsung wallet app the samsungpaysdkflutter class provides the following api method to update the samsung wallet app on the device future<void> gotoupdatepage gotoupdatepage is called to update samsung wallet app on the same device on which the partner app is running as with all api calls, the partner app must first check the samsung wallet status with getsamsungpaystatus if this returns spay_not_ready and extra_error_reason is error_spay_app_need_to_update, then the partner app needs to display an appropriate message to the user and call gotoupdatepage , which launches the samsung wallet update page the following code sample reflects how to update samsung wallet samsungpaysdkflutterplugin gotoupdatepage ;
Develop Samsung Wallet
docgetting started samsung wallet cards is an e-wallet service that allows customers using samsung devices to add various digitized contents to samsung wallet users can add their tickets, coupons, boarding passes, and other types of data into samsung wallet using an "add to wallet" link given in online channels like application notifications, web pages, or email and social media messages this document describes how to implement samsung wallet cards service features from the integration partner's point of view integration steps partner account a samsung account is necessary to manage your own service for samsung wallet the account is used to sign up and sign in to the partners portal onboarding the interaction keys are issued from a service onboarding step the partner manager should fill basic information of the company and card details on partner portal, choose the card type and template that fit their contents, which will then provide keys such as card id and partner id to ensure safe data communication, make sure to prepare security key factors samsung will sign the provided csr then deliver certificates used to create the secured data see the document 'samsung wallet partner onboarding guide' for onboarding details see the chapter security for more details add to samsung wallet partner managers have to configure 'add to samsung wallet' button on their contents the button must configure the link to the promised web page with the specific format the linked page will initiate a basic process of storing cards on samsung wallet service see the chapter implement the button for more details every digitized contents on 'add-to-wallet' link is identified by a reference id refid if the same reference id is reused, the existing card will be updated with new data without notice see the chapter "add to wallet" interfaces for more details samsung wallet app won't cache every resource no-cache web contents must be used for interfaces such as cdn in other words, the app won't consider work with '304 not modified' management the stored wallet card contents on samsung wallet can be updated to predefined states if partners want to manage the contents on samsung wallet, interaction between samsung and partner servers is necessary see the chapter server interaction for more details service flow this chapter describes how to bring users' digitized content to samsung wallet once partner service onboarding is complete and card templates are ready, it is possible to add contents such as boarding passes, coupons and tickets into samsung wallet see the service flow below 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
docimage resources button image resources add to samsung wallet buttons [image sample] type locale version image btnsw n/a normal normal, dark vertical vertical, dark btnatsw en-kr, en-us, en-um,en-vi, en-gb, en-vg,en-io, en-fr, en-gf,en-tf, en-pf, en-de,en-it, en-es normal normal, dark vertical vertical, dark fr-fr, fr-gf, fr-tf, fr-pf normal normal, dark vertical vertical, dark de-de normal normal, dark vertical vertical, dark it-it normal normal, dark vertical vertical, dark ko-kr normal normal, dark vertical vertical, dark es-es normal normal, dark vertical vertical, dark [base url] us https //us-cdn-gpp mcsvc samsung com/lib kr https //kr-cdn-gpp mcsvc samsung com/lib [file name] type version file name btnsw normal wallet-card png normal, dark wallet-card-dark png vertical wallet-card-ver png vertical, dark wallet-card-ver-dark png btnatsw normal add-to-samsung-wallet_{locale} png normal, dark add-to-samsung-wallet_dark_{locale} png vertical add-to-samsung-wallet_ver_{locale} png vertical, dark add-to-samsung-wallet_dark_ver_{locale} png [default value of each resource property] brandname samsung wallet add to samsung wallet button type btnsw locale en-us version normal verify with samsung wallet buttons [image sample] type locale version image btnsw n/a normal normal, dark vertical vertical, dark [file name] type version file name btnsw normal wallet_button_at_hor_pos_rgb png normal, dark wallet_button_at_hor_rev_rgb png vertical wallet_button_at_ver_pos_rgbr png vertical, dark wallet_button_at_ver_rev_rgb png download assets samsung wallet logo asset v2023_1 0 29 81 mb march 07, 2023 to make an "add to wallet" button in your own style, download this graphic asset and customize it for details on how to apply a custom button in the integration, refer to implement the button download the samsung wallet logo toolkit samsung wallet logo toolkit v2023_1 0 14 56 mb march 07, 2023 this toolkit provides guides about samsung wallet logo composition and its usage
Develop Samsung Pay
docenable app to app service adding payment cards to samsung wallet from the card issuer’s app requesting registered card list in the samsung wallet getting wallet information adding a card to samsung wallet requesting registered card list in the samsung wallet the getallcards method of the cardmanager class is used to request a list of all cards currently registered/enrolled in samsung wallet on the same device running the issuer’s app to succeed, the issuer app must pass valid partnerinfo to 'cardmanager' for caller verification 'cardfilter' narrows the card list returned by samsung wallet to the issuername specified please be noted that getsamsungpaystatus must be called before getallcards getallcards could not return a cards list when getsamsungpaystatus responds with a code other than spay_ready as of api level sdk version 1 4, cardfilter retrieves this information from the samsung pay developers portal certain issuers may need to register multiple issuer name s with the portal, depending on their app and/or the requirements of their token service provider tsp the getallcards parameter cardfilter matches the issuer name s specified with those registered in the portal only complete matches are returned this method is typically called when your partner app wants to check the card status it does not need to be called every time the partner app resumes therefore, you should create the card list with the 'oncreate ' method, rather than the 'onresume ' method the result of a getallcards call is delivered to getcardlistener, which provides the following events onsuccess - called when the operation succeeds; provides the list of all filtered cards and their status card information includes cardid, cardstatus, and extra cardinfo data onfail - called when the operation fails here’s an example of how to use the 'getallcards ' api method in your issuer app samsungpaysdkflutterplugin getallcards getcardlistener onsuccess list { showcardlist list ; }, onfail errorcode, bundle { showerror errorcode, bundle ; } ; getting wallet information the samsungpay class provides the getwalletinfo api method, which is called to request wallet information from the samsung wallet app prior to calling the addcard api, when you want to avoid duplicate provisioning your issuer app uses this information to uniquely identify the user and the samsung wallet app on a particular device wallet device management id, device id, and wallet user id void getwalletinfo statuslistener? statuslistener the following example demonstrates how to use it string serviceid; spaysdk partner_service_type servicetype app2app name tostring samsungpaysdkflutter partnerinfo serviceid "", data {} ; samsungpay=samsungpay context,partnerinfo val keys = arraylist<string> keys add samsungpay wallet_dm_id keys add samsungpay device_id keys add samsungpay wallet_user_id samsungpaysdkflutterplugin getwalletinfo statuslistener onsuccess status, bundle async { val deviceid string? = walletdata getstring samsungpay device_id val walletuserid string? = walletdata getstring samsungpay wallet_user_id }, onfail errorcode, bundle { util showerror context, errorcode, bundle ; } ; adding a card to samsung wallet your issuer app calls the addcard api method of cardmanager to add a card to samsung wallet by providing the required card details, your app can make it convenient and easy for users to add their bank-issued debit/credit cards to samsung wallet directly from your app without additional steps, like switching between apps for most issuers, getwalletinfo suffices for requesting current wallet information the response from samsung wallet tells the issuer app whether or not the user’s card has already been added to samsung wallet or is ineligible for provisioning it is therefore recommended that you call getwalletinfo before displaying the add to samsung pay button if the card is eligible, display the “add” button and, if the user taps it, call addcard the addcard result is delivered to addcardlistener, which provides the following events onsuccess - called when the operation succeeds; provides information and status regarding the added card onfail - called when the operation fails; returns the error code and extra bundle data such as extra_error_reason or extra_request_id if provided onprogress - called to indicate the current progress of the 'addcard ' operation; can be used to show a progress bar to the user in the issuer app this callback is supported for tsm solution issuers in china and spain here’s an example of how to use the addcard api method in your issuer app string cardtype; string tokenizationprovider; string testpayload = "testpayloadcardinfoforflutterplugin" map<string, dynamic> carddetail; carddetail {addcardinfo extra_provision_payload testpayload} ; var addcardinfo = addcardinfo cardtype walletcard card_type_credit_debit, tokenizationprovider gettokenprovider tokenprovider tostring , carddetail {addcardinfo extra_provision_payload payload} ; myapp samsungpaysdkflutterplugin addcard addcardinfo, addcardlistener onsuccess status, card { print "success $status / data $card" ; },onfail errorcode, bundle { util showerror context, errorcode, bundle ; print "error $errorcode / data $bundle" ; },onprogress currentcount, totalcount, bundle { print "currentcount $currentcount / totalcount $totalcount / data $bundle" ; } ;
Preferences Submitted
You have successfully updated your cookie preferences.