Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
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
docmanage wallet card for verify with wallet please take a look at 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 wallet cards draft status partners can create and manage their wallet cards with this step-by-step guide manage wallet cards partners can manage all registered wallet cards partners can edit wallet cards and check their status general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the samsung wallet item description testing mode all data generated during testing mode is periodically deleted be sure to turn off the 'testing mode' setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name automatically generated partner app package name partner app package name wallet card template pre-defined partner’s wallet card template type > sub type > design type wallet card custom setting type authentication issuer set the authentication issuer for the relying party service to be provided as this wallet card please select authentication issuers from the identity provider groups only authentication issuers with the same “service location” as the relying party service are displayed ※ the identity provider of the “authentication issuer”is supported depending on the "service location" set partner rp get request 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}/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 ttype you selected ※ for rp partners the "authentication issuer" attribute is a unique property of the relying party card the identity provider of the authentication issuer is supported depending on the "service location" set e g if service location is in the us, the authentication issuer field only supports an identity provider belonging to the us when the parent hierarchy value is checked, its children values created later are automatically checked in the united states, the authentication issuer is the state government, and the driver's license can be understood as an mdl mobile driver's license view wallet card partners can view all the registered information, edit and delete the wallet card launch wallet cards verifying status partners can launch and activate cards you can activate a card by clicking the launch button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, partners can modify and re-launch the administrator registers the reason for rejection when rejecting a launched wallet card partners will receive an email from the system, including the reason for rejection partners can apply for launching again by checking the reason for rejection and modifying the wallet card information testing mode partners can test a card internally to make sure everything works before officially release to the users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to ‘active’ after administrator approval when the card is activated, it becomes visible to the user verify with samsung wallet integration to integrate the wallet, you need to run the ‘verify with samsung wallet’ script into your system the verify with samsung wallet script is available for both web and android platforms each system has a different composition to implement the verify with samsung wallet button, follow the steps below in order create tokenized card data cdata card data is the actual content data of wallet card and it has several format based on card type please refer to generate_cdata sample code for detail copy the sample verify with samsung wallet script from partner portal’s wallet card page and replace cdata with the data token created above apply the script to your system please see web_integration sample code and app_integration sample code for detail below are ‘verify with samsung wallet’ script guide in partner portal to integrate the ‘verify with samsung wallet’ you may need some base data you can find this base data and other necessary information on the partner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis
tutorials mobile
blogintroduction the samsung wallet application lets you store cards that can be used for various purposes. if you want to provide reward points to your members, use the newly introduced loyalty card type, also known as a membership card. in this article, we show how you can create a loyalty card in the wallet partners portal. we also provide guidelines to implement the card, so that you can integrate the loyalty card into your application. card setup before adding the card to samsung wallet, create your card in the wallet partners portal. log in to the wallet partners portal. select wallet 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
Learn Code Lab
codelabverify your id with samsung wallet objective learn how to verify a user's identity with the id information registered in their samsung wallet app partnership request to create, manage, and monitor performance of wallet cards with the samsung wallet partners site, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more by visiting samsung wallet partner onboarding process, here in samsung developers notein accordance with the applicable samsung wallet partners agreements, this code lab covers the setup and use of the verify with samsung wallet service for purposes of integrating samsung wallet with partner sites and apps the use cases and corresponding code samples included are representative examples only and should not be considered as either recommended or required overview verify with samsung wallet enables users to utilize the digital id added to their wallets to simplify online transactions that require an identity verification a mobile device with samsung wallet installed is required to verify the user’s identity through this feature this feature uses the relying party card type to verify a user's identity using the id information stored in samsung wallet this feature supports app-to-app app2app and web-to-app web2app integration models the web2app integration supports the partner's mobile web application to request a verification to the samsung wallet app the app2app integration supports the partner’s mobile application to request a verification to the samsung wallet app when the partner site requests the user to verify their identity, the verify with samsung wallet button is displayed the user is redirected to the samsung wallet app where they verify their identity via pin or biometrics once verified, the user's identity information is sent to the partner and the transaction will proceed noteas of 2024, this feature is only available in the united states and can be used by the state government with mobile driver's license mdl support for more information, visit https //developer samsung com/dashboard/support for detailed description, see verify with samsung wallet set up your environment you will need the following access to samsung wallet partners site samsung galaxy device that supports samsung wallet app samsung wallet app latest version android studio latest version recommended java se development kit jdk 11 or later supported mobile driver's license be added to samsung wallet app internet browser, such as google chrome openssl intellij idea or any java ide optional sample code here is a sample code for you to start coding in this code lab download it and start your learning experience! verify with wallet sample code for app2app integration 802 3 kb start the onboarding process partners can manage wallet cards and monitor performance with the samsung wallet partners site to join as partner generate a private key and certificate signing request csr using the openssl command you can follow the instructions in security factors notea private key enables encryption and is the most important component of certificates while csr, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country proceed to register in the samsung wallet partners site using your samsung account follow the samsung wallet partner onboarding process upload the generated csr for data encryption in encryption setting management section after registration, you will receive a welcome email noteupon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes signed certificate used along with the private key to sign data samsung certificate used to encrypt card data and validate authentication tokens in server api headers create a relying party wallet card follow the steps below to create a wallet card in samsung wallet partners site go to wallet cards > manage wallet card and click add wallet card in wallet card template field, choose [wallet] relying party as wallet card type and relyingparty > others as sub type select the design type and click done in wallet card custom setting, click change, and choose drivers as authentication issuer you can also select specific mdls such as below notethe authentication issuer is a unique property of the relying party card type the identity provider of the authentication issuer is supported depending on the service location set for example, if the service location is in the united states, the authentication issuer field only supports any identity provider in the united states region in main headquarters location, select united states once finished, select save to view all registered information launch wallet cards you can launch and request activation of the cards by clicking the launch button upon agreeing to proceed, the launch button text changes to launched and the card status becomes verifying create a verify with samsung wallet button app2app for the app2app integration, you need to setup the button inside the mobile application in android studio, click open locate the downloaded android project rpclient_codelab from the directory and click ok go to app > kotlin+java > com samsung android sample rpclient > presentation > partners and, in the partnersrequestfragment kt file, add the verify with samsung wallet button inside the oncreateview function glide with this load partner getverifybuttonimage into binding verifybutton set up a click listener for the verifybutton binding verifybutton setonclicklistener { /// add the requestdata variable to prepare the request fields /// add the applink variables to request the card information /// call the applink method to request verification } inside the listener, add the requestdata variable to prepare the request fields for verification val requestdata = demodata requestdata add the applink variables to request the card information val applink = rpclientapis buildapplink partnerid = partner getpartnerid , cardid = partner getcardid , payload = partner buildapp2apppayload , samsungpublickey = partner getsamsungpublickey , partnerpublickey = partner getpartnerpublickey , partnerprivatekey = partner getpartnerprivatekey , isstagingserver = true the data being requested are as follows partnerid = gets the partner id from the identification card used cardid = gets the card id from the identification card used payload = builds the app2app payload samsungpublickey = gets the samsung public key partnerpublickey = gets the partner's public key partnerprivatekey = gets the partner's private key isstagingserver = checks if the application runs on a staging environment noterequested data such as partnerid, public keys, and private keys are generated during the onboarding process, while cardid is generated when you create a wallet card however, in this code lab, these data is already predefined and included in the sample mobile app call the applink method to request verification this method creates a channel between the test app and samsung wallet app to create the request and response data for the verification process applink? let { log i tag, applink rpclientapis request "com samsung android spay", uuid randomuuid tostring , applink, object rpclientapis onresponselistener { override fun ongetmdocrequestdata deviceengagementbytes bytearray bytearray? { log i tag, "deviceengagementbytes=${deviceengagementbytes tohex }" val keypair = securerepository generateeckeypair log i tag, "requestdata=$requestdata" val encryptedsessionestablishmentbytes = securerepository buildsessionestablishment requestdata, deviceengagementbytes, keypair log i tag, "encryptedsessionestablishmentbytes=${encryptedsessionestablishmentbytes? tohex }" return encryptedsessionestablishmentbytes } override fun onmdocresponse encryptedresponsebytes bytearray { log i tag, "encryptedresponsebytes=${encryptedresponsebytes tohex }" try { val plainresponse = securerepository decryptmdocresponse encryptedresponsebytes log i tag, "plainresponse=${plainresponse? toprettyjson }" val responsedata = plainresponse? toprettyjson onresponse postvalue responsedata } catch e exception { e printstacktrace } } override fun onmdocresponsefailed exception exception { log i tag, "onmdocresponsefailed ${exception} " onerror postvalue exception } } } run and test the application app2app go to build > build app bundle s / apk s > build apk s to build the application install the apk file to your mobile device and test the sample app as follows open the sample app and choose sdc code lab press the verify with samsung wallet button once you are redirected to the samsung wallet app, press the verify button the samsung wallet app shows a checkmark to indicate that the identity has already been verified while the sample app displays a verification success screen test the verify with samsung wallet button web2app for the web2app integration, you can use the test tool to test the verify with samsung wallet button open a web browser on your computer or galaxy mobile device and go to the following link partner walletsvc samsung com/addtowallettest go to verify with wallet tab and click choose key file to upload your private key in the select card dropdown menu, select the card you created to display its details navigate to the form tab and modify the data as desired you can change the logo image or provider name press the verify with samsung wallet button once you are redirected to samsung wallet, press the verify button the samsung wallet app shows a checkmark to indicate that the identity has already been verified go back to the test tool, open the mdoc tab, and click the check result button it displays a result success popup when the verification process is successful tokenize card data and implement the verify with wallet button to your service optional notethis step is optional, but if you want to learn how to integrate the verify with wallet button into your services like an android app, web app, or email, you can follow these steps the samsung wallet partners site provides generated verify with samsung wallet scripts for each wallet card you create you can simply copy and paste these scripts into your partner apps web and android or include them in emails/mms messages to implement the verify with wallet button, follow these steps go to the [verify with wallet script guide] section of the card you created click show to view the available scripts and then copy the appropriate script for your service develop a program that can generate tokenized card data cdata the cdata represents the actual content of the wallet card and comes in different formats depending on the card type you can check the cdata generation sample code for reference the cdata is derived from the card data, which is in json format for testing purposes, you can utilize the generated json from the test tool follow the implementing button guide to determine where to incorporate the generated cdata and gain further insights into this process you are redirected back to your app and your identity is verified you're done! congratulations! you have successfully accomplished the topic of this code lab now, you are ready to verify your id with the verify with samsung wallet button into your application on your own! if you're having trouble, you may download this file verify with wallet complete code for app2app integration 802 5 kb to learn more about samsung wallet, visit developer samsung com/wallet
Develop Samsung Wallet
docoverview once the partner service onboarding is complete, you can create your own templates such as boarding passes, coupons and tickets in samsung wallet before you can create a new wallet type, you must first create a base template in general, wallet card creation and modification are possible through the ‘wallet partners portal' however, a server api is provided for cases where it is necessary to manage a large number of cards cards created through api can also be checked and managed in the same way on the ‘wallet partners portal' changes to each card status can be processed at the ‘wallet partners portal', and information on how to change them should be checked through the partner server portal guide the description of each state is as follows state description draft when a wallet card is created for the first time, it transitions to “draft” state in this state, all setting values can be modified verifying to launch and activate the card, the verification step must be completed the “verifying” state is a step in which the card is approved by an administrator for a card to be verified, at least one csr must be registered, and general information must be configured rejected the administrator registers the reason for rejection when rejecting the launched wallet card the reason for rejection is then sent to the partner by email through the system partners can apply for relaunch by checking the reason for rejection and modifying the wallet card information active the administrator has approved the partner’s requests the card is activated, and the activation cannot be canceled when the card is activated, it becomes visible to the user blocked the activated card has been blocked this function can only be performed by the administrator note that when a card is first created, testing mode is switched on automatically even if the card is active, if the testing mode is on, the service does not behave normally the testing mode must be changed to off first note that it is not possible to return to testing mode after switching the mode off, so ensure that the testing is complete before switching the testing mode off it is now possible to add wallet cards to a user's wallet wallet cards are added as described in 'add to samsung wallet', but in special cases, wallet cards can be added automatically only to allowed partners without user interaction
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
doccode resources cdata generation cdata generation sample code zip v1 1 2 16kb oct 02, 2024 this sample code shows how to generate cdata, which is required for implementing samsung wallet card service android integration sample code android integration sample code zip v1 0 1 118kb nov 26, 2024 this sample code shows how to implement samsung wallet card service for android web integration sample code web integration sample code zip v1 0 2 180kb july 25, 2023 this sample code shows how to implement the samsung wallet card service for web it consists of javascript api source code and web implementation sample code web implementation sample code is located in the packages > wallet-card > sample directory rpclient sample code onlinerpclientv zip v1 21 799kb feb 25, 2025 this sample code shows how to implement the verify with samsung wallet feature for android rp sdk rp sdk release aar v1 05 39kb feb 25, 2025 this file is the sdk for verify with samsung wallet, used in partner apps online rp client online rp client apk v1 21 10,200kb feb 25, 2025 you can experience the verify with samsung wallet feature using this partner sample app onlinerp partner server sample onlinerp partner server sample zip v1 0 437kb oct 02, 2024 this sample code shows how to implement the partner server api notethough every care has been taken to ensure the accuracy of these sample codes, samsung electronics co, ltd cannot accept responsibility for any errors or omissions or for any loss occurred to any person, whether legal or natural, from acting, or refraining from action, as a result of the information contained herein information in these sample codes are subject to change at any time without obligation to notify any person of such changes
Develop Samsung Wallet
docapi guidelines the adding samsung wallet card templates section defines interfaces for providers to conveniently create wallet cards in samsung wallet the generated wallet card templates can be updated by following the instructions on the updating wallet card templates section authorized partners can add wallet cards to users directly from the partner server by following the instructions on the adding wallet cards section below [service domain] environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card templates this section describes how to create a wallet card in samsung wallet [request] type value description method post url /partner/v1/card/template headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id unique value for each template created by a partner this value is set to a number of 19 digits or less cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 required the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate cardtype string 100 required template card type for details, refer to wallet cards cardtemplate subtype string 100 required template card sub type for details, refer to wallet cards cardtemplate designtype string 100 optional the value that defines the design type of the wallet card for details, refer to wallet cards cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of the image is 1024*1024 e g http //www yourdomain com/banner_logo_image png cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, the user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance, parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrcardstate string 1000 optional [get card state] partner url check the url format below and implement api according to url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional when creating a card, you can transition the card's state from “draft” to “verifying” you can only choose “draft” or “verifying” * default 'draft' cardtemplate desc string 500 optional description [example] /** example card template object **/ { "prtnrid" "4083254626439156160", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "cardtype" "coupon", "subtype" "others", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/] { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable updating wallet card templates wallet card tmplates updated through api can also be checked and managed in the same way on the ‘wallet partners portal' partners can manage all wallet cards they have created [request] type value description method post url /partner/v1/card/template/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate cardid string 32 required the cardid response received when creating a card cardtemplate templaterefid string 19 required partner template id the unique value for each template created by a partner this value is set to a number with 19 digits or less cardtemplate title string 32 optional wallet card name cardtemplate countrycode string 2 optional the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of that image is 1024*1024 cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomainn cardtemplate prtnrcardstate string 1000 optional partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional if the card status is “draft”, you can only select “verifying” cardtemplate testingmodeoff string 1 optional this value can be set only when the card status is active normal service is possible only when the testing mode is changed to off * default ‘n’ cardtemplate desc string 500 optional description [example] /* *example card template object **/ { "prtnrid" "4083254626439156160", "cardid" "3hdpejr6qi380", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template/cardid=3hdpejr6qi380 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable adding wallet cards a typical addition to the wallet card is triggered by user interaction, such as pressing the add to wallet button or link the api also supports adding a wallet card automatically to the user for a special purpose with user’s consent this api allows partners to provide wallet cards to users the request payload must contain information about the target to which the card is added this information may be related to the user’s account, or it may contain information about a card that is already registered a push notification is sent to the user’s device to confirm successful card registration the success of card registration must be determined that the card is registered normally when it is updated to added of send card state an administrator must grant permission for partners to use this api card data specification card id {card id} is an id issued when the partner manager signs up for partner services and register the wallet card they want to service refer to partner onboarding guide document for details cdata actual payload data in basic json format to establish the communication between partners and samsung wallet see the details in the table below card data token the specific wallet card data mentioned as cdata must be secured in jwt json web token format see a chapter security for details [request] type value description method post url /atw/v1/cards/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required wallet card identifier granted through the partner portal body parameters cdata object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object card object required wallet card object card type string 16 required wallet card type *see wallet cards card subtype string 16 required wallet card sub type *see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds *utc±00 00 data[] updatedat long 13 required data update timestamp epoch timestamp in milliseconds *utc±00 00 data[] language string 8 required default card language code e g en, ko data[] attributes object required attributes container data[] attributes {fields} required attributes fields by card type*see wallet cards data[] localization[] array of object optional localized language container *see wallet cards localization[] language string 8 required multilingual content language code, e g en, ko localization[] attributes {fields} for displaying a given language, ‘data[] attributes’ can be replaced by localized versions *see wallet cards account object conditional user account object account type string 16 required type of user identifier, e g phonenumber, email account value string 64 required user identifier [example] /** example card object **/ { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678” } } /** example **/ post /atw/v1/cards/1656147182764415319 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "cdata" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable
FAQ marketplace, mobile, web
docfaq & troubleshooting if the samsung pay app throws error_not_allowed -6 / error_unable_to_verify_caller -359 , what needs to be checked on the partner app side? for debug verify that the serviceid is correct; make sure it was generated for the test mode and not for release verify that the servicetype is correct; make sure it is same as the value assigned by the samsung pay developers portal when you create the service verify that the device’s samsung account is registered allowed under test accounts in the service details for release verify that the serviceid is correct; make sure it was generated for release and not for the test mode verify that the servicetype is correct; make sure it is same as the value assigned by the samsung pay developers portal when you create the service ask your samsung pay relationship manager rm to confirm that the status of your service is approved i received an onsuccess callback for a `getallcards ` response but the card list is empty even though there already one or more installed cards in samsungpay one of the most common exceptions during development is that “getallcard ” returns an empty list even though the card has already been added to the samsung wallet the main reason for this exception is the mismatch of an issuer name with the samsung pay portal the issuer name on the samsung pay portal and the actual issuer name of the card must be the same to overcome this problem if you cannot confirm the actual issuer name of the card, just add the card to samsung wallet app and see its details information open wallet app > tap on the card > three-dot menu > customer service option > under the title you will find the issuer name the following screenshot would be helpful for better understanding, i have received an onfail callback for `getsamsungpaystatus ` with a `spay_not_supported` status code if your app’s target api level is set to 30 or higher, refer to setting up your sdk development environmen part and follow guide for android r os targetsdkversion 30 i am getting 500 error when registering a csr while creating the 'web payment' service what should i do? if your csr was signed using your own private key rather than signed by a payment gateway, please select payment gateway with 'none default ' note the default pg name is 'none default '
Develop Samsung Wallet
docnotifications for partners partners can use pre-approved templates to send notifications to users who have their wallet cards importantonly authorized partners can use the notification feature the notification tab is not displayed to unauthorized partners register notification template partners can create a template for sending notifications on each of their wallet cards either through the partner portal or by using a separate api type partners can only choose the merchant push type message type you can choose a message type from marketing or others rejected comment if the merchant push notification is rejected after request approval, you can modify the message template the administrator registers the reason for rejection when rejecting the merchant push notification it is sent to the partner by email from the system, including the reason for rejection partners can request for approval again by checking the reason for rejection and modifying the message template approved date displays the date and time when the push message is approved by the administrator message template you can create the contents of the push, and it is also possible to put the available variables in '{{}}' after configuring the content, click harmfulness verification to verify whether there is a harmful expression in the content the verified result is displayed as pass or fail, and if it is fail, it shows the filtered harmful expression together even if the verified result is fail, an approval request can be made, but it can be rejected by the administrator if a different language is added to the default language in general information, the message template must also be entered for each added language request approval button after completing the message template, click this button to send an e-mail requesting approval to the administrator notification with a reference id this api allows partners to push notification to users who have their own wallet cards this request must include a reference id to receive the message and a template id this template id is issued when a partner creates a template through the portal only templates pre-approved by the administrator can be used this reference id is a unique identifier generated by the partner during add to wallet process [request] type value description method post url /{cc2}/wltex/cards/{card id}/notifications/{template id}/send header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type e g , bearer <credentials> * refer to authorization token for more details x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cc2string 2 required country code cc2 from send card state card idstring 32 required wallet card identifier granted from partners portal template idstring 32 required approved notification template identifier from partners portal payload ndatastring required notification object json * this field needs to be encrypted * refer to security for more details * the value of "cty" must be set to "notification" notification object refidsarray of string 100 required unique content identifier defined by the content provider data object required name-value pair for use in notification template [example] post /wltex/cards/12584806754/notifications/12353465344/send /*[headers]*/ authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /*[payload]*/ { “ndata” “eyjjdhkioijbvvriiiwidmvyi…” } /*[notification object]*/ { "refids" [ "ref-20230304-0003", "ref-20230304-0004" ], "data" { "name" "logan", "place" "samsung wallet" } } [response] type value description http status 200 ok payload n/a [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request
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.