Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
Develop Samsung Wallet
docmanage wallet card refer to the partner onboarding guide for the samsung wallet portal the rp partner needs registration information on the wallet portal wallet portal currently offers 'verify with samsung wallet' functionality to the rp partners overall managing process the following image illustrates the process of managing samsung wallet cards create relaying party wallet card template 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 rp get request data url through which a partner receives a card data inquiry api call in case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/key ※ the attribute could be activated with the approval of a manager partner rp send authentication data url through which a partner receives a card data inquiry api callin case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/auth ※ 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 type 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 formats 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 below is ‘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 the partner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis
tutorials web
blogthe previous tutorial, implementing "add to wallet" in an android application, showed how to generate and sign a card data token to add the card to samsung wallet. this tutorial demonstrates how you can perform server interactions with the samsung wallet server and retrieve information such as the card states on a user’s device. if you are a samsung wallet partner who is offering samsung wallet cards to your users, you might also want to know how you can track a provided wallet card’s status on a user’s device. follow along in this tutorial to learn how you can utilize the send card state api and retrieve this information to your own server. all code examples used in this tutorial can be found within the sample code provided at the end of this tutorial for further reference. card states and the send card state api the samsung wallet card’s status on a user’s device is represented by various states, such as added, updated, or deleted. whenever the card state of a card changes on a user’s device, samsung wallet server sends a notification to the configured partner server informing about the change. this api provided by samsung is called the send card state api. figure 1: samsung wallet card state changes samsung provides the send card state api as a means of server-to-server communication between the samsung server and the partner’s server and to let the partner know about the card state of their issued cards on user’s devices. with this api, partners can track the state of a wallet card on a user’s samsung galaxy device. prerequisites before you can test the send card state api, you need to: complete the samsung wallet onboarding process. create a samsung wallet card template. launch the wallet card template and have it in verifying or active status so that the card can be added to a user’s device. have an existing server to receive the notifications. you can use codesandbox or a similar online hosting service for testing. configure your firewall (if you use any) to accept incoming connections from the samsung wallet server (34.200.172.231 and 13.209.93.60). when you have completed all the prerequisites, proceed to the next step to configure your wallet card template to send requests to your server. configure the wallet card template for the send card state api to receive the send card state notifications on your server, you need to set your server’s url in the desired samsung wallet card’s options: go to the wallet partners portal. from the wallet cards dropdown, select “manage wallet card.” click the name of the wallet card. click “edit” and then scroll down to the “partner send card state” section to modify the partner server url. click “save” to set the partner server url for the card. figure 2: partner send card state url input field now, whenever a user adds or deletes an issued samsung wallet card to their device, the samsung wallet server automatically sends a post notification to the partner server url set in the wallet partners portal. next you need to learn about the specification of the request so that you can handle it from the server. send card state api specification and format for a complete description of the send card state api specification, see samsung wallet documentation. request method the send card state api uses a post method to send a request to the server. the api path for the request is fixed and uses the partner server url that you defined in section “configure the wallet card template for the send card state api.” api path and url parameters the api path at the very end of the "partner send card state" section is the path where the samsung server sends the send card state post request. so the complete api path url is: {partner server url}/cards/{cardid}/{refid}?cc2={cc2}&event={event}. here, cardid is the card id of the wallet card template and refid is the reference id field of the issued card data, which is a unique identifier. the cc2 query parameter is the 2-letter country code (iso 3166-1 alpha-2) and event is the card state event (added, deleted, or updated) occurring in the user’s device. consider the following example card configuration: partner server url: https://partner.server.url card id: 123 ref id for the issued card: abc country code: us in this configuration, whenever the user adds the card to their samsung wallet application, the samsung wallet server sends a send card state notification to the following url: https://partner.server.url/cards/123/abc?cc2=us&event=added. similarly, if a user from the united kingdom deletes a card with the refid xyz, the post request is sent to https://partner.server.url/cards/123/xyz?cc2=gb&event=deleted. therefore, you can know if a card was added or removed from the user’s device directly from the query parameters. post request body the post request body does not contain any information regarding the card state. rather it just provides a callback url that you can use if you want to send an update notification for the card. { "callback": "https://us-tsapi.walletsvc.samsung.com" } post request header the post request header contains all the required information for ensuring the authenticity of the request. it contains a request id with the name “x-request-id” and a jwt bearer token credential for authentication with the name “authorization” in the header. the samsung wallet server uses a bearer authorization token to ensure the authenticity of the requests being sent to the partner server. for details of the security factors, see authorization token. the bearer token is encoded in base64 following the jwt specification. it has three parts: jws header containing authentication related information, jws payload containing the api path, method, and refid, and jws signature, which validates that the bearer token is signed by the samsung server. jws header format: { "cty": "auth", // always “auth” "ver": "3", // can also be “2” for legacy card data token "partnerid": "4048012345678938963", // your partner id "utc": 1728995805104, // time of signing in milliseconds "alg": "rs256", "certificateid": "a123" // only provided for token version 3 } jws payload format: { "api": { "path": "/cards/3h844qgbhil00/2e19cd17-1b3e-4a3a-b904?cc2=gb&event=added", "method": "post" }, "refid": "2e19cd17-1b3e-4a3a-b904-f30dc91ac264" } finally, the bearer token contains a signature to verify the token. this is signed using the samsung private key and can be validated using the public key provided by samsung wallet during the onboarding process. after receiving any request from the samsung wallet server, your server should send back an http status code as a response. samsung server expects one of the following codes as a response: 200 ok 401 unauthorized 500 internal server error 503 service unavailable this is the complete specification of the send card state api that you need to be aware of before you implement the server. next, you need to configure your server to accept the post request in the specified format. configure the spring server to receive the post request to receive and interpret the send card state post notifications sent by the samsung wallet server, you need to configure a partner server and host the server at the url you specified earlier. to receive the post requests, this tutorial extends an existing server created using the spring boot framework. if you want to know how the spring server is configured, check out the “generate signed wallet card data” section in the implementing "add to wallet" in an android application tutorial. this cdata generation server is used as the base server application for this tutorial, so the dependencies are the same as well. now you can start implementing the tutorial. create a controller class to intercept the post request samsung wallet always sends the send card state post notification to the fixed api path url: {partner server url}/cards/{cardid}/{refid}. create a new controller class in your spring server to intercept any post request that is sent to this api path. @restcontroller @requestmapping("/cards") class cardstatecontroller { @postmapping(path = ["/{cardid}/{refid}"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string): httpstatuscode { // implement your logic here to process the card state. println("received card state notification for card id $cardid and reference id $refid.") return httpstatus.ok } } run the server and then add or delete a card from your samsung wallet. if the partner server url was set correctly in section “configure the wallet card template for the send card state api,” your server should receive a post request from the samsung server and print the following message to the console: “received card state notification.” update the controller class to receive the query parameters handle the query parameters from the request by adding the following parameters as the function’s parameters: @requestparam("cc2") cc2: string, @requestparam("event") event: string receive and print the request body using the @requestbody body: string parameter. the function should now look like this: @postmapping(path = ["/{cardid}/{refid}"], params = ["cc2", "event"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string, @requestparam("cc2") cc2: string, @requestparam("event") event: string, @requestbody body: string): httpstatuscode { // implement your logic here to process the card state. println("country code: $cc2") println("wallet card state event: $event") println("request body: $body") return httpstatus.ok } now whenever the samsung server sends a request to the server, it prints the device’s country code and the wallet card’s state event on the device. verify the post request this is the final and the most important step of this tutorial. before accepting any incoming post request, you should always validate the request by following the api specification mentioned earlier in the tutorial. the security procedures can include but are not limited to: matching your partnerid with the received partnerid custom parameter. checking the token version with the ver custom parameter. for token version 3, match your certificateid using the certificateid custom parameter. checking the time of signing using the utc custom parameter. matching the other jws header parameters with the values mentioned in the specification. matching the path from the jws payload with the received url. verifying the jwt. this section shows how you can implement each of these one by one. first, parse the authentication token and read the header. val signedjwt : signedjwt = signedjwt.parse(authtoken) val jwsheader : jwsheader = signedjwt.header match partnerid and jws header parameters: val ownpartnerid = "4048012345678938963" // your partner id from samsung wallet partner portal val receivedpartnerid = jwsheader.customparams["partnerid"] val ctype = jwsheader.contenttype val alg = jwsheader.algorithm.name // check if the jws header parameters match the expected values if (ctype == "auth" && alg == "rs256" && receivedpartnerid == ownpartnerid ) { println("jws header parameters matched") // proceed with further verification } check the token version and match certificateid: val ver = jwsheader.customparams["ver"] val owncertificateid = "a123" // your certificate id from samsung wallet partner portal val receivedcertificateid = jwsheader.customparams["certificateid"]?: "" // if partner uses token version 3 in the jws header of the cdata, // then samsung server also returns version 3 response along with the certificate id if(ver == "3" && receivedcertificateid == owncertificateid){ println("jws header certificate id matched") // proceed with further verification } check if the token was generated recently: // check if the timestamp is within acceptable range val utc = jwsheader.customparams["utc"] as long val timedelta = system.currenttimemillis() - utc println("time delta: $timedelta") if (timedelta < 600000l) { println("utc timestamp is within last 1 minute. time delta = $timedelta ms.") // proceed with further verification } match the api path with the received api path from the payload: val receivedapivalue = signedjwt.payload.tojsonobject()["api"]?.tostring()?: "" val receivedapipath = receivedapivalue.substring(6, receivedapivalue.length - 14) val expectedpath = "/cards/$cardid/$refid?cc2=$cc2&event=$event" // match the path in the payload with the expected path if (receivedapipath == expectedpath) { println("path matched") // proceed with further verification } finally, validate the token using the samsung certificate provided to you during the onboarding process: read the samsung certificate from a file and then extract the public key. for instructions, refer to the cdata generation server sample code at implementing "add to wallet" in an android application. build an rsakey object using the extracted public key. create an rsassaverifier object with the rsakey to verify the token. verify the token using the verifier. // verify the signature of the jwt token using the public key provided by samsung wallet. val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) val rsakey = rsakey.builder(samsungpublickey as rsapublickey).build() val verifier: rsassaverifier = rsassaverifier(rsakey) if(signedjwt.verify(verifier)){ println("verification successful") // implement your logic here to process the card state notification. // for example, you can update the card status in your database or trigger a notification to the user. // in this example, we simply return a 200 ok response indicating that the notification was successfully processed. return httpstatus.ok } else { println("verification failed") // return an appropriate http status code indicating that the notification could not be verified. return httpstatus.unauthorized } now the complete implementation of the controller class to receive and verify the send card state request is complete. once a send card state request is completely verified, you can accept the request as a valid card state update and make any changes as required. for example, you can update the card status information in your own database or trigger a notification to the user. summary by completing this tutorial, you are now able to receive card state updates from the samsung wallet server using the send card state api and validate them. in a future tutorial, we will discuss how you can expand the server interaction functionality even further and how you can update samsung wallet card information on user devices through the get card data api. if you want to discuss or ask questions about this tutorial, you can share your thoughts or queries on the samsung developers forum or contact us directly for any implementation-related issues through the samsung developer support portal. if you want to keep up-to-date with the latest developments in the samsung developers ecosystem, subscribe to the samsung developers newsletter. sample code you can click on the link given below to download the complete sample code used in this tutorial. wallet card state server sample code (55 kb) dec 2024 additional resources implementing "add to wallet" in an android application send card state authorization token iso 3166 country codes
Mobassir Ahsan
Develop Samsung Wallet
docstatistics performance monitoring the samsung wallet service is monitored to get an effective measure of the wallet performance overview wallet card total number of wallet cards registered in the portal wallet card type total number of wallet card types registered in the portal wallet card template total number of templates registered in the portal recent trends provides key indicators and trend charts for the selected period provides the ability to change the period and wallet card type being reviewed item description registered registration by wallet card category impressions count when the coupon or banner is displayed on each screen page click count of click on a specific link to the number of total users who view a coupon or banner click through rate percentage of clicks against impressions in the coupon or banner [ctr % = clicks/impressions] stats of wallet cards provides detailed statistical information for the selected wallet card provides the ability to change the period, template, and wallet card type checks detailed information and charts for each indicator item description registered registration by wallet card category number of registrations by wallet card category and registrations by template number of registrations by template , registered number of registrations for the specified wallet card category/template , registration by partner number of registrations by partner active device number of device registering cards in the wallet max number of unique device ids dmid the max number means the maximum value during the statistical period - the hourly graph shows the maximum time's value - the daily graph shows the maximum date's value top 10 of all templates statistics on top 10 templates based on number of registrations or clicks & ctr add to wallet - impressions number of impressions counts for 'add to wallet' button add to wallet - clicks number of clicks for 'add to wallet' button add to wallet –click through rate ratio of clicks against impressions for 'add to wallet' button [ctr % = clicks/impressions] wallet cards - impressions number of exposures of registered content wallet cards – clicks number of clicks on registered content wallet cards – click through rate click through rate of registered content age & gender age & gender statistics for impression/click/ctr data by wallet card / wallet category registered by end user push notification – impressions number of exposures of push notification content push notification – clicks number of clicks of push notification content
tutorials mobile
blogsamsung wallet is one of the leading digital wallet services, designed for and available on millions of samsung galaxy devices. to ensure that samsung wallet partners can easily develop, test and integrate samsung wallet cards, samsung wallet has recently introduced a new testing suite called wallet studio. wallet studio allows samsung wallet partners and developers to develop, design, modify and experiment with different types of samsung wallet cards for a variety of purposes. wallet studio lets partners preview the card's final design in advance, making the samsung wallet card development process easier. in this tutorial, you will learn about wallet studio and how you can utilize this tool to design and check samsung wallet cards in real-time. about wallet studio wallet studio is the complete testing and designing suite introduced by samsung wallet. the tool is available at the following url: https://partner.walletsvc.samsung.com/addtowallettest wallet studio includes many features to streamline the development and testing process for samsung wallet cards. one of its key features is to allow samsung wallet partners to preview how these cards will appear on samsung galaxy devices once their implementation is complete. in this article, the following 2 features of wallet studio are discussed and you will learn about their use cases: playground – for exploring different types of pre-configured samsung wallet cards add to samsung wallet – for testing your own cards during development these 2 features are very similar in nature. both of them can be used to design and preview samsung wallet cards in real-time. however, their use cases are vastly different. playground presents samsung wallet partners with all possible combinations of preconfigured samsung wallet cards. it can therefore be used to check various samsung wallet card types and their designs. the feature can be utilized to review design options for different samsung wallet cards and their functionalities before you decide to develop a specific card type. add to samsung wallet is meant for testing your own samsung wallet cards. once you have reviewed the different types of samsung wallet cards using playground and decided on a specific type of card to implement, you can then use the add to samsung wallet feature. to use this feature, you need to create your own samsung wallet card templates using the wallet partners portal. since this feature allows you to directly configure, test, preview and add your own cards using your own private keys and certificate id, it is best used during the actual implementation of your card. prerequisites to use wallet studio, you need to first complete the samsung wallet onboarding process. once you have completed the onboarding, you can use the samsung wallet playground to check different types of samsung wallet cards. to use add to samsung wallet, you additionally need to do the following: create your own private key & csr upload the csr in the samsung wallet partners portal create at least 1 card template in the samsung wallet partners portal additionally, a supported samsung galaxy device with samsung wallet installed is necessary in order to perform add to samsung wallet operations on mobile devices. checking all card types using wallet studio playground wallet studio's playground feature provides an easy-to-use web ui for viewing all possible combinations of samsung wallet cards and their subtypes. the purpose of playground is to check the design and availability of various different samsung wallet cards. in playground, you can check all available samsung wallet cards. these cards are all pre-created for an easier experience. using playground, you can preview various wallet card types and their designs, modify their attributes, and review the changes in real-time, either through the preview pane or by adding the card to samsung wallet. to use wallet studio playground: visit wallet studio at the following url: https://partner.walletsvc.samsung.com/addtowallettest hover on learn and a pop-up menu appears. click playground to use the playground feature. figure 1: wallet studio - playground selection on this page, the card type and subtype dropdown menu is visible in the top-right corner. select a card type. its subtype dropdown menu is then populated with all the available subtypes for that card type. then select a subtype from the dropdown menu and a sample card preview appears for the selected card type. alternatively, you can scroll down to the playground section of wallet studio and click on a card type. then the playground page appears for the selected card type. figure 2: wallet studio - playground once you select a card type, you can modify the card's attributes using the text fields, and the changes appear immediately in the preview pane. after modifying the attributes to your liking, you can click the "add to samsung wallet" button, and a samsung wallet card with the same design as displayed in the preview pane is added to your wallet. this only applies if you are using wallet studio from your samsung galaxy device that has samsung wallet installed. designing your own cards using add to samsung wallet add to samsung wallet is very similar to wallet studio playground. while playground offers the ability to experiment with pre-configured samsung wallet cards, add to samsung wallet is specifically designed for reviewing and testing your own custom cards. to visit the add to samsung wallet tab of wallet studio: open wallet studio hover on my card container and a pop-up menu appears. click add to samsung wallet to use the add to samsung wallet feature. figure 3: wallet studio – add to samsung wallet selection the card templates you created previously appear in the card picker area of this page. before you choose a card, you need to upload your private key to wallet studio. to use add to samsung wallet: click the "choose file" button. upload your private key. select your certificate id. select the desired card template from the card picker. a preview of the selected card appears below the card picker. you can now design, modify, and experiment with the card, as necessary, using wallet studio. figure 4: wallet studio - add to samsung wallet you can also add the card to your device at any time using the "add to wallet" button below the card preview. designing and testing samsung wallet cards in real-time once you select a card in either add to samsung wallet or playground, a preview of the card and its configurable attributes appear. all the modifiable attributes for the card are listed in the general section of the page. as soon as you modify an attribute, the preview of the card updates immediately to reflect the changes. this way, you can modify the card attributes and use the preview to monitor the effect on the card in real-time. figure 5: changes made in wallet studio (reflected immediately in the preview) if you hover over the ? icon of an attribute, it displays the required data type and length for the attribute. figure 6: specification for each attribute (viewed by hovering over the "?" icon) if you use an invalid data type or exceed the specified data length, the tool warns you in real-time. figure 7: wallet studio informing users if a value does not meet the specification to view the json value of the card, use the dropdown menu on the top-right corner of the general section and select json. the complete json object for the card appears. if you make any modifications to the json data, the changes appear immediately in the preview section. figure 8: viewing and editing the json values directly in wallet studio to modify the barcode or qr code for the card, click the "barcode/qr" button and the barcode section appears. click any of the supported barcode or qr code formats and the changes are applied to the card. this way, you can modify the entire card, including the qr and barcodes, using wallet studio. figure 9: barcode type and values, modified using wallet studio wallet studio can be used to design and create a complete samsung wallet card which can be used as a reference during the card implementation. additionally, wallet studio can be utilized differently on desktop and mobile devices. in a desktop environment, the playground and add to samsung wallet tools can be used primarily for designing and previewing samsung wallet cards and generating the card's required json data. on mobile devices, the preview is not displayed due to the smaller screen. instead, you can directly add the card to your device's samsung wallet using the "add to samsung wallet" button to see how it looks. figure 10: wallet studio flow on mobile devices conclusion in this blog article you learned how you can make use of wallet studio to design and test samsung wallet cards on samsung galaxy devices. with this knowledge, feel free to proceed to the next steps of implementing samsung wallet cards. for additional reference you can check out the following resources: visit the samsung wallet documentation. check previous blogs on samsung wallet to learn about various features of samsung wallet. learn how you can generate cdata in real-time . learn how to handle samsung wallet card updates. for additional queries and support, feel free to reach out to us through the samsung developer forum.
Mobassir Ahsan
tutorials mobile
blogsamsung wallet is introducing a new feature called "generic card" for partners who cannot use other card types to fulfill their business requirements. this provides flexibility to modify various field labels for the card, according to the partners’ business needs. other cards, such as boarding passes and coupons serve a specific purpose, and their field labels cannot be modified. however, with a generic card, the label can be modified so it can be used for multiple purposes. in this article, you learn how to modify a generic card to use it as an insurance card. we will explain the details specification with example of the generic card. at the end of the article a guide will be provided to implement this card for your reference, to help you modify your generic card according to your needs. card setup before you begin creating a new card template, log in to the samsung wallet partner site and create a generic card. log in to the samsung wallet partner site. go to the wallet cards and then create wallet card. for more details about creating a card, check the manage wallet cards documentation. select generic card from the available card templates. modify the card information. when you have finished editing card information, launch the card to complete card setup. for more information on how to launch the card, see launch wallet cards. template editor use the template editor to modify the card template. from the "cardart" view, you can modify the card color, set a background image or change the logo image properties. from the "enlarge" view, you can modify the {{text1}} and {{text2}} labels. however, only the label itself can be changed in the template editor. to set the label value, you need to update the json file. from the "detail" view, you can modify the "textgroup" and "applink" properties. modify the text label according to your needs. it is also possible to add new text fields, with a maximum of 12 text fields allowed. after every modification, click save. finally, apply all changes by clicking apply. if you want to preview your changes, just click preview. add to samsung wallet now that the card has been created in the site, it is ready to be distributed to fulfill your business needs. implement the "add to samsung wallet" functionality to the platform where you are planning to distribute the cards. when users click "add to samsung wallet," the card is added to the wallet application on the user’s galaxy device. this functionality can be added through the application/mobile web, mms, or email. additionally, you can use a qr code on a computer web browser and kiosk. samsung provides a codelab guide for developers so that they can easily understand the implementation. for additional information on the codelab guide, read utilize the add to samsung wallet service for digital cards. further details can also be found in the implementing atw 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
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 samsung dev support the image below shows the process of managing wallet cards for more information, refer to manage wallet cards set up your environment 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, explore samsung wallet
tutorials
blogsamsung wallet provides an e-wallet service to its customers through wallet cards, as well as offering features designed to enhance user engagement and drive business growth for partners. sending push notifications to users is such a feature. partners can send push notifications to users' wallet cards directly, using pre-approved message templates. these notifications can be used to send promotional messages or alert users about important updates. this article demonstrates a complete implementation of the send notification api. in the example scenario, we send a notification to a user's wallet card from a partner's server using this api. system requirements the notification api has the following prerequisites: complete the onboarding procedure to obtain the required security certificates if you are new to samsung wallet. now create your wallet card. follow the step 1 - create wallet card template section of the documentation. create your notification template and request for approval. follow the notification workflow overview to complete this step. remember to check the template to detect prohibited content. no additional approval is required if it passes. get permission from samsung to use the send notification api. reach out to samsung developer support for further support. api fundamentals as an authorized partner, you can send notifications to the users linked to your card, using the send notification api from your server. endpoint: the endpoint below processes the notification requests. url https://tsapi-card.walletsvc.samsung.com/{cc2}/wltex/cards/{cardid}/notifications/{templateid}/send headers: header information is required to ensure secure communication between the samsung server and the partner server. authorization: bearer token for authentication. refer to json web token documentation for specifications. x-smcs-partner-id: unique partner identifier required for api access. x-request-id: a unique uuid string that identifies each request. body: a payload including a parameter named ndata possessing a jwt token that contains the relevant data to identify the card user. see the official documentation for detailed api specifications. api implementation process the send notification api allows you to send personalized push notifications to users. download the sample source code and follow the step-by-step process below for a better understanding of the implementation of the api. step 1: managing cryptographic keys cryptographic keys are needed for authorization purposes. in this step, use the certificate you obtained during the onboarding process to extract the necessary keys. these keys are needed for jwt token generation. extracting the public keys extract the public keys from the partner.crt and samsung.crt certificate files. def getpublickey(crt_path): try: with open(crt_path, "rb") as f: crt_data = f.read() certificate = x509.load_pem_x509_certificate(crt_data, default_backend()) public_key = certificate.public_key() public_key_pem = public_key.public_bytes( encoding=serialization.encoding.pem, format=serialization.publicformat.subjectpublickeyinfo ) return public_key_pem except exception as error: print(f"error reading public key from {crt_path}: {error}") return none extracting the private key extract the private key from the .pem file generated during the onboarding process. def getprivatekey(pem_path): try: with open(pem_path, "rb") as data: private_key = serialization.load_pem_private_key( data.read(), password=none, backend=default_backend() ) return private_key except exception as error: print(f"error reading private key from {pem_path}: {error}") return none step 2: constructing the authorization token an authorization token is needed to validate the api request. construct an authorization header with auth as the payload content type and include the certificate and partner ids. retrieve these ids from my account > encryption management in the wallet partner portal, then build the payload and construct the authorization token. the following code snippet implements the actions described. def generateauthtoken(partnerid, certificateid, utctimestamp, privatekey, cardid, cc2, templateid): auth_header = { "cty": "auth", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, "alg": "rs256" } auth_payload = { "api": { "method": "post", "path": f"/wltex/cards/{cardid}/notifications/{templateid}/send" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token step 3: constructing the notification data token the request payload requires the ndata parameter, which is a jwt token that contains information about the notification data and the cards’ identifiers. follow these steps to construct the ndata token. defining the notification object the notification object is a json structured data object containing a list of reference ids and the data. the reference ids identify the specific cards to send the push notification to. you can use a list of reference ids to send the push notification to multiple recipients at a time. the data contains the name-value pairs used in the notification template. in our sample notification template, we used two name-value pairs (name and insert_end_date). notifcationobject = { "refids": [ "4afb049c-efef-43ca-8f03-1df55243477c" ], "data": { "name": "premium", "insert_end_date": "12/12/2026" } } constructing the notification data jwt token next, construct the jwt token for notification data (ndata). you can get more information about the jwt format in the "card data token" section of this documentation. def generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data): jwe_header = { "alg": "rsa1_5", "enc": "a128gcm" } jwe_token = jwe.encrypt( data, samsungpublickey, encryption=jwe_header["enc"], algorithm=jwe_header["alg"] ) print(f"jwe_token: \n{jwe_token}\n") jws_header = { "alg": "rs256", "cty": "notification", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, } jws_token = jws.sign( jwe_token, key=partnerprivatekey, algorithm='rs256', headers=jws_header ) print(f"jws_token: \n{jws_token}\n") return jws_token step 4: building and executing the post request construct the http post request to send the push notification using the following code structure. # --- prepare json body (python dictionary) --- payload = { "ndata": ndata } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "content-type": "application/json" } # --- execute http request --- try: response = requests.post(endpoint, json=payload, headers=headers) response.raise_for_status() print("wallet card template notificatiom: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to notify the wallet card user:") print(f"error: {e}") if response: print("response body:", response.text) running the sample application once the four steps described above are implemented, open the sample project and do the following: update the partner_id, certificate_id, card_id, and template_id values in src/main.py with your actual values. place your partner.crt, samsung.crt and private_key.pem files in the /cert directory. install all dependent libraries listed in the requirements.txt file. run the main script in the terminal. after the script is executed successfully, a push notification is sent to the user's wallet. conclusion now that you have implemented the send notification api sample application successfully, you can implement this api with your server to send customized push notifications. additional resources for more information on this topic, consult the following resources: complete source code official samsung wallet api documentation
M. A. Hasan Molla
tutorials
blogin a previous blog article, we learned about samsung wallet’s server notification api and how to use this api to receive server notifications about samsung wallet card updates in a user’s samsung galaxy devices. this time, we look at the partner server api called “get card data” and how partners can use this api in order to add, update, or cancel issued wallet cards in user’s devices. prerequisites the prerequisites needed for this article are similar to those for our previous article about samsung wallet server apis. namely, we require a partner server where we can set up the get card data api endpoint. in order to set up and test this api, you need to: complete the samsung wallet onboarding process. create a samsung wallet card template. launch the wallet card template and have it in either the verifying or active status so that the card can be added to a user’s device. have an existing server to set up the get card data api endpoint. you can use codesandbox or a similar online hosting service for testing. configure your firewall (if you use any) to accept incoming connections from the samsung wallet server (34.200.172.231 and 13.209.93.60). when you have completed all the prerequisites, proceed to the next step to configure your wallet card template to send requests to your server. setting up the get card data api in the samsung wallet partners portal, open the desired wallet card template and then edit it to set the following “get” field: go to the wallet partners portal. from the wallet cards dropdown, select “manage wallet card.” click the name of the wallet card you want to edit. click “edit” and then scroll down to the “partner get card data” section to modify the partner server url. click “save” to set the server url for the card. get card data api specification for a complete description of the get card data api specification, please check the samsung wallet documentation. method: the get card data api uses a get method to fetch card information from the server. api path: the api path for the request is fixed and uses the “partner get card data” server url that you configured in the previous section. the samsung wallet server sends the get request to this exact url whenever it needs to fetch card data from the partner server. the format for the api path url for the complete get card data request is: {partner server url}/cards/{cardid}/{refid} if the samsung wallet server needs to fetch specific fields from the card data instead of the entire card, then it uses the additional query parameter named “fields” at the end of the url: {partner server url}/cards/{cardid}/{refid}?fields={fields} request header: the samsung wallet server includes 2 fields in the header when calling the get card data endpoint: authorization and x-request-id. an authorization bearer token is provided in the authorization field, so that the partner can verify the request before providing the data. request payload: the request does not contain any payload. expected response payload: the response to the get card data request must contain the card data in one of the following two formats: plain card data in the raw json format. encrypted card data in the cdata format. when the fields query parameter is used in the request url, the card data returned in the response can provide only the fields included in the request. however, it is acceptable to return the entire card data in the response as well. implementing the get card data api we will extend the spring server from the previous article to create the get card data api endpoint. in the api, we need to do 2 things: verify the incoming request to check that it is authentic and actually coming from the samsung wallet server. send the requested card’s data back as the response. the verification part is similar to the verification steps performed in the previous article. the request header contains the authorization bearer token, which we can use to verify the request. after verification, it is necessary to send back valid card data in the response to this get request. we can return either the plain card data or encrypt and tokenize it into cdata. in this implementation, we return the plain card data in the json format. in this example, we use a raw json file from a plaintext file called ticket_ref-001.json for simplicity. the complete get card data api implementation will therefore be as follows: @restcontroller @requestmapping("/cards") class carddatacontroller { // data transmit link @getmapping(path = ["/{cardid}/{refid}"]) fun providecarddata(@pathvariable cardid: string, @pathvariable refid: string, @requestparam("fields", defaultvalue = "") fields: string, @requestheader("authorization") authtoken: string, @requestheader("x-request-id") requestid: string,): string { if(verifyauthtoken(authtoken)){ return jwtgen.getplaincarddata() } else{ return httpstatus.unauthorized.tostring() } } } next, define the getplaincarddata() function, where the cdata is generated using the data provided in the ticket_ref-001.json file. fun getplaincarddata():string{ val data:string = getstringfromfile("sample/payload/ticket_ref-001.json") return data } warningalways verify the authenticity of the get card data request before returning the data in response. the authenticity of the request can be verified using the authorization token provided in the request header. adding cards to samsung wallet using data fetch link once you have configured the get card data api for your server, you can use the api to add cards to the user’s device directly. this is called the data fetch link and unlike the standard approach, it is not necessary to send the card information in the cdata format. instead, you can simply provide the user with the url and they can then add the card to their device by clicking the url. the url format for adding card data is as follows: https://a.swallet.link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} so, for example, if your certificateid is a123, cardid is 3h844abcdefg00, and refid is ref-001, then the slim api url for the add to wallet operation is: https://a.swallet.link/atw/v3/a123/3h844abcdefg00#clip?pdata=ref-001 to add the card to their wallet using this method, the user needs to simply visit this url from their device. once the user clicks the link, the samsung wallet server requests the card data from the previously configured get card data api and adds the wallet card to the device. notethe only information required to add a card to the device is the pdata (also known as refid). ensure that this value is a unique hash identifier so that it cannot be easily compromised by third parties figure 1: adding a card to the wallet using data fetch link updating card data using an update notification samsung wallet allows partners to update any issued card’s data using the previously configured get card data api. the card data can be updated in one of the following two ways: the card data is refreshed automatically every time the user opens the card in the detail view. the card data update is triggered manually when the partner sends an update notification. in this case, the card data is updated even when samsung wallet is running in the background, and it is not necessary to open the card in the detail view. when an update notification is sent, the state of the card is immediately updated on the device. afterwards, when the user opens samsung wallet in their device, the card data attributes are refreshed by calling the get card data api. this ensures that the wallet card data is always updated right before the user views it. in order to update card data manually and notify the user about the change, we need to configure the changes in the card data and then send an update notification to the samsung wallet server. once the update notification api is called following the specification, the card’s status and data are updated on the user’s device automatically. samsung wallet uses the refid as the unique identifier of samsung wallet cards. therefore, the refid of the specific card must be included in the payload of the update notification request in order to update the card. the complete specification for the update notification api can be found in the documentation: method: post api path: the request needs to be sent at:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/updates for the samsung wallet server domain url, we can either use the public domain (https://tsapi-card.walletsvc.samsung.com) or the private domain we received in our api callback. request header: the header must contain the authorization, x-smcs-partner-id, and x-request-id request header fields. the samsung wallet server uses this header information to verify the authenticity of the request. additionally, the header also needs to specify the content-type header, which must be set to application/json. request payload: the payload of the update notification must contain the card type, refid, and the new state of the card. optionally, the payload can also contain the fields to be updated so that only those specific fields are retrieved and updated. the payload must be in the following json format: { "card": { "type": "{card type}", "data": [ { "refid": "{ref id}", "state": "{update/deleted/expired}", "fields": "{fields, comma-separated, optional}" } ] } } steps for using the update notification: configure the authorization token. prepare the card data in your server for updating. prepare the header and payload with the refid of the selected card for updating. send the post request to the samsung wallet server for updating. once you send the update notification post request following the specification, the samsung wallet server updates the card on the user’s device. let us modify the data of the previously added card from our server and then call the update notification api. configuring the authorization token all samsung wallet server apis require the use of a bearer authorization token in order to ensure the security and authenticity of the request. you can find the complete specification of the authorization token required by samsung wallet in the documentation the authorization token generation process is very similar to generating cdata, except that for cdata, the payload needs to be encrypted first. for the authorization token, the payload is in plaintext and only contains the api path for verification. to create the bearer authorization token: configure the json payload that describes the method and api path of the request. configure a custom jws header following the jwt format specification. create a jws object using the payload and custom jws header. sign and validate the complete jws object with your partner private and public keys using the rs256 asymmetric algorithm. the complete function to generate the authorization token is given below: fun generateauthorizationtoken(): string{ val payload:string = getstringfromfile("sample/payload/api_path.json") .replace("{refid}", refid) .replace("{method}","get") .replace("{path}","/wltex/cards/cardid/updates/") val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("auth") .customparam("partnerid", partner_id) .customparam("certificateid", "a123") .customparam("ver", "3") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } preparing card data for update once the update notification is sent, the samsung wallet server queries the get card data api endpoint for the updated card data and then updates the wallet card with the latest data provided by the api. so before calling the update notification, make sure the card data provided by the api is up-to-date. for our example, let us change the value of the seatnumber field from a-07 to e-05 before calling the update notification api. prepare the request header and payload for the update notification the post request header contains the following fields: authorization, x-smcs-partner-id, and x-request-id. for our example, we set our partner id as the x-smcs-partner-id, a randomly generated code as x-request-id, and generate a bearer token following the authorization token generation process mentioned previously and use it as the authorization field value. next, we set the json payload, according to the previously mentioned format: { "card": { "type": "ticket", "data": [ { "refid": "ref-001", "state": "updated" } ] } } since the fields field is optional, we have omitted it in this example. sending the update notification to the samsung wallet server once everything is ready, we send the update notification post request to the samsung wallet server. we can use any method to send the request, such as postman, curl, or a plain http request. make sure that the update notification is sent immediately after generating the authorization token, as the token only has a ttl (time to live) of 30 seconds. once the update notification is sent, the user should immediately receive a “card information updated” push notification informing them of the card update. afterwards, the next time the user opens the samsung wallet application, the card details are up-to-date and the user can see their new seat number in their card. figure 2: updating card data using an update notification cancelling an event using a cancel notification there are times when you might need to cancel an event and recall all the issued wallet cards for it. in such case, samsung wallet makes it possible to cancel all issued cards with a specific eventid and send a notification regarding the cancelation to all users with the cards associated with the event. therefore, it is no longer necessary to modify issued cards one-by-one using their refid. instead the card issuer can cancel all cards under the event at one time. the process of sending a cancel notification is the same as the update notification process, except for the following differences: the payload needs to contain the eventid instead of the refid the state must always be canceled the post request endpoint url is:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/cancels you can find the complete specification for the cancel notification api in the samsung wallet documentation. now let us send a cancel notification following the same process as update notification: configure the authorization token. prepare the payload with the eventid for cancellation. send the post request to the samsung wallet server for cancellation. for our example, we add a few cards with the same event id to our wallet in different devices, then send a cancel notification following the specification. once the cancel notification is sent, all samsung wallet cards with the given eventid are deleted automatically from all devices and the affected users receive a "ticket canceled" push notification. figure 3: canceling an event using a cancel notification conclusion in this article, we have learned how to configure our server to use the get card data api, as well as how to use various samsung wallet server apis to add, update, delete, and cancel samsung wallet cards from user devices. if you have any further queries regarding this process, feel free to reach out to us through the samsung developers forum.
Mobassir Ahsan
Develop Samsung Wallet
docaction data this section describes action data, which defines actions that can be associated with a wallet card during the add to wallet process action data enables a card to expose predefined actions that can be triggered from samsung wallet, allowing partners to define how users interact with the card beyond static presentation overview action data represents a structured definition of actions associated with a wallet card these actions are defined at card issuance time and become part of the card data registered in samsung wallet from the add to wallet perspective, action data is optional is defined and delivered during the add to wallet process applies uniformly to all cards that require actionable behavior applicability and api usage action data may be used across various card services to support different interaction scenarios typical usage includes launching application-specific behavior triggering partner-defined actions supporting extended interaction flows initiated from the wallet api role get card data partner api return procedural data during issuance or refresh request action partner api primary carrier of action data send card event partner api used by partners to report final lifecycle outcomes and terminal events of wallet card instancesformerly referred to as send card state update notification samsung api notify state transitions caused by completed actions the presence of action data does not impose any requirement on how the action is executed at runtime conceptual model action as a mediated process an action represents a single logical step within a larger workflow responsibilities samsung wallet server o initiates or forwards actions o maintains transaction continuity o does not own business logic or credentials partner server o interprets actiontype o executes domain-specific logic o returns next-step instructions or execution results idempotency is evaluated within the scope of a card program partner context , primarily based on the card instance identifier refid and the requested actiontype detailed idempotency and deduplication rules are defined in section idempotency and request deduplication idempotency and request deduplication idempotency identifier all apis defined in this specification use refid as the primary identifier of a card instance at minimum, the wallet backend must guarantee idempotent handling of requests scoped by refid actiontype this ensures that repeated requests caused by network retries do not result in duplicated side effects idempotency scope claification the refid value is guaranteed to be unique within a given card program partner context , but is not guaranteed to be globally unique across different partners or programs accordingly, samsung wallet evaluates idempotency within the card template scope internally, the effective idempotency key may be composed of cardid, refid, actiontype, actioninstanceid partners are required to ensure uniqueness of refid within their own card template, but are not required to generate globally unique refid values across templates recommended idempotency extension to safely distinguish retries from logically new attempts, the following enhancement is recommended each action data request should include a unique request-level identifier e g actioninstanceid idempotency should be evaluated using the composite key refid, actiontype, actioninstanceid if actioninstanceid is not present, the server must fall back to refid, actiontype and must not reject the request solely due to the absence of actioninstanceid concurrent action handling for a given refid, the server must define and enforce valid state transitions if an action is received that is not valid for the current state the server must reject the request with http 409 state_conflict the response must include an appropriate error code describing the conflict common action envelope all actions are defined using a common envelope format the envelope includes action identifier action type action-specific payload this structure allows samsung wallet to interpret and route actions in a consistent manner [common action envelope structure] field description actiontypestring ≤ 32 required identifier of the requested action actionpayloadobject required container for action-specific data actionpayload actiondetailsobject required contextual metadata for the action see actiondetails object actionpayload actiondetails actioninstanceidstring optional unique request-level identifier for idempotency and deduplication see idempotency and request deduplication actionpayload {fields}object optional action-specific payload fields whose semantics are determined solely by actiontype normative rules when actiontype is present, actionpayload must be present the semantic meaning of actionpayload {fields} is determined solely by actiontype unknown fields must be ignored, unless explicitly agreed by both parties actiondetails object the actiondetails object contains action-specific data required to perform the defined action the structure and contents of actiondetails depend on the action type and the intended use case the actiondetails object provides contextual metadata for an action field description timestampstring optional unix epoch milliseconds eventstring optional logical event register, update, reissue, etc reasonstring optional reason for triggering the action levelstring optional info, warn, error sourcestring optional wallet_app, wallet_server, partner_server codestring optional result or error code messagestring optional human-readable message action usage pattern action data may be applied to different usage patterns depending on the card service these patterns define how action data is interpreted and used after the card is added to samsung wallet general action usage in general usage scenarios, action data is used to define actions that can be initiated by the user from the wallet interface these actions are handled according to the action type and associated payload access-related action usage optional in some card services, action data may be used to support access-related interactions in such cases action data may include access-related information the action definition may serve as an entry point for access-related processing the inclusion of access-related action data during add to wallet does not, by itself, enable or activate access functionality detailed access-specific behavior is described in the separate access guide
tutorials mobile
blogdigital identity verification has become a rising topic in the current technological landscape. samsung wallet allows samsung galaxy device users to securely register their state-issued us driver's license in their device, letting them use it as a mobile driver's license (mdl). through the "verify with wallet" (vww) functionality, samsung wallet provides android developers with the ability to authenticate a user's identity directly from their application by utilizing the user's registered mdl on the device. the implementation of the functionality is based on and is fully compliant with the iso 18013-5 standard. in this article, we explore the complete process of implementing verify with wallet in an android application. prerequisites in order to complete the tasks in this article and implement a complete sample application for verifying a user's identity, you need the following: valid us driver's license or state id us region samsung galaxy device with mdl support complete the samsung wallet partner onboarding process understanding the verify with wallet process samsung wallet offers a native relying party (rp) sdk for android applications. rp sdk is an app2app sdk designed for enabling samsung wallet's mdl service in online use cases. by integrating this sdk, you can leverage the vww functionality within their applications. in your application, you need to create a json object for defining the request and a json payload for the relying party card. then, you can utilize the rp sdk to create a valid mdoc request using the provided information. finally, the request needs to be sent to the samsung wallet application. in response, samsung wallet sends an encrypted response back to the application, which contains the requested information in a cbor encoded format. the application can then decode the provided data and use it as necessary. refer to the iso 18013-5 standard, aamva mdl guidelines and the samsung wallet documentation for a better understanding of the vww process. implementing the verify with wallet functionality in your android application the process of implementing vww in an android application includes creating a relying party card for samsung wallet, downloading and integrating the rp sdk into the android application and implementing the necessary functions in the android application for completing the verification process. creating a relying party wallet card template in the samsung wallet partners portal in order to implement and use the vww functionality, you need a wallet card of the relying party type for this purpose. to create a relying party wallet card template: go to the samsung wallet partners portal. select wallet card > create wallet cards. from wallet card templates, select relying party. select the applicable service location and authentication issuer from the advanced setting section. make sure to select the proper values for the card, otherwise the verification process may not work. figure 1: creating a relying party card for vww integrating the rp sdk in an android application once the relying party card template has been created, we can download and integrate the rp sdk to work with the android application. step 1: download the rp sdk for android to download the rp sdk: download the zip file containing the latest rp sdk release aar file from samsung wallet code resources on the samsung developer website. extract the aar file from the downloaded zip file. copy and paste the downloaded rp-sdk-x.xx-release.aar file inside a new directory in the android studio project (for example, \libs\). step 2: add android manifest permissions to implement the verify with wallet functionality, the application needs both the internet access permission and the ability to query the installed samsung wallet application. to provide the application with these permissions, open the androidmanifest.xml file in the android studio project and add the following lines: <uses-permission android:name="android.permission.internet" /> <queries> <package android:name="com.samsung.android.spay" /> </queries> step 3: add gradle dependencies in the application's build.gradle file, load the rp sdk aar file and the necessary additional dependencies for using the sdk, as follows: // load rp sdk aar file implementation(files("libs/rp-sdk-1.05-release.aar")) //cbor decoding dependencies implementation("com.upokecenter:cbor:4.0.1") implementation("com.augustcellars.cose:cose-java:1.1.0") // other dependencies implementation("com.google.code.gson:gson:2.11.0") implementation("org.bouncycastle:bcprov-jdk15to18:1.66") implementation("com.nimbusds:nimbus-jose-jwt:9.37.3") 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") after these steps, the rp sdk is ready for use in your android application. configuring the android application for verify with wallet next, we need to complete the implementation of the verify with wallet functionality in your android application. step 1: build a card payload for the relying party card first, we need to create a request payload for the relying party card following the specification. private fun buildapp2apppayload(): string { return payload .replace("{refid}", uuid.randomuuid().tostring()) .replace("{createdat}", system.currenttimemillis().tostring()) .replace("{updatedat}", system.currenttimemillis().tostring()) } private val payload = """ { "card": { "type": "relyingparty", "data": [ { "createdat": {createdat}, "updatedat": {updatedat}, "language": "en", "refid": "{refid}", "attributes": { "clientpackagename": "com.ahsan.verifyappsample", "clienttype": "app", "fontcolor": "#ffffff", "logoimage": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "logoimage.darkurl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "logoimage.lighturl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "providername": "samsung verification sample" } } ] } } """.trimindent() step 2: build the applink the applink is a tokenized url that is similar to the cdata tokens used for samsung wallet cards. the samsung wallet rp sdk includes a function to generate the applink using the payload and the partner credentials (private key, public key, partner id, card id, certificate id, etc.). to build the applink, you can simply call the rpclientapis.buildapplink() function with the required parameters: val rpclientapis = rpclientapis(this) val applink = rpclientapis.buildapplink( partnerid = partner_id, cardid = card_id, payload = buildapp2apppayload(), samsungpublickey = samsung_certificate, partnerpublickey = partner_certificate, partnerprivatekey = partner_private_key, partnercertificateid = certificate_id, isstagingserver = true ) step 3: build the request data finally, once the applink creation is complete, we can send the verification request using the rp sdk. before sending the request, we need to specify exactly which information we wish to retrieve. for this purpose, we need to create a json document following the iso 18013-5 specification and specify the fields we wish to retrieve in the response. it is possible to request for the following fields in the request data under the "org.iso.18013.5.1" namespace: portrait family_name given_name document_number age_in_years resident_address birth_date issue_date expiry_date sex height weight_range weight eye_colour hair_colour organ_donor driving_privileges veteran additionally, it is also possible to request for the following 3 fields, under the "org.iso.18013.5.1.aamva" namespace: domestic_driving_privileges dhs_compliance edl_credential in our example, we only try to retrieve the following 4 fields: family_name, age_in_years, issue_date, and expiry_date. in the following code example, we build the request string accordingly: val requestdata = """ { "doctype": "org.iso.18013.5.1.mdl", "namespaces": { "org.iso.18013.5.1": { "family_name": true, "age_in_years": true, "issue_date": true, "expiry_date": true } } } """.trimindent() step 4: create the onresponselistener class when using the vww rp sdk, it is necessary to create a listener class for both sending the request and for receiving and processing the response from the mdoc server. for our example, let's create an empty placeholder onresponselistener class which extends the rp sdk's onresponselistener class. class onresponselistener(private val requestdata: string) : rpclientapis.onresponselistener{ override fun ongetmdocrequestdata(deviceengagementbytes: bytearray): bytearray? { todo("not yet implemented") } override fun onmdocresponse(encryptedresponsebytes: bytearray) { todo("not yet implemented") } override fun onmdocresponsefailed(exception: exception) { log.e(tag, "response processing failed", exception) } } initiating the verification request to initiate the identity verification process, we need to establish a secure session and send a structured request to the samsung wallet application. we can use the previously created onresponselistener class for this purpose. step 1: define the ongetmdocrequestdata() function for sending the request data inside the ongetmdocrequestdata() function, we need to do 2 things for establishing a secure encrypted session: generate an elliptic curve key pair build session establishment bytes following the iso-18013-5 specification. once the key pair is generated, we can use this key pair, the device engagement bytes, and the previously created request data for building the encrypted session establishment bytes. the device engagement bytes are provided automatically inside the ongetmdocrequestdata() function by the rp client sdk. private val securerepository = securerepository() override fun ongetmdocrequestdata(deviceengagementbytes: bytearray): bytearray? { val keypair = securerepository.generateeckeypair() val encryptedsessionestablishmentbytes = securerepository.buildsessionestablishment(requestdata, deviceengagementbytes, keypair) return encryptedsessionestablishmentbytes!! } for further information regarding generating the key pair and building the session establishment bytes, check the provided sample code. step 2: initiate a verification request with the applink once the ongetmdocrequestdata() function is ready, we can use the request() function to initiate the verification request. val sessionid = uuid.randomuuid().tostring() val wallet_package = "com.samsung.android.spay" rpclientapis.request( wallet_package, sessionid, applink, onresponselistener(requestdata) ) processing the request response once the mdoc request has been sent and processed successfully, the application should receive a bytearray as response in the onmdocresponse() function inside the listener class. this bytearray is an encrypted json object. once decrypted, the response should look like the following: { "documents": [ { "issuersigned": { "namespaces": { "org.iso.18013.5.1": [ "pghkawdlc3rjrbku-mzyyw5kb21uagnkngduzdl5z2i1ctrjadv4znpxzwxlbwvudelkzw50awzpzxjrzxhwaxj5x2rhdgvszwxlbwvudfzhbhvlwhqymdmxltexltixvda3ojawojawwg", "pghkawdlc3rjrbknbwzyyw5kb21udjg1nmsydzizzzq3ohk5ctq0ahjxzwxlbwvudelkzw50awzpzxjsywdlx2lux3llyxjzbgvszw1lbnrwywx1zrgr", "pghkawdlc3rjrblvwwzyyw5kb21ubnrtdnj5oxlucxcyzjy2bmp2nxrxzwxlbwvudelkzw50awzpzxjqaxnzdwvfzgf0zwxlbgvtzw50vmfsdwxaddiwmjmtmtetmdhumdc6mda6mdba", "pghkawdlc3rjrbnxqwzyyw5kb21uoxjqd2nydjz6cxpqzm1xajnkcnhxzwxlbwvudelkzw50awzpzxjrzmftawx5x25hbwvszwxlbwvudfzhbhvlzufoc2fu" ] }, "issuerauth": [ "dcba", { "33": "..." }, "...", "..." ] }, "devicesigned": {…}, "doctype": "org.iso.18013.5.1.mdl" } ], "version": "1.0", "status": 0 } the values inside the org.iso.18013.5.1 json array are the information we requested, in the cbor (concise binary object representation) format. for example, if we decode the value: "pghkawdlc3rjrblvwwzyyw5kb21ubnrtdnj5oxlucxcyzjy2bmp2nxrxzwxlbwvudelkzw50awzpzxjqaxnzdwvfzgf0zwxlbgvtzw50vmfsdwxaddiwmjmtmtetmdhumdc6mda6mdba", we find that this cbor object contains the issue_date field and its value is 2023-11-08t07:00:00.000z. similarly, every value provided in the array is a cbor object that can be decoded using cbor decoders to find a key-value pair containing the requested information. we can now receive the mdoc response in the onmdocresponse() function and decode it to retrieve the final requested values: override fun onmdocresponse(encryptedresponsebytes: bytearray) { val plainresponse = securerepository.decryptmdocresponse(encryptedresponsebytes) log.i(tag, "plainresponse=${plainresponse?.toprettyjson()}") val mdoccontent = mdoc18013utils.parsemdocresponse(plainresponse!!) mdoccontent.foreach { (key, value) -> log.i(tag, "$key: $value") } } here, securerepository.decryptmdocresponse() performs the decryption operation and converts the encrypted bytes into a plain json response. afterwards, the mdoc18013utils.parsemdocresponse() function takes the plain response and decodes each cbor-encoded element contained in the org.iso.18013.5.1 array and returns these values in a simplified dictionary of key-value pairs. if you wish to learn more about these functions, you can check out the provided sample code. with this step, the sample application's implementation of verify with wallet is complete. you can now build and run the application. in the sample application, once the user clicks the "verify with samsung wallet" button, the vww procedure is initiated. once the user confirms that they wish to share their information, the application will receive the requested information about the user. figure 2: complete the verification process using vww conclusion in this article, we have explored how you can integrate the verify with wallet rp sdk directly into your application and use it to verify the user's identity. feel free to integrate the rp sdk in your own application and test the verify with samsung wallet process as well. if you have any further queries regarding this process, feel free to reach out to us through the samsung developers forum. related resources iso/iec 18013-5:2021 - personal identification — iso-compliant driving licence — part 5: mobile driving licence (mdl) application mobile driver license - american association of motor vehicle administrators - aamva rp sdk download link verify with wallet api guidelines relying party card specifications sample code download link
Mobassir Ahsan
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.
You have successfully updated your cookie preferences.