Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials
blogwallet cards. notice this article introduces non-payment service cards. if you want to learn more about the payment service of samsung wallet, visit the samsung pay page. you can get information on online payment services such as in-app payments, web checkout, and w3c payments. add to samsung wallet service let's delve deeper into the "add to samsung wallet" feature. digitized content registered in samsung wallet comes in the form of cards called wallet cards. registering a wallet card is effortless: simply click the "add to samsung wallet" button, and the card is stored securely on users’ galaxy smartphones. "add to samsung wallet" button and wallet card notice the benefits of using wallet cards can be found in the commercial video forgetting can be awesome. wallet cards the "add to samsung wallet" service is an open platform that supports offering various types of content such as wallet cards. we are streamlining service integration with content providers across different regions and adding useful features. boarding pass event ticket loyalty gift card coupon id card generic card pay as you go (in progress) reservation (in progress) digital key (in progress) notice generic card supports unstructured forms of cards. be a samsung wallet partner partner onboarding to begin offering content through samsung wallet, you must first register as a partner on the samsung wallet partner portal. the integration process is detailed on the samsung developer portal. to join the samsung wallet partner portal, create a samsung account that is used as the service administrator. wallet card management once enrolled, you can create service cards on the wallet cards menu. each card is assigned a card id representing the service, and you can set the card type and linking information. you can manage cards according to their status – test or live. configuring wallet card notice after completing all required forms for the wallet card, click the launch button to request card activation. before providing the service to actual users, remember to turn off the 'test mode.' how to safely secure user data key generation and certificate request the registration process includes certificate exchange to securely transmit service data. refer to the diagram and developer guide, security key & certificate creation guide, to complete the certificate registration and partner enrollment smoothly. certificates exchange process ensuring data security to prevent forgery and leakage of user card data, secure tokenization processing is required. json web token (jwt), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. in particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used. process of generating and verifying security tokens notice depending on how partners provide content services to users, you can choose how to deliver data to the samsung wallet service. two ways to transfer wallet card data add to samsung wallet interface provides two methods for partners to deliver users digital content as wallet cards. data transmit link the general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the samsung wallet service when the user clicks the button. as long as samsung wallet support is confirmed, you can generate a link containing the user's card data and configure the "add to samsung wallet" button to run the link when pressed, either on an application or web page. data transmit process data fetch link another method to transfer wallet card data is to include only the refid, which represents the user's content, in the "add to samsung wallet" link and transmit it to the samsung wallet service. when a user clicks the "add to samsung wallet" button, samsung servers refer to the get card data api information set on the wallet card and retrieve user content using the received refid to complete registration. data fetch process this method is suitable for providing user's data through email or mms messages where static links cannot be avoided. there is an option to secure these static links. data fetch process for static links setting up data synchronization on the partner portal, you can set up the wallet card information and configure the server interaction api that the content provider needs to prepare. this api is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on samsung wallet. register wallet cards when a user card is added to samsung wallet, samsung wallet servers use the send card state api to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with samsung wallet. when a wallet card is registered, added event is sent to the partner's server update wallet cards changes to the synchronization target content can be notified to the samsung wallet service through the update notification api. here, the value that distinguishes each piece of content is the refid that the partner must provide when registering the users’ wallet card. through the get card data api, samsung wallet servers can check the latest content information any time. if updates occur on the partner's side, updated event notifications should be sent to the samsung server in case users withdraw content from the partner's side in case users delete cards from samsung wallet notice both servers should verify requests using the authorization header of the api request. this authorization token is in jwt format, familiar from card data security. effortless wallet card registration with just one click this feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or mms message. various service channels javascript library for web developers we provide a javascript library and a user guide, implement the button, to help integrate your web pages. creating buttons and links in your app for configuring buttons in applications, utilize the button image resources. providing services via mms, email, or qr codes to provide services through fixed links, check out the details of the data fetch link. these static links can also be used by scanning qr codes. experience the service and practice you can experience service integration development using the codelab and use the testing tool to preregister the wallet cards created on the partner portal, which could be helpful. conclusion we've looked at how to provide digital content through the "add to samsung wallet" feature. we continuously update the guides on the developer portal, so please refer to them when preparing for integration. summary the "add to samsung wallet" service welcomes participation from content service partners and developers. for inquiries or technical support, please contact us through the form provided on the developer portal. i hope this post has been helpful, and now i'll conclude my writing here. thank you. this post was written based on the sdc23 korea session.
Choi, Jonghwa
tutorials mobile
blogwallet card which you must create and launch within the samsung wallet portal. after successfully launching the card, you can create an “add to wallet” link for it. prerequisites before you can create wallet cards for samsung wallet, complete the samsung wallet partner registration and onboarding process, including encryption setup. after onboarding, you receive an email with your public key and signed security certificate. keep this information in a safe place. important your company can only obtain partnership for a single samsung account. store your private key securely, as it is needed for wallet card management. your encryption settings cannot be modified without administrator approval. creating wallet cards samsung wallet supports the following wallet card types: boarding pass event ticket coupon gift card loyalty card id card create your wallet card at the samsung wallet portal. you can create as many cards as you need. the samsung wallet portal also allows you to manage your cards and monitor their performance. testing wallet cards use the “add to wallet” test tool to test the card at any time, before or after launching it: in the samsung wallet portal, enable testing mode for the card you want to test. skip this step if you have already launched the card. on your samsung device, go to the “add to wallet” test tool and sign in with your samsung account. select the card from the list and provide test data in the appropriate fields. in the “partner’s private key” field, paste your decrypted private key. this must be the same private key that was used during onboarding. noteif your private key is encrypted, you must first decode it with the ssl command. an encrypted key starts with the following text: -----begin encrypted private key----- once decoded, the key starts with the following text: -----begin private key----- 5. tap the “add to samsung wallet” button to add the card to samsung wallet on your device. for more information about testing wallet cards, see “add to wallet” test tool. launching wallet cards when you are ready to make the wallet card accessible to users, click “launch” to start the verification process. launching a card cannot be canceled. figure 1: wallet card launched the samsung wallet administrator reviews the card and approves or rejects it. if your card is rejected, check the rejection email for the reason. modify the card to address the issue and launch it again. for more information about wallet card verification, see launch wallet cards (verifying status) and launch wallet cards (rejected status). implementing “add to wallet” links after launching your wallet card, create a link that users can click to add the content to their samsung wallet. to include the card data in tokenized form, use the following url format: https://a.swallet.link/atw/v1/{card id}#clip?cdata={cdata token} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. cdata query parameter contains the encrypted card data in jwt format. for more information, see the "cdata token generation" section below. if the encrypted card data is longer than 2048 bytes, or you do not want to include the tokenized data in the url, store and reference the card data on your server. create the url in the following format: https://a.swallet.link/atw/v1/{card id}#clip?pdata={reference id} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. pdata query parameter is the unique identifier for the card data stored on your server. for more information on “add to wallet” links, see add to wallet interface. cdata token generation the card data in basic json format must be provided as a jwt (json web token). for token generation details, see security. you can also study the cdata generation sample code. to ensure your cdata token is valid, keep the following requirements in mind: pay attention to the mandatory fields in the card object. all timestamps are utc epoch time in milliseconds. card data attributes vary based on the card type. for detailed card data specifications, see wallet cards. your private key must match the key used for the security certificate signed by samsung. if you are using the correct private key, the following commands generate the same hash: $ openssl rsa -noout -modulus -in partner.key | openssl md5 $ openssl x509 -noout -modulus -in partner.crt | openssl md5 generated jwt tokens expire in 30 seconds. the “add to wallet” link must be used within this time. otherwise, you must generate a new token and new link. next steps to integrate the “add to wallet” feature as a button in your application or website, see implement the button. you can update the information on a card that has been stored in a user’s samsung wallet by communicating between your server and the samsung server. for information, see server interaction. if you have any questions or face difficulties implementing the content in this article, you can contact samsung developer support. related resources samsung wallet documentation integrate “add to samsung wallet” button into partner services code lab
M. A. Hasan Molla
tutorials web
blogwallet 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
tutorials mobile
blogwallet cards, such as for boarding passes, tickets, coupons, gift cards and loyalty cards, for your service and issue them to users who can add them to the samsung wallet application on their device. samsung wallet cards are signed with the rs256 asymmetric algorithm. the rs256 signing algorithm requires a private key, which is a personal credential that must never be shared in the application. consequently, a separate server application is needed to store the key and sign the wallet card data (cdata). when the user taps the "add to samsung wallet" button in the application, the server application creates and signs the wallet card data, then returns a jwt token that is used to add the wallet card to the user's samsung wallet application. figure 1: "add to wallet" flow this tutorial uses kotlin to demonstrate how to implement the "add to wallet" feature in an android mobile application that adds movie tickets to samsung wallet. it also shows how to generate the wallet cards using a spring boot server. you can follow along with the tutorial by downloading the sample code files. develop the mobile application to implement the "add to wallet" button in the mobile application, you must configure the application, implement the application ui, and define the application logic for the button. configuring the mobile application project create an application project and configure it to connect to and communicate with the server through rest api requests: in android studio, create a new project. to implement rest api support in the application, add the following retrofit library dependencies to the application's "build.gradle" file: 'com.squareup.retrofit2:retrofit:2.11.0' 'com.squareup.retrofit2:converter-gson: 2.11.0' to enable communication with the server, add the following permissions to the "androidmanifest.xml" file: <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.access_wifi_state"/> to enable testing with a local non-https server, add the following attribute to the "application" element in the "androidmanifest.xml" file: android:usescleartexttraffic="true" implementing the application ui the application ui consists of two screens: the movie tickets list and a ticket detail page. in the application code, define a movie data class that contains details for the movie tickets that can be added to samsung wallet. data class movie( val name:string, val studio:string, val ticketnumber:string, ) create a recyclerview that displays the list of movie tickets as buttons on the main screen. each button has a listener that opens the detail page for the ticket. you can study the implementation details in the sample code. to check whether the device supports samsung wallet, send an http get request to the following endpoint, where build.model is the model of the device: https://api-us3.mpay.samsung.com/wallet/cmn/v2.0/device/available?servicetype=wallet&modelname=${build.model} create the ticket detail page layout in the "activity_movie_detail.xml" file. the "add to wallet" button is implemented on this page. figure 2: detail page layout implement the ticket detail page functionality in the moviedetailactivity activity class in the application code. for this demonstration, the movie ticket data is predefined in the application code. in a real application, the data is usually retrieved in real time from an external database. val movielists = listof<movie>( movie("the wallet", "samsung studios", "a-01"), movie("crying sea", "laplace studio","h-07"), movie("canoe", "terra productions", "r-03") ) val position:int = intent.getintextra("movieposition", 0) val movie:movie = movielists[position] binding.mvnametext.text = movie.name binding.mvstudiotext.text = movie.studio binding.mvticketnumber.text = "ticket: ${movie.ticketnumber}" binding.addtowalletbutton.setonclicklistener { // request server to generate card data // retrieve signed card data from server // add card to samsung wallet application } when the user taps the "add to wallet" button, onclicklistener() is triggered. its functionality is defined later in this tutorial. connecting to the server to communicate with the server: in the tokenresponse class, define the structure of the json response to be received from the server. the status field indicates whether the token generation request was successful, and the jwt field contains the generated cdata in the form of a jwt token. data class tokenresponse( val status: string, val jwt:string ) in the "apiclient.kt" file, define a retrofitclient object that is used to establish the connection with the server. define the apiinterface interface, which defines the api request and response: the api endpoint url is base_url/movie/{id}, where {id} is the movie ticket id to be added the expected response from the endpoint is a tokenresponse object. define an apiclient object that extends apiinterface and creates a retrofitclient instance to establish the server connection. object retrofitclient { private const val base_url = "http://192.xxx.xxx.xxx:8080" // define your server url val retrofit: retrofit by lazy { retrofit.builder() .baseurl(base_url) .addconverterfactory(gsonconverterfactory.create()) .build() } } interface apiinterface { @get("/movie/{id}") suspend fun getmovie(@path("id") movieid:int): response<tokenresponse> } object apiclient { val apiservice: apiinterface by lazy { retrofitclient.retrofit.create(apiinterface::class.java) } } adding card data to samsung wallet to request cdata generation from the server and add the wallet card to samsung wallet: in the addtowalletbutton.setonclicklistener() method within the moviedetailactivity class, send a request to the server to generate cdata for the selected movie ticket. if cdata generation is successful, to add the movie ticket to samsung wallet, send an http request containing the cdata token to the following endpoint url: https://a.swallet.link/atw/v1/{card id}#clip?cdata={cdata token} for more information about this endpoint, see data transmit link. binding.addtowalletbutton.setonclicklistener { coroutinescope(dispatchers.main).launch { val response = apiclient.apiservice.getmovie(position) if(response.issuccessful && response.body()!=null){ startactivity(intent( intent.action_view, uri.parse("http://a.swallet.link/atw/v1/3aabbccddee00#clip?cdata=${response.body()!!.jwt}"))) // replace '3aabbccddee00' part with your card id } } } notethe generated cdata is valid for 30 seconds, so it is recommended to generate the cdata only when the "add to samsung wallet" button is clicked. if the cdata has expired by the time the token is sent to samsung wallet, the user can receive a "request timed out" error. generate signed wallet card data the server application must be configured to receive the card data request from the mobile application and return a signed jwt token. this part of the tutorial uses the spring boot framework. configuring the server project to create and configure a server application to generate and sign wallet card data: in the spring initializr tool or any supported java ide, create a spring boot project and open the sample code. to configure the server to receive rest api requests from the mobile application, add the "spring web" dependency to the project. define a token data class. make sure it has the same attributes as the tokenresponse data class defined in the mobile application. data class token(val status:string, val jwt:string initialize a tokencontroller class that receives the incoming requests and returns a token object in response. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { return token("success", "{dummy_cdata}") // cdata generation logic } } the cdata generation and signing logic is described in the next section. implementing card data signing logic for easier understanding, this section describes a simplified implementation of the cdata generation sample code. in the server application project, copy the following credential files to the "sample/securities/" directory. samsung public key from the samsung certificate ("samsung.crt") partner public key from your partner certificate ("partner.crt") partner private key from the private key file ("partner.key") to handle the certificate files and signing algorithms, add the following dependencies to the server application's "build.gradle" file: implementation 'com.nimbusds:nimbus-jose-jwt:9.37.3' implementation 'org.bouncycastle:bcprov-jdk18on:1.77' in a new "jwtgen.kt" file, define a readcertificate() method that reads the public keys from the certificates and a readprivatekey() method that reads the private key from the key file. private val partner_id = "4048012345678912345" // replace with your partner id private val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) private val partnerpublickey = readcertificate(getstringfromfile("sample/securities/partner.crt")) private val partnerprivatekey = readprivatekey(getstringfromfile("sample/securities/partner.key")) fun readprivatekey(key: string): privatekey { val keybyte = readkeybyte(key) lateinit var privatekey: privatekey val pkcs8spec = pkcs8encodedkeyspec(keybyte) try { val kf = keyfactory.getinstance("rsa") privatekey = kf.generateprivate(pkcs8spec) } catch (e: invalidkeyspecexception) { e.printstacktrace() } catch (e: nosuchalgorithmexception) { e.printstacktrace() } return privatekey } fun readcertificate(cert: string): publickey { lateinit var certificate: certificate val keybyte = readkeybyte(cert) val `is`: inputstream = bytearrayinputstream(keybyte) try { val cf = certificatefactory.getinstance("x.509") certificate = cf.generatecertificate(`is`) } catch (e: certificateexception) { e.printstacktrace() } return certificate.publickey } private fun readkeybyte(key: string): bytearray { val keybyte: bytearray val bais = bytearrayinputstream(key.tobytearray(standardcharsets.utf_8)) val reader: reader = inputstreamreader(bais, standardcharsets.utf_8) val pemreader = pemreader(reader) var pemobject: pemobject? = null try { pemobject = pemreader.readpemobject() } catch (e: ioexception) { e.printstacktrace() } keybyte = if (pemobject == null) { base64.getdecoder().decode(key) } else { pemobject.content } return keybyte } fun getstringfromfile(path: string?): string { try { val file = file(objects.requirenonnull(classloader.getsystemclassloader().getresource(path)).file) return string(files.readallbytes(file.topath())) } catch (e: ioexception) { throw runtimeexception(e) } } generating card data cdata token generation is implemented in the "jwtgen.kt" file: read the file containing raw json data that defines the ticket data structure. for this demonstration, use the "ticket.json" file in the "sample/payload/" directory of the cdata generation sample code. generate or fill in the required ticket details. for example, the "{title}" and "{seatnumber}" fields are replaced with the movie title and seat number. for information about the complete json structure, see wallet cards. convert the json data to a jwe object. encrypt the jwe object with the samsung public key. build the custom jws header for samsung wallet cards. sign and validate the complete jws object with your partner private and public key using the rs256 asymmetric algorithm. this is the cdata token. private val currenttimemillis = system.currenttimemillis() private val plaindata:string = getstringfromfile("sample/payload/ticket.json") .replace("{refid}", uuid.randomuuid().tostring()) .replace("{language}", "en") .replace("{createdat}", currenttimemillis.tostring()) .replace("{updatedat}", currenttimemillis.tostring()) .replace("{issuedate}", currenttimemillis.tostring()) .replace("{startdate}", (currenttimemillis + timeunit.days.tomillis(1)).tostring()) .replace("{enddate}", (currenttimemillis + timeunit.days.tomillis(1) + +timeunit.hours.tomillis(2)).tostring()) fun generatecdata(moviename: string, movieticktno:string): string{ // modify data as needed val data = plaindata.replace("{title}", "\"$moviename\"") .replace("{seatnumber}","\"$movieticktno\"") //print(data) return generate(partner_id, samsungpublickey, partnerpublickey, partnerprivatekey, data) } private fun generate(partnerid: string, samsungpublickey: publickey, partnerpublickey: publickey, partnerprivatekey: privatekey, data: string): string { val jweenc = encryptionmethod.a128gcm val jwealg = jwealgorithm.rsa1_5 val jweheader = jweheader.builder(jwealg, jweenc).build() val encryptor = rsaencrypter(samsungpublickey as rsapublickey) val jwe = jweobject(jweheader, payload(data)) try { jwe.encrypt(encryptor) } catch (e: joseexception) { e.printstacktrace() } val payload = jwe.serialize() val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", "2") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } returning the signed token in the server application code, when the server receives a request at the movie/{movieid} endpoint, the tokencontroller class calls the jwtgen.generatecdata() method with the movie id, which generates and returns the cdata jwt token in the api response. in this tutorial, since the movie ticket list was predefined in the mobile application project, make sure the same movie data class and list are defined here too. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { val movielists = listof<movie>( movie("the wallet", "samsung studios", "a-01"), movie("crying sea", "laplace studio","h-07"), movie("canoe", "terra productions", "r-03") ) if( movieid>2){ // implement your verification logic return token("failure", "") } else{ val cdata = jwtgen.generatecdata(movielists[movieid].name, movielists[movieid].ticketnumber) return token("success", cdata) } } } testing the application to test your "add to wallet" integration: connect the server and the mobile device to the same network. launch the server and mobile applications. in the mobile application, tap a movie ticket in the list. its detail page opens. tap add to samsung wallet. the server generates and returns the cdata token. the samsung wallet application launches on the device and the movie ticket information is added to it. figure 3: ticket added to samsung wallet summary implementing the "add to wallet" feature enables your users to add your digital content, such as tickets, passes, and loyalty cards, to the samsung wallet application on their mobile device as wallet cards. in addition to implementing the "add to samsung wallet" button in your mobile application, you must also create a server application that securely generates and signs the wallet card data and returns it to the mobile application for transmitting to samsung wallet. for more information about adding "add to wallet" to your application, see implementing atw button. you can also study the extended sample application (clicking this link downloads the sample code) and the api reference. if you have questions about or need help with the information presented in this article, you can share your queries on the samsung developers forum. you can also contact us directly for more specialized support through the samsung developer support portal. resources click the links below to download the sample code. android app sample code extended android app sample code cdata generation server sample code
Mobassir Ahsan
tutorials mobile
blogwallet cards from the sidebar and then navigate to create wallet card. follow the instructions in the general information section to complete the form. select "loyalty card" from the wallet card template menu. select your location from the main (headquarters) location menu. if you get a "country not supported" error during a later phase, contact samsung developer support. after completing the form, save the card. all created cards are listed in the manage wallet card view. you can view, edit, and delete the card information from this view. finally, launch the card. card specification once a card is created in the wallet partners portal, the card can be implemented in the partner application so that the user can purchase and use it. to do so, implement the "add to samsung wallet" button in your application. for this purpose, generate a card data token and create a final url. this url is integrated with the "add to samsung wallet" button to add the card to samsung wallet. for generating a card data token, you need to define the wallet card data. the loyalty card follows the specification below. name description title required. the main title of the loyalty card. in the sample card, this field has the value "card title". eventid optional. the event id. use this id to find and process an action to an event to all loyalty cards with the same id. groupingid optional. identifier to group related cards. subtitle1 optional. an auxiliary field for showing supporting information about your card. logoimage optional. logo image displayed in the card item. the image size must be a maximum of 256 kb. logoimage.darkurl optional. logo image displayed in the card item in dark mode. the image size must be a maximum of 256 kb. logoimage.lighturl optional. logo image displayed in the card item in light mode. the image size must be a maximum of 256 kb. providername required. provider name for the loyalty card. startdate optional. card validity start date. the date format is an epoch timestamp in milliseconds. enddate optional. card validity end date. the date format is an epoch timestamp in milliseconds. locations optional. list of locations where the card can be used. this information can be used to provide location-based service and samsung wallet can use this information to show maps, place names and addresses. you can find more about the location field and the json format in the documentation. noticedesc optional. the notices section can be used for any additional information for your card. you can use html tags without any css or script in this field. for the test card, this field contains the following list: <ul> <li>loyalty card notice. <a href="https://www.samsung.com/">learn more.</a></li> <li>loyalty card notice.</li></ul> csinfo optional. customer service information visible to the card user. this information is stored as key-value pairs with the following keys that correspond with the categories of information shown to the user: callemail website applinklogo required. application link logo url applinkname required. application link name applinkdata required. application link destination url bgimage optional. background image for the card bgcolor optional. background color for the card. if you use bgcolor together with bgimage, they are displayed in a predefined ratio. to only display a background image, omit the bgcolor value. the following image shows the difference between a scenario where both bgimage and bgcolor are used (left) to one where only bgimage is used (right). fontcolor optional. font color on the card art. barcode.value optional. barcode data and serial number. barcode.serialtype optional. barcode presentation type. for more details, see the presentation types (serialtype) table. barcode.ptformat optional. barcode presentation format. you can find all supported presentation formats in the presentation formats (ptformat) table. barcode.ptsubformat optional. barcode format. some commonly used barcode formats are listed in the barcode formats (ptsubformat) table. barcode.errorcorrectionlevel optional. qr code error correction level. four error correction levels are available: l/m/q/h. merchantid optional. merchant identifier. use this field if you have merchant id. merchantname optional. merchant name. amount optional. total amount of points or initial balance. it is recommended to use a one-letter currency symbol. use any of these formats: $1,000 or 1,000p. balance optional. available points or remaining balance. use the same format as the amount field. card json example the card data must be in the json format and needs to follow the specific structure. the example below shows a card data sample that we have used to implement the loyalty card used in this content. modify the card data as per your card information. find more about the card data format in the wallet cards documentation. { "card": { "type": "loyalty", "subtype": "others", "data": [ { "refid": "9400ae65-751b-4327-866c-37e8c228f1c4", "createdat": 1672574400000, "updatedat": 1672574400000, "language": "en", "attributes": { "title": "card title", "eventid": "event-001", "groupingid": "group-001", "orderid": "order-001", "subtitle1": "card subtitle", "logoimage": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg", "logoimage.lighturl": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg", "logoimage.darkurl": "https://kr-cdn-gpp.stg.mcsvc.samsung.com/devops/ops/partner-portal/test-tool/assets/img/ticket_movie.jpg", "providername": "provider name", "startdate": 1715533051242, "enddate": 1715833051242, "noticedesc": "<ul><li>loyalty card notice. <a href=\"https://www.samsung.com/\">learn more.</a></li><li>loyalty card notice.</li></ul>", "csinfo": "{\"website\":\"https://homepage.com/cs\",\"email\":\"cs@email.com\",\"call\":\"555 333 111\"}", "applinklogo": "https://play-lh.googleusercontent.com/znfa1roz7hpv9j-jiacbjmjudl2x-fnuwte0oyvbbcwvf5vpzoqqikbxgk7d-aptvag=w240-h480-rw", "applinkname": "loyalty card link", "applinkdata": "www.samsung.com", "bgimage": "https://djcpagh05u38x.cloudfront.net/wlt/us/stg/x1iwgocnroqa5dmwpykfkq/qupknpwntmqt7letkgufag.png", "bgcolor": "#ffffff", "fontcolor": "#ffffff", "locations": "[{\"lat\":48.861614505643196,\"lng\":2.380811870098114,\"address\":\"38 rue saint-maur, 75011 paris\",\"name\":\"atelier des lumieres\"}]", "amount": "$1,000", "balance": "$100", "barcode.value": "cs16138353212584806754fg1802", "barcode.serialtype": "qrcode", "barcode.ptsubformat": "qr_code", "barcode.ptformat": "qrcodeserial", "barcode.errorcorrectionlevel": "m", "merchantid": "123344433", "merchantname": "merchantname" } } ] } } test with the add to wallet test tool once the card data specification details and the json structure of the loyalty card are established, we can test the "add to samsung wallet" functionality. first, we use the add to wallet test tool as this tool provides minimal card data in json format by default. after that, you can modify the json data and test the cards as you want. follow the instructions below to use the add to wallet test tool. for more details, refer to the add to wallet test tool documentation. sign in to the add to wallet test tool. enter the private key in the enter partner private key field. select the loyalty card we have created and then enter the json in the data field. finally add the card to samsung wallet. create jwt token if testing with add to wallet test tool is successful, you can implement the "add to samsung wallet" functionality with your application or website and handle the card data token generation process on your server. finally, generate the url and integrate it with the "add to samsung wallet" button. for more details on the implementation, check out our implementing "add to wallet" in an android application article, which is a complete guide to implementing the "add to samsung wallet" button on an android application and handling the card data token generation process on the server side. conclusion once the implementation of both the application and server is completed, you can integrate the loyalty card with your production server and perform a full test on the loyalty card. after the test is done, an admin will check and set the card as active. while implementing your card, follow the steps shown in seamlessly integrate "add to wallet" for samsung wallet, as this article focuses on the common mistakes. if you have any questions or face difficulties implementing the card, you can contact samsung developer support. related resources integrate "add to samsung wallet" button into partner services implementing "add to wallet" in an android application seamlessly integrate "add to wallet" for samsung wallet
M. A. Hasan Molla
tutorials mobile
blogwallet 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
featured
blogwallet cards https://developer.samsung.com/wallet/manage.html step 3. integrate “add to samsung wallet” to your service https://developer.samsung.com/wallet/api/overview.html if you are in a country where the event ticket menu is not supported on galaxy devices, contact us through developer support and we will help you as quickly as possible.
Hye-In Min
tutorials mobile
blogsamsung has invested tremendous effort in the digital economy from the very beginning and continuously facilitates millions of people who use samsung wallet. samsung wallet is one of the most used digital wallets right now in the cashless industry. it is a medium that fuels up digital currency transactions by its ease-of-use and security. to support various businesses, samsung has developed the samsung pay sdk which allows you to use samsung wallet’s features effortlessly. the samsung pay android sdk consists of android-based apis to perform transactions using samsung wallet. it helps to implement simple payment solutions, which boost your businesses' growth to the next level. to understand the business and possibilities, visit the samsung pay sdk portal for more information. what is push provisioning? push provisioning is one of the major features of the samsung pay sdk. it allows an issuer bank to push the payment experience to a digital wallet. it simplifies the process of adding a payment card as it can be done with a single tap of a finger. the normal process is time consuming since it involves multiple steps, and the user needs to enter their card information. with push provisioning, the process is easier as it can be done with a single tap, and it's also secure because the process is performed from the issuer application. this tutorial demonstrates how to implement the push provisioning feature in an issuer application with the samsung pay sdk. figure 1: samsung pay push provisioning concept prerequisite to use the samsung pay sdk, you must be an official samsung partner. for information about the partnership process, see the samsung pay member guide. as a samsung pay sdk partner, you can utilize this tutorial while implementing push provisioning. sdk integration to download the samsung pay sdk, go to samsung developers portal > samsung pay > download . when the download is complete, a .jar file called “samsungpaysdk_x.xx.xx_release.jar” can be found under the libs folder. add the samsung pay sdk .jar file to the libs folder of your android project using android studio or file explorer. navigate to the build.gradle file of your application module and enter the following dependency to the dependencies block: implementation files('libs/samsungpaysdk_x.xx.xx_release.jar') if the target sdk version is 30 or higher (android 11 or r-os), include the following <queries> element in androidmanifest.xml. for more information, see declare package visibility needs. <queries> <package android:name="com.samsung.android.spay" /> </queries> since we are using the latest sdk, set the api level to 2.18. we recommend using the updated version of the samsung pay sdk for a better user experience. implement the following code in the <application> element of androidmanifest.xml: <meta-data android:name="spay_sdk_api_level" android:value="2.18" /><!-- most recent sdk version is recommended to leverage the latest apis--> configure the debug or release mode for your project as follows: for testing and qa, set the debug mode value to y. this mode requires the allowed samsung account(s) list to test. for market release to end users, set the debug mode value to n. <meta-data android:name="debug_mode" android:value="n" /><!--set to y if debug mode--> let’s get started since the main functionalities in this tutorial are based on push provisioning, we need to initialize the samsungpay and cardmanager classes first. these two classes take the same parameters to construct, which are context and an instance of the partnerinfo class. the partnerinfo object contains information about partners, which is to validate the request from the issuer application. private val partnerinfo = partnerinfoholder.getinstance(context).partnerinfo private val samsungpay= samsungpay(context,partnerinfo) private val cardmanager = cardmanager(context, partnerinfo) check if samsung wallet is ready since the samsung pay sdk depends on samsung wallet, you need to ensure that samsung wallet is prepared for transactions. check the samsung wallet status before the sdk api call using the getsamsungpaystatus() method. if you get the "spay_ready" status, you can proceed further to call any api. for more details, see the programming guide. samsungpay.getsamsungpaystatus(object : statuslistener { override fun onsuccess(status: int, bundle: bundle?) { if(status == spaysdk.spay_ready){ //enable samsung pay sdk functionalities } else{ //disable samsung pay sdk functionalities } } override fun onfail(status: int, bundle: bundle?) { //disable samsung pay sdk functionalities } }) check if the card is added during development, you may need to know whether the card is already added to samsung wallet or not. to get a list of cards that have already been added to the wallet, use the getallcards() method. for card-related operations, such as getting cards from samsung wallet, the cardmanager class is the responsible one to perform. this means that the getallcards() method is a property of the cardmanager class. this method takes a bundle and an interface as parameters, so it returns the result based on the operation. notethe getsamsungpaystatus() method must be called before the getallcards() method. the getallcards() method cannot return a card list if the getsamsungpaystatus() method responds with a code other than spay_ready. tipone of the most common issues during development is that the getallcards() method returns empty data even though a card has been added. the main reason for this issue is that the card issuer name and issuer name on the samsung pay portal are not the same. for more information, see the faq & troubleshooting page. val getcardlistener: getcardlistener = object : getcardlistener { override fun onsuccess(cards: list<card>) { //show cards } override fun onfail(errorcode: int, errordata: bundle) { //show error } } cardmanager.getallcards(null, getcardlistener) configure your payload the getwalletinfo() method is designed to request wallet information from the samsung wallet application prior to performing the add card operation. wallet information can be mandatory or optional for token providers for payload configuration. for visa, wallet information is mandatory, and you have to use it while building the payload. val keys = arraylist<string>() keys.add(samsungpay.wallet_dm_id) keys.add(samsungpay.device_id) keys.add(samsungpay.wallet_user_id) val statuslistener: statuslistener = object : statuslistener { override fun onsuccess(status: int, walletdata: bundle) { val deviceid: string? = walletdata.getstring(samsungpay.device_id) val walletaccountid: string? = walletdata.getstring(samsungpay.wallet_user_id) //build payload } override fun onfail(errorcode: int, errordata: bundle) { //show error } } samsungpay.getwalletinfo(keys, statuslistener) complete the push provisioning the last command to execute the push provisioning operation in our tutorial is the addcard() method, which is required to perform the push provisioning in samsung wallet. the payload we have created must be delivered with the addcard() method as a parameter. the payload is a tricky part where partners can sometimes get confused or misguided. to be clear, samsung does not provide the payload for push provisioning. the payload is defined between the issuer and the token provider, and it varies based on different issuers and token providers. samsung only delivers the payload to the token provider without consuming anything. the addcard() method also takes a callback as a parameter to return the result based on the operation. tipfor push provisioning of a payment card, samsung pay does not store any card information nor provide any payload for adding cards. so, the issuer needs to provide the payload in a format that is defined in the token provider specification. the issuer and the token provider have their own agreement of data sharing, payload, and encryption. samsung pay is only a medium for this process. val tokenizationprovider = addcardinfo.provider_abcd val carddetail = bundle() carddetail.putstring(extra_provision_payload, payload) var cardtype = card.card_type_credit_debit val addcardinfo = addcardinfo(cardtype, tokenizationprovider, carddetail) val addcardlistener: addcardlistener = object : addcardlistener { override fun onsuccess(status: int, card: card) { //show successful message } override fun onfail(errorcode: int, errordata: bundle) { //show error } override fun onprogress(currentcount: int, totalcount: int, bundledata: bundle) { //extra event for operation count } } cardmanager.addcard(addcardinfo, addcardlistener) summary push provisioning is the powerful experience of sharing information to a digital wallet, and digital wallets transform this experience to the next level by facilitating transactions within seconds. samsung wallet handles these operations and helps the digital payment system to its next step. for more information about the samsung pay sdk, visit the samsung pay developers portal. if you face any issues during sdk implementation, contact the developer support team.
Yasin Hosain
tutorials mobile
blogas businesses strive to enhance their mobile payment capabilities and provide seamless transaction experiences to users, integrating third-party payment solutions like samsung pay has become increasingly common. however, amid the excitement of implementing these solutions, developers often encounter challenges and pitfalls that can hinder the integration process and impact the overall user experience. in this blog, we show some of the most common mistakes developers make when integrating the samsung pay sdk, and offer practical insights and best practices to overcome these hurdles and ensure successful implementation and testing. pitfall 1: using an unofficial email id to implement the samsung pay sdk, the first step is to establish a partnership between your company and samsung. when submitting a partnership request, do so using your company's official email domain. this precaution is crucial, as partnership requests originating from non-official email addresses are prone to rejection by the samsung relationship manager. pitfall 2: providing the wrong issuer name while creating your service while creating a service for the push provisioning feature, you have to add the issuer names, meaning the names of your financial institution or bank. you must make sure to provide the correct names that have been registered with the card networks such as visa, mastercard and so on. if incorrect names are provided, the getallcard() api returns an empty list even though the card has already been added to the samsung wallet. to confirm your issuer name, first add your card to the samsung wallet application. tap on the card in the wallet application, open the more menu, and select customer services. the correct issuer name is listed on the “customer services” pane. to correct your issuer name for services that you have created: select my projects > service management. select the service name to open the service details page. select edit info. you can delete the incorrect issuer name and enter a new one. pitfall 3: using service id with an invalid effective date a common error that occurs during sdk integration is the error_expired_or_invalid_debug_key (-310) error. this error occurs in two cases: using a newly created service id without generating an expiration date of the service: after creating a service, if you check the edit info of the service details page, you will find that the debug effective data is blank. hence, you have to generate a date right after creating the service. using a service id with an expired debugging date: the service id provided by samsung pay portal remains valid for 90 days. after that time, the service expires. therefore, you must generate a date for debugging every 90 days. to generate or extend the validity date of the service: select my projects > service management. select the service name to open the service details page. select edit info. click generate new date. provide a samsung account for testing the application. this account is placed on the allow list for testing. click generate. the new expiration date of your service appears on the page. remember to extend the date after 90 days if you continue testing your application past that point. pitfall 4: configuring the release service with insufficient information it is essential to include the apk file when setting up the release service. failure to include the apk file will result in samsung pay’s relationship manager rejecting the service, leading to delays in the release process. additionally, ensure that you have correctly integrated the appropriate service id into your release application. pitfall 5: testing your application with a mismatched configuration samsung wallet uses the service id, package name, and apk signature for partner verification. if you test your application with an apk signature different from the one already registered in the samsung pay portal, samsung pay recognizes that the apk signature is inconsistent with the service id and produces the error code -6 (not_allowed). in conclusion, navigating the integration of the samsung pay sdk can present you with many challenges. but, armed with the knowledge shared here, you can steer clear of some potential pitfalls and ensure a smoother implementation process. by prioritizing thorough testing, adhering to best practices, and maintaining clear communication with samsung's support channels, you can mitigate risks and deliver a seamless payment experience to users.
Ummey Habiba Bristy
events mobile, iot, game, health, galaxy watch, smarttv, foldable
blogthis week we're gearing up for the samsung developer conference and can't wait to see samsung's newest developer technology enhancements. while looking at the list of wednesday's tech sessions, we couldn't help but spill the beans on the online and in-person tech sessions that excite us the most. in-person tech sessions samsung wallet, it's convenient, personal, and safe as the growth of digital wallets skyrockets, samsung recently announced samsung wallet–a new platform bringing almost all of the cards you’d typically find in a physical wallet, as well as important documents, into one easy-to-use and secure mobile application. as samsung wallet rapidly expands its content set, robert white will share more about the future of digital wallets and how open apis can allow developers to build integrations for the samsung wallet. click here to learn more. what's new in tizen are you curious about the direction in which intelligent iot platform “tizen” is going? learn what’s new in tizen’s android hardware and get tips for cross-platform application development with hobum kwon and hyunju shin. this in-person tech session will introduce updates to the ui assistant technology and the extended 3d ui framework. it will also introduce the new iot standard "matter." click here to learn more. intuitive multitasking experience based upon android 12l join sanguk jeon to see how samsung continues to enhance the large screen user experience with fast app switching and intuitive multitasking capabilities. learn how the galaxy foldable experience is expanding flex mode even further with more apps, partners, and google's ongoing collaborative effort in android 12l. click here to learn more. on-demand online tech sessions expand health experiences with galaxy watch the galaxy watch’s powerful bioactive sensor, together with wear os powered by samsung, is transforming mobile health experiences. in this online session, sungchull lee will share how to help users accurately monitor their health stats through samsung’s privileged health sdk. this sdk allows developers to retrieve raw or analyzed sensor data for their applications, including bia, ecg, and blood oxygen level or sweat loss. click here to learn more. creating spectacular galaxy game audio experiences with dolby atmos discover how dolby atmos can help developers create a deeper emotional connection with players, keep gamers playing for longer, and earn their loyalty by unleashing the full power of samsung galaxy mobile and tablet game audio. in this online session, you will hear from matthew reyes, john couling, and dolby’s partner, audiokinetic, who will walk you through how you can make dolby atmos games and how to use dolby atmos plug-ins in audikinetic's wwise audio middleware. also moong labs–creators of epic cricket, one of india's most popular sports games–will also share how dolby atmos benefitted their game. click here to learn more. sign up for sdc in case you plan to go to sdc, you can see the full list of live tech sessions to attend. if you can't make it irl, you can sign up for sdc online and attend these on-demand sessions.
Mischa Shankerman
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.