Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
tutorials
blogsamsung wallet allows users to conveniently store and access payment cards, passes, and now also custom gift cards—all in one secure place. with gift card integration, partners can deliver a personalized and rewarding experience to their users, enhancing brand connection and user convenience. in this article, you learn how to create and integrate your own gift card as a partner using samsung wallet’s card template system. learn to customize visuals, define key details like balance and expiration date, and enable a seamless ‘add to samsung wallet’ experience for your customers. gift card setup are you ready to dive into the world of samsung wallet and create your first card template? follow these simple steps to get started and bring your ideas to life! step 1: complete the onboarding process if you have not done it already. for details, check out the onboarding guide. step 2: log in to the wallet partners portal. this is your gateway to creating and managing your wallet cards. step 3: once logged in, head over to the wallet cards section. here, you find the create wallet card option. for more details about creating a card, don’t forget to check out the manage wallet cards documentation. step 4: choose the gift card template from the list of available card templates. step 5: customize your card. now comes the fun part! modify the card information to suit your needs. through adjusting colors, adding logos, or tweaking text, this is where your creativity shines. step 6: launch your card once you are satisfied with your edits. for more details on launching, refer to the launch wallet cards guide. notemanaging multiple cards through the wallet partners portal can be challenging. samsung offers server apis to simplify the process, enabling you to create and modify samsung wallet card templates efficiently, without relying on the portal. explore the following blog topic for detailed insights: create samsung wallet card templates using the server api. gift card specifications before generating the card data token for the ‘add to samsung wallet’ button, it’s essential to understand the structure of a sample gift card. every gift card in samsung wallet is built from a defined set of data fields that determine how the card looks and functions. these fields are part of the card’s json structure and control everything from how the card title appears to how barcode data is delivered when scanned. the following examples illustrate how different card elements map to the gift card specifications. each image highlights a specific group of parameters used when creating a gift card for samsung wallet. basic gift card information this image illustrates the core elements that define the basic structure of a gift card in samsung wallet. it highlights the required fields—such as title, applinkname, applinkdata, and applinklogo—which control the card’s main display name and linked actions. optional parameters like bgimage enhance the visual design by allowing a custom background. together, these specifications form the foundation of the card’s visible layout and branding. this image demonstrates the specification fields that define the card’s balance, expiration date, and barcode data in samsung wallet. this image illustrates how the barcode appears when the user taps the pay button on the gift card. the displayed barcode corresponds to barcode.serialtype, which specifies the presentation format (such as barcode or serialnumber). this configuration allows users to redeem their gift cards seamlessly by scanning the code at a merchant terminal. this image demonstrates the use of the csinfo field to store customer support information. telephone number, email address, and website address information can all be stored in it. this image illustrates how the gift card’s display language adapts to the user's device language settings through the localization field. localization allows the user to serve content in multiple languages. when a user sets their device to a specific language, the corresponding localized content is displayed on their device. these specifications collectively define how your gift card appears and behaves in samsung wallet. for more detailed insights, check out the comprehensive gift card document. gift card json structure once you’ve reviewed the gift card specifications, the next step is to define them in the json structure. this data structure contains all the parameters that describe your gift card—including its title, amount, expiration date, barcode details, and optional links. the json is used to generate the card data token, which securely transfers the card information when users tap ‘add to samsung wallet’. the following is an example json file for a sample gift card: { "card": { "type": "giftcard", "subtype": "others", "data": [ { "refid": {refid}, "createdat": {createdat}, "updatedat": {updatedat}, "language": "en", "attributes": { "title": "sample gift card", "eventid": "event-001", "logoimage": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/ghdkj4z2q5o23cwuxsupbg.png", "logoimage.darkurl": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/zdzswfkbtvuvaz35mskmzw.png", "providername": "gift card provider name testing", "user": "john smith", "csinfo": "{\"call\":\"(+82) 1588-3366\",\"website\":\"https://www.samsung.com/us/\"}", "applinklogo": "https://d3unf4s5rp9dfh.cloudfront.net/tango/03-11-2025-wallet-gift-card-applink-logo-image.png", "applinkname": "gift card link", "applinkdata": "https://developer.samsung.com/wallet", "bgimage": "https://d3unf4s5rp9dfh.cloudfront.net/tango/03-11-2025-wallet-gift-card-design-v2.png", "fontcolor": "", "amount": "100p", "startdate": {startdate}, "enddate": {enddate}, "barcode.value": "sdc0102025", "barcode.serialtype": "qrcode", "barcode.ptformat": "qrcodeserial", "barcode.ptsubformat": "qr_code" }, "localization": [ { "language": "ko", "attributes": { "title": "삼성 월렛" } } ] } ] } } noteif you do not specify a fontcolor value, it automatically adapts to your system settings. for instance, in dark mode, the font color is light, and in light mode, it is dark. gift card testing with the ‘add to wallet’ test tool you have created a gift card in the wallet partners portal, now check if the card works properly before further development process. follow these steps to check the card. sign in to the add to wallet test tool, navigate to the playground section, select the gift card from the dropdown menu, and press add to samsung wallet. navigate to the add to wallet menu on the add to wallet test tool site and follow the step-by-step guide provided in the add to samsung wallet test section in the online test tool documentation. ‘add to samsung wallet’ implementation after testing the card with the ‘add to wallet’ test tool, you can let users add it directly to samsung wallet. implement the ‘add to samsung wallet’ button so that user can add the card to their wallet. for more details, refer to the implementing atw button documentation. in the ‘add to samsung wallet’ button implementation process, the generated jwt token expires after 30 seconds. as a result, you need to implement the server logic so that this token generates after the user interaction like pressing a button. see the implementing "add to wallet" in an android application blog to get details on the server-side logic implementation process of an ‘add to samsung wallet’ button in an android application. conclusion bringing your gift cards to samsung wallet creates a secure, seamless, and branded experience for your users. by defining your card data, generating the token, and enabling the add to samsung wallet flow, you make digital gifting effortless and engaging. start integrating today and let users enjoy convenient, personalized gifting within samsung wallet. 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
Most Fowziya Akther Houya
tutorials
blogsamsung wallet provides an e-wallet service to its customers through wallet cards. adding a card to the user device is normally triggered by user interaction, cards are added to their device when the add to wallet button or link is pressed. the adding wallet cards api provides the functionality to add cards to user devices directly without user interaction. a partner can provide wallet cards to the user’s wallet directly using the user’s email or mobile number. this article demonstrates a complete implementation of the adding wallet cards api. in the example scenario, we add a coupon type card to a user device from a partner’s server using this api without any user interaction. system requirements the adding wallet cards api has the following prerequisites: new samsung wallet users must first complete the onboarding procedure and obtain the required security certificates. create a new coupon card template through the wallet partners portal and launch the card. as a partner you can also create a card template through the partner server. for more details, refer to the create samsung wallet card templates using the server api. using the adding wallet cards api requires explicit permission from samsung. contact samsung developer support for authorization. api fundamentals this restful interface enables partners to deliver wallet cards directly to user accounts from their servers. endpoint: the service url where card addition requests are processed. https://tsapi-card.walletsvc.samsung.com/atw/v1/cards/{cardid} headers: only verified partners can utilize this api. header information establishes secure communication between the partner and samsung servers. authorization: bearer token authentication. refer to json web token documentation for specifications. x-smcs-partner-id: your unique partner identifier required for api access. x-request-id: a unique uuid string that identifies each request. body: must include a cdata parameter containing a jwt token with card details and user account information. detailed api specifications are available in the official documentation. api implementation process the adding wallet cards api enables partners to deliver cards directly to the user's account or wallet. follow this step-by-step approach to implement the api. for a better understanding of the overall process, download the sample source code. step 1: cryptographic key management extract necessary keys from security certificates for jwt token generation in subsequent steps. public key retrieval the following function extracts public keys from partner.crt and samsung.crt certificate files received during the onboarding process. def getpublickey(crt_path): """ extract public key from a .crt file. """ try: with open(crt_path, "rb") as f: crt_data = f.read() certificate = x509.load_pem_x509_certificate(crt_data, default_backend()) public_key = certificate.public_key() public_key_pem = public_key.public_bytes( encoding=serialization.encoding.pem, format=serialization.publicformat.subjectpublickeyinfo ) return public_key_pem except exception as error: print(f"error reading public key from {crt_path}: {error}") return none private key retrieval this function retrieves the private key from the .pem file generated during the onboarding process. def getprivatekey(pem_path): ''' extract private key from a .pem file. ''' try: with open(pem_path, "rb") as data: private_key = serialization.load_pem_private_key( data.read(), password=none, backend=default_backend() ) return private_key except exception as error: print(f"error reading private key from {pem_path}: {error}") return none step 2: authentication token creation samsung validates each api request through an authorization token in jwt format. to generate a valid authentication token: construct an authheader with auth as the payload content type. include the certificate id from my account > encryption management in the wallet partners portal. build the payload using the authheader structure. generate the final authorization token. the following code snippet implements the steps above. def generateauthtoken(partnerid, certificateid, utctimestamp, privatekey, cardid): auth_header = { "cty": "auth", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, "alg": "rs256" } auth_payload = { "api": { "method": "post", "path": f"/atw/v1/cards/{cardid}" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token step 3: card data token generation (cdata) the request payload requires a cdata parameter containing a jwt token with card information and user details. follow these steps to construct the cdata token. card information structure build a card data object containing all necessary information about the card to be delivered and the target user account. cdatapayload = { "card": { "type": "coupon", "subtype": "others", "data": [{ "refid": "e389dc8a-4616-494c-a8b3-80380f449fc2", "createdat": 1727913600000, "updatedat": 1727913600000, "language": "ko", "attributes": { "title": "strawberry icecream-1", "orderid": "order-001", "groupingid": "grouping-001", "mainimg": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/ldzf4fwlq9i5iqoym1r2yw.png", "brandname": "cioud icecream", "expiry": 1762225720029, "issuedate": 1727913600000, "redeemdate": 1727913600489, "noticedesc": "<div>▶precautions<br>-this product is an example image and may be different from the actual product. <br>-only available within the expiration date.<br><br>", "editableyn": "n", "deletableyn": "y", "displayredeembuttonyn": "n", "addtowalletcouponyn": "y", "notificationyn": "y", "applinklogo": "https://play-lh.googleusercontent.com/o5iwmhhbrmiga_4xdsxmizthld-wwu2ln6fbz6znpdlmkif0i98sfhtwzkyzjan-tw=w240-h480-rw", "applinkname": "cioud icecream", "applinkdata": "https://www.samsung.com/us", "barcode.value": "1111222233334444", "barcode.serialtype": "barcode", "barcode.ptformat": "barcodeserial", "barcode.ptsubformat": "code128" }, }] }, "account": { "type": "email", "value": "example@samsung.com" } } cdata jwt token construction generate the jwt token using the following implementation. additional information about the jwt format is available in the card data token section of the security documentation. def generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data): jwe_header = { "alg": "rsa1_5", "enc": "a128gcm" } jwe_token = jwe.encrypt( data, samsungpublickey, encryption=jwe_header["enc"], algorithm=jwe_header["alg"] ) print(f"jwe_token: \n{jwe_token}\n") jws_header = { "alg": "rs256", "cty": "card", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, } jws_token = jws.sign( jwe_token, key=partnerprivatekey, algorithm='rs256', headers=jws_header ) print(f"jws_token: \n{jws_token}\n") return jws_token step 4: build http request and execute with all required components prepared, construct the card addition http request using the following code structure: # --- prepare json body (python dictionary) --- c_data_json_body = { "cdata": cdatatoken } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "x-request-cc2": "kr", "content-type": "application/json" } # --- execute http request --- try: response = requests.post(endpoint, json=c_data_json_body, headers=headers) response.raise_for_status() print("wallet card added successfully: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to add wallet card:") print(f"error: {e}") if response: print("response body:", response.text) running the application once the four steps described above are implemented, open the sample project and do the following: update the partner id, certificate id, and card id values in src/main.py with your actual credentials. replace the partner.crt, samsung.crt and private_key.pem files with your credential files in the /cert directory. install all dependencies listed in the requirements.txt file using command pip install -r requirements.txt. run the main script using the command python src/main.py in the terminal. after successful execution of the requests, you will get a success message. get the full response code in the response section of the documentation. a push notification is sent to the user’s device to confirm the successful card registration. once this is done, open your samsung wallet and navigate to the coupon card list and you will find the card there. conclusion now that you have familiarized yourself with the process of adding cards to the user device using the adding wallet cards api, you can implement this logic to your server and use it to improve your card management. additional resources for more information on this topic, consult the following resources. complete source code create samsung wallet card templates using the server api official samsung wallet api documentation
M. A. Hasan Molla
tutorials
blogsamsung wallet partners can create and update card templates to meet their business needs through the wallet partners portal. however, if the partner has a large number of cards, it can become difficult to manage them using the wallet partners portal website. to provide partners with more flexibility, samsung provides server apis so that partners can easily create and modify samsung wallet card templates without using the wallet partners portal. with these apis, partners can also create their own user interface (ui) or dashboard to manage their cards. in this article, we implement the add wallet card templates api to create a card template for a coupon in the wallet partners portal. we focus on the api implementation only and do not create a ui for card management. prerequisites if you are new to samsung wallet, complete the onboarding process and get the necessary certificates. as a samsung wallet partner, you need permission to use this api. only authorized partners are allowed to create wallet card templates using this api. you can reach out to samsung developer support for further assistance. api overview the rest api discussed in this article provides an interface to add wallet card templates directly from the partner's server. this api utilizes a base url, specific headers, and a well-structured body to ensure seamless integration. url: this is the endpoint where the request is sent to create a new wallet card template. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template headers: the information provided in the headers ensures secure communication between the partner's server and samsung's server. authorization: the bearer token. see the json web token documentation for details. x-smcs-partner-id: this is your partner id. the partner id gives you permission to use the api. x-request-id: use a randomly generated uuid string in this field. body: the body must be in the jwt token format. convert the payload data (card template in json format) into a jwt token. for more details about the api, refer to the documentation. implementation of the api to create a card template the add wallet card templates api allows you to add a new card template to the wallet partners portal. you can also create the card in the portal directly, but this api generates a new card template from your server, without requiring you to launch the wallet partners portal. follow these steps to add a new card template. step 1: extracting the keys extract the following keys from the certificates. these keys are used while generating the jwt token. rsapublickey partnerpublickey = (rsapublickey) readpublickey("partner.crt"); rsapublickey samsungpublickey = (rsapublickey) readpublickey("samsung.crt"); privatekey partnerprivatekey = readprivatekey("private_key.pem"); extracting the public keys use the following code to extract the partner public key and the samsung public key from the partner.crt and samsung.crt certificate files, respectively. you received these certificate files during the onboarding process. private static publickey readpublickey(string filename) throws exception { // load the certificate file from resources classpathresource resource = new classpathresource(filename); try (inputstream in = resource.getinputstream()) { certificatefactory certfactory = certificatefactory.getinstance("x.509"); x509certificate certificate = (x509certificate) certfactory.generatecertificate(in); return certificate.getpublickey(); } } extracting the private key the following code extracts the private key from the .pem file you generated during the onboarding process. this key is needed to build the auth token. private static privatekey readprivatekey(string filename) throws exception { string key = new string(files.readallbytes(new classpathresource(filename).getfile().topath())); key = key.replace("-----begin private key-----", "").replace("-----end private key-----", "").replaceall("\\s", ""); byte[] keybytes = base64.getdecoder().decode(key); keyfactory keyfactory = keyfactory.getinstance("rsa"); return keyfactory.generateprivate(new pkcs8encodedkeyspec(keybytes)); } step 2: generating the authorization token samsung's server checks the authorization token of the api request to ensure the request is from an authorized partner. the authorization token is in the jwt format. follow these steps to create an authorization token: building the auth header create an authheader. set “auth” as its payload content type to mark it as an authorization token. as you can create multiple certificates, use the corresponding certificate id of the certificate that you use in the project. you can get the certificate id from “my account > encryption management” of the wallet partners portal. // create auth header jsonobject authheader = new jsonobject(); authheader.put("cty", "auth"); authheader.put("ver", 3); authheader.put("certificateid", certificateid); authheader.put("partnerid", partnerid); authheader.put("utc", utctimestamp); authheader.put("alg", "rs256"); creating the payload create the payload using the authheader. follow this code snippet to create the payload. // create auth payload jsonobject authpayload = new jsonobject(); authpayload.put("api", new jsonobject().put("method", "post").put("path", "/partner/v1/card/template")); authpayload.put("refid", uuid.randomuuid().tostring()); building the auth token finally, generate the authorization token. for more details, refer to the “authorization token” section of the security page private static string generateauthtoken(string partnerid, string certificateid, long utctimestamp, privatekey privatekey) throws exception { // create auth header // create auth payload // return auth token return jwts.builder() .setheader(authheader.tomap()) .setpayload(authpayload.tostring()) .signwith(privatekey, signaturealgorithm.rs256) .compact(); } step 3: generating a payload object token the request body contains a parameter named “ctemplate” which is a jwt token. follow these steps to create the “ctemplate.” creating the card template object select the proper card template you want to create from the card specs documentation. get the payload object as json format. now create the jsonobject from the json file using the following code snippet. // creating card template object jsonobject cdatapayload = new jsonobject(); cdatapayload.put("cardtemplate", new jsonobject() .put("prtnrid", partnerid) .put("title", "sample card") .put("countrycode", "kr") .put("cardtype", "coupon") .put("subtype", "others") .put("saveinserveryn", "y")); generating the jwe token create the jwe token using the following code snippet. for more details about the jwe format, refer to the “card data token” section of the security page. // jwe payload generation encryptionmethod jweenc = encryptionmethod.a128gcm; jwealgorithm jwealg = jwealgorithm.rsa1_5; jweheader jweheader = new jweheader.builder(jwealg, jweenc).build(); rsaencrypter encryptor = new rsaencrypter((rsapublickey) samsungpublickey); jweobject jwe = new jweobject(jweheader, new payload(string.valueof(cdatapayload))); try { jwe.encrypt(encryptor); } catch (joseexception e) { e.printstacktrace(); } string payload = jwe.serialize(); building the jws header next, follow this code snippet to build the jws header. set “card” as the payload content type in this header. // jws header jwsheader jwsheader = new jwsheader.builder(jwsalgorithm.rs256) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", 3) .customparam("certificateid", certificateid) .customparam("utc", utctimestamp) .build(); building the jws token generate the jws token from the previously generated jwe token and, finally, get the “ctemplate” jwt. follow the “jws format” section of the security page. private static string generatecdatatoken(string partnerid, publickey partnerpublickey, publickey samsungpublickey, privatekey partnerprivatekey, string certificateid, long utctimestamp) throws exception { // creating card template object // jwe payload generation // jws header // jws token generation jwsobject jwsobj = new jwsobject(jwsheader, new payload(payload)); rsakey rsajwk = new rsakey.builder((rsapublickey) partnerpublickey) .privatekey(partnerprivatekey) .build(); jwssigner signer = new rsassasigner( ); jwsobj.sign(signer); return jwsobj.serialize(); } step 4: building the request as all of the required fields to create the request have been generated, you can now create the request to add a new template. follow the code snippet to generate the request. private static request buildrequest(string endpoint, string partnerid, string requestid, string authtoken, string cdatatoken) { // prepare json body jsonobject cdatajsonbody = new jsonobject(); cdatajsonbody.put("ctemplate", cdatatoken); requestbody requestbody = requestbody.create( mediatype.parse("application/json; charset=utf-8"), cdatajsonbody.tostring() ); // build http request request request = new request.builder() .url(endpoint) .post(requestbody) .addheader("authorization", "bearer " + authtoken) .addheader("x-smcs-partner-id", partnerid) .addheader("x-request-id", requestid) .addheader("x-smcs-cc2", "kr") .addheader("content-type", "application/json") .build(); return request; } step 5: executing the request if the request is successful, a new card is added to the wallet partners portal and its “cardid” value is returned as a response. private static void executerequest(request request) { // execute http request try (response response = client.newcall(request).execute()) { if (response.issuccessful()) { system.out.println("wallet card template added successfully: " + response.body().string()); } else { system.out.println("failed to add wallet card template: " + response.body().string()); } } } implement as a server at this point, you can add a webpage ui for creating card templates and deploy it as a web service. in this sample project, there is no ui added. but, you can deploy this sample as a web service and test it. conclusion this tutorial shows you how you can create a new samsung wallet card template directly from your server by using a rest api. now that you can implement the api, you can add a ui and make it more user-friendly. also implement the updating wallet cards templates api for better card management. references for additional information on this topic, refer to the resources below: sample project code. business support for special purposes documentation.
M. A. Hasan Molla
tutorials
blogsamsung wallet provides powerful tools for partners to engage with their users and improve the user experience. push notification is one of these features, allowing partners to send customized notifications to their users. but before they can do that, partners need to create a notification template and receive approval for it from samsung. partners can create individual notification templates from the wallet partners portal. as a partner, if you need to create a large number of card notifications, the adding notification templates server api comes in handy. in the example scenario in this blog, we create a notification template from a partner's server using the adding notification template api. system requirements the adding notification template api has the following prerequisites: complete the onboarding procedure to obtain the required security certificates if you are new to samsung wallet, and create your wallet card. get permission from samsung to use the adding notification template api as explicit permission is needed. reach out to samsung developer support for further assistance. api fundamentals to create a notification template, you need to handle an http post request which contains the endpoint, headers, and a body. for a successful execution of the api, you need to follow the following specification. endpoint: use the following url as endpoint. url https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{card id}/notification headers: to ensure secure communication between the samsung server and the partner server, implement the following headers. authorization: bearer token for authentication. for details, follow rest api authorization token. x-smcs-partner-id: use the samsung wallet partner id. x-request-id: a unique uuid string that identifies each request. body: contains detailed template data in the jwt token format. see the adding notification templates for a detailed api specification. api implementation the steps below show how to implement the adding notification template api. for a better understanding of the implementation process, download the sample source code. certificate management the keymanager class is a static utility class that provides methods for loading cryptographic keys from files. this separation of concerns ensures that certificate handling logic is isolated and reusable. loading public keys from certificate files first, you need to load rsa public certificates from x.509 certificate files. the getpublickeyrsa() method loads rsa public keys from the partner.crt and samsung.crt files you received during the onboarding process. if the certificate doesn't contain an rsa key, this method raises an exception. public static rsa getpublickeyrsa(string certpath) { try { var cert = new x509certificate2(certpath); return cert.getrsapublickey() ?? throw new invalidoperationexception("certificate does not contain rsa public key"); } catch (exception ex) { throw new invalidoperationexception($"failed to load certificate: {ex.message}", ex); } } loading private keys from a pem file the getprivatekeyrsa() method loads an rsa private key from a pem file. this is used to generate jwt tokens. public static rsa getprivatekeyrsa(string pempath) { try { string keydata = file.readalltext(pempath); // remove pem headers and whitespace keydata = keydata.replace("-----begin private key-----", "") .replace("-----end private key-----", "") .replace("-----begin rsa private key-----", "") .replace("-----end rsa private key-----", "") .replace("\n", "") .replace("\r", "") .trim(); byte[] keybytes = convert.frombase64string(keydata); var rsa = rsa.create(); rsa.importpkcs8privatekey(keybytes, out _); return rsa; } catch (exception ex) { console.writeline($"failed to load private key from {pempath}: {ex.message}"); return null; } } token generation the tokengenerator class is the heart of the implementation, responsible for creating secure tokens using cryptographic techniques. constructor and properties the class stores all necessary cryptographic keys and identifiers. private string _partnerid = ""; private string _certificateid = ""; private readonly rsa _samsungpublickey; private readonly rsa _partnerpublickey; private readonly rsa _partnerprivatekey; public tokengenerator(string partnerid, string certificateid, rsa samsungpublickey, rsa partnerpublickey, rsa partnerprivatekey) { _partnerid = partnerid; _certificateid = certificateid; _samsungpublickey = samsungpublickey; _partnerpublickey = partnerpublickey; _partnerprivatekey = partnerprivatekey; } generating an authentication token an authentication token proves that your request to samsung's server is legitimate. it contains the following: the api method and path being accessed. var authpayload = new dictionary<string, object> { ["api"] = new dictionary<string, string> { ["method"] = "post", ["path"] = $"/partner/v1/card/template/{cardid}/notification" } }; timestamp and other metadata like certificate id. retrieve this metadata from my account > encryption management in the wallet partners portal. a digital signature that verifies the sender's identity. the token is used in the authorization header of the http request. public string generateauthtoken(dictionary<string, object> authpayload, string contenttype_auth) { string datastr = jsonserializer.serialize(authpayload); string authtoken = signjws(datastr, contenttype_auth); return authtoken; } generating a notification template token next, generate the jwt token for notification template data (ntemplate). it is recommended to generate this token after a user action. for details about the jwt format, follow card data token (cdata). preparing a notification template define the notification template according to the following code snippet. define your message details and message type here. get details about the template fields from the “[request]” section of the adding notification templates documentation. var notificationtemplate = new { type = "m", messagetype = "m", messagedetails = new[] { new { languagecode = "en", message = "sample merchant push notification message." } }, forcesaveyn = "n" }; noteuse forcesaveyn = “y”, if you want to save the template even if the message is detected as harmful. if your message is detected as harmful, your template can be rejected by samsung. the default value of the forcesaveyn property is “n”. implementing encryption (jwe) the notification template data or payload is encrypted using the samsung public key and this encrypted payload is used for signing. public string generatecdata(string payloaddata, string notification) { string jwetokenstring = jwt.encode(payloaddata, _samsungpublickey, jwealgorithm.rsa1_5, jweencryption.a128gcm); string jwttokenstring = signjws(jwetokenstring, notification); return jwttokenstring; } implementing jws signing the encrypted jwe token is then signed with the partner's private key. this signature proves the token originated from a legitimate partner. samsung can verify this signature using the partner's public key. noteuse auth as the content type when signing an auth token and use notification as the content type when signing the notification template data. private string signjws(string payload, string contenttype) { try { // create header var header = new dictionary<string, object> { ["alg"] = "rs256", ["cty"] = contenttype, ["partnerid"] = _partnerid, ["ver"] = 3, ["certificateid"] = _certificateid, ["utc"] = datetimeoffset.utcnow.tounixtimemilliseconds() }; return jwt.encode(payload, _partnerprivatekey, jwsalgorithm.rs256, header); } catch (exception ex) { throw new invalidoperationexception($"jws signing failed: {ex.message}", ex); } } building and executing the post request the next stage of the process is to construct the http post request to generate a new notification. client.defaultrequestheaders.clear(); client.defaultrequestheaders.add("authorization", $"bearer {authtoken}"); client.defaultrequestheaders.add("x-smcs-partner-id", partnerid); client.defaultrequestheaders.add("x-request-id", requestid); try { httpresponsemessage response = await client.postasync(endpoint, content); response.ensuresuccessstatuscode(); string responsecontent = await response.content.readasstringasync(); console.writeline("successfully generated notification template: " + responsecontent); } catch (httprequestexception e) { console.writeline("failed to generate notification template: " + e.message); } catch (exception e) { console.writeline("unexpected error during http request: " + e.message); } running the sample application once you are done with the above steps, open the sample project and do the following: update the partnerid, cardid, and certificateid values in the src/program.cs file with your actual values. place your partner.crt, samsung.crt and private_key.pem files in the /cert directory. navigate to the src directory, then build and run the project. find the details for responses and errors from the [response] section of the documentation. # build the project dotnet build # run the application dotnet run conclusion now that you know how to create a new notification template using the adding notification template api, you can implement it with your server if you need to generate a larger number of notification templates at once. additional resources for more information on this topic, consult the following resources: download the complete source code official samsung wallet api documentation send push notifications to samsung wallet users using the send notification api blog
M. A. Hasan Molla
tutorials
blogintroduction smartphones have become an essential part of our everyday lives. users are continually searching for more convenient ways to perform their tasks on their smartphones, driving them toward services with greater usability. as smartphones advance, our lives become simpler. galaxy users have completely embraced the convenience of paying with samsung pay, and no longer carry physical payment cards. this led to the evolution of samsung pay into samsung wallet, incorporating biometric-authentication-based security solutions and adding various features to replace conventional wallets. since june 2022, samsung wallet has been expanding its service area based on the existing samsung pay launching countries. this article aims to introduce samsung wallet and guide you through the integration process of the "add to samsung wallet" feature, which allows you to digitize various content and offer them as wallet cards. notice this article introduces non-payment service cards. if you want to learn more about the payment service of samsung wallet, visit the samsung pay page. you can get information on online payment services such as in-app payments, web checkout, and w3c payments. add to samsung wallet service let's delve deeper into the "add to samsung wallet" feature. digitized content registered in samsung wallet comes in the form of cards called wallet cards. registering a wallet card is effortless: simply click the "add to samsung wallet" button, and the card is stored securely on users’ galaxy smartphones. "add to samsung wallet" button and wallet card notice the benefits of using wallet cards can be found in the commercial video forgetting can be awesome. wallet cards the "add to samsung wallet" service is an open platform that supports offering various types of content such as wallet cards. we are streamlining service integration with content providers across different regions and adding useful features. boarding pass event ticket loyalty gift card coupon id card generic card pay as you go (in progress) reservation (in progress) digital key (in progress) notice generic card supports unstructured forms of cards. be a samsung wallet partner partner onboarding to begin offering content through samsung wallet, you must first register as a partner on the samsung wallet partner portal. the integration process is detailed on the samsung developer portal. to join the samsung wallet partner portal, create a samsung account that is used as the service administrator. wallet card management once enrolled, you can create service cards on the wallet cards menu. each card is assigned a card id representing the service, and you can set the card type and linking information. you can manage cards according to their status – test or live. configuring wallet card notice after completing all required forms for the wallet card, click the launch button to request card activation. before providing the service to actual users, remember to turn off the 'test mode.' how to safely secure user data key generation and certificate request the registration process includes certificate exchange to securely transmit service data. refer to the diagram and developer guide, security key & certificate creation guide, to complete the certificate registration and partner enrollment smoothly. certificates exchange process ensuring data security to prevent forgery and leakage of user card data, secure tokenization processing is required. json web token (jwt), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. in particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used. process of generating and verifying security tokens notice depending on how partners provide content services to users, you can choose how to deliver data to the samsung wallet service. two ways to transfer wallet card data add to samsung wallet interface provides two methods for partners to deliver users digital content as wallet cards. data transmit link the general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the samsung wallet service when the user clicks the button. as long as samsung wallet support is confirmed, you can generate a link containing the user's card data and configure the "add to samsung wallet" button to run the link when pressed, either on an application or web page. data transmit process data fetch link another method to transfer wallet card data is to include only the refid, which represents the user's content, in the "add to samsung wallet" link and transmit it to the samsung wallet service. when a user clicks the "add to samsung wallet" button, samsung servers refer to the get card data api information set on the wallet card and retrieve user content using the received refid to complete registration. data fetch process this method is suitable for providing user's data through email or mms messages where static links cannot be avoided. there is an option to secure these static links. data fetch process for static links setting up data synchronization on the partner portal, you can set up the wallet card information and configure the server interaction api that the content provider needs to prepare. this api is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on samsung wallet. register wallet cards when a user card is added to samsung wallet, samsung wallet servers use the send card state api to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with samsung wallet. when a wallet card is registered, added event is sent to the partner's server update wallet cards changes to the synchronization target content can be notified to the samsung wallet service through the update notification api. here, the value that distinguishes each piece of content is the refid that the partner must provide when registering the users’ wallet card. through the get card data api, samsung wallet servers can check the latest content information any time. if updates occur on the partner's side, updated event notifications should be sent to the samsung server in case users withdraw content from the partner's side in case users delete cards from samsung wallet notice both servers should verify requests using the authorization header of the api request. this authorization token is in jwt format, familiar from card data security. effortless wallet card registration with just one click this feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or mms message. various service channels javascript library for web developers we provide a javascript library and a user guide, implement the button, to help integrate your web pages. creating buttons and links in your app for configuring buttons in applications, utilize the button image resources. providing services via mms, email, or qr codes to provide services through fixed links, check out the details of the data fetch link. these static links can also be used by scanning qr codes. experience the service and practice you can experience service integration development using the codelab and use the testing tool to preregister the wallet cards created on the partner portal, which could be helpful. conclusion we've looked at how to provide digital content through the "add to samsung wallet" feature. we continuously update the guides on the developer portal, so please refer to them when preparing for integration. summary the "add to samsung wallet" service welcomes participation from content service partners and developers. for inquiries or technical support, please contact us through the form provided on the developer portal. i hope this post has been helpful, and now i'll conclude my writing here. thank you. this post was written based on the sdc23 korea session.
Choi, Jonghwa
Develop Samsung Wallet
docapi index use this chapter for lookup after you understand the integration flow contract-bearing api details remain in their task chapters and are indexed here to avoid maintaining duplicate definitions the direction column identifies which system receives the request confirm the required authentication and endpoint configuration in the linked definition interface direction primary purpose definition get card data samsung → partner resolve or refresh a card instance from the partner system get card data send card state send card event samsung → partner report add, update, deletion and provisioning events send card state request action samsung → partner execute an approved action data flow request action update notification partner → samsung notify samsung wallet that one card instance must be refreshed update notification cancel notification partner → samsung cancel card instances associated with the specified scope cancel notification template management apis partner → samsung create, update and retrieve templates programmatically template management apis server-initiated provisioning partner → samsung initiate card provisioning for a resolved user account adding wallet card apis pushed card update partner → samsung push an update to wallet cards already added to samsung wallet pushed updating wallet card api check service availability partner → samsung check whether samsung wallet service is available for a device and country check service availability user-facing atw url formats are defined separately in add card links
Develop Samsung Wallet
docserver-initiated card provisioning this subsection defines the server-initiated flow for adding wallet cards and how samsung wallet determines which user to register the card to based on the account object embedded in the card payload high-level flow partner backend prepares the wallet card payload card + optional account and required metadata the card payload is securely tokenized using jwt and supplied in the cdata body parameter when calling the server add api post /atw/v1/cards/{cardid} samsung wallet receives and validates the request, then inspects the account object to determine the target user if a push notification is required by policy or template configuration, samsung wallet sends a push to the resolved device/account the card is registered to the resolved user/device and the card instance lifecycle starts account object & user resolution when present, the account object is conditional but, if provided, is used to identify the target recipient of the server-initiated card the account object structure from the payload is "account" { "type" "phonenumber", // e g phonenumber, email, etc "value" "+821012345678" } the account type values supported and their meaning are type requires additional configuration description email x email address registered with samsung account e g , test@google com phonenumber x phone number registered with samsung account on e g , +821012345678 extpmid o partner-specific user identifier issued by payment service pmid o partner-specific user identifier issued by wallet service dmid o user device identifier issued and managed internally by samsung wallet since this value is not disclosed to partners, external partners generally have no legitimate way to obtain a valid dmid, making this option impractical for normal partner integrations said o samsung account identifier ci o identification value for distinguishing korean users resolution logic if account type is email or phonenumber, samsung wallet attempts to locate the samsung account matching that value and deliver/register the card against that account if account type is one of the optional identifiers extpmid, pmid, dmid, said, ci , samsung wallet will use partner-specific mappings and preconfigured integrations partner portal configuration / agreements to resolve the target user or device these modes may require prior coordination or additional configuration from the partner if account is omitted or cannot be resolved, samsung wallet follows the fallback policy specified by the template / partner configuration for example, rejecting the request, logging for manual reconciliation, or requiring a different delivery flow such as data-fetch policy specifics depend on partner onboarding and template settings in the partner portal security and operational requirements all card payloads must be jwt-tokenized and calls authenticated see chapter 3 partners must ensure the account value is normalized e g , e 164 for phone numbers and matches the samsung account data format expected by wallet use of optional account types extpmid/pmid/dmid/said/ci requires prior configuration in the partner portal and, where applicable, contractual/technical setup per onboarding guidance adding wallet card apis a wallet card is typically added after user interaction, such as selecting the add to wallet button or link this api also supports automatically adding a wallet card for special-purpose use cases, with the 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 card registration is confirmed when the card state is updated to added through send card state send card event an administrator must grant permission for partners to use this api card data specification card id {cardid} 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 serialized as a jws-wrapped jwe token, not a plain jwt see the security chapter for details request type value description method post url /atw/v1/cards/{cardid} for requests targeting the kr region, prepend kr/ to the path e g , /kr/atw/v1/cards/{cardid} headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials> * see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required wallet card identifier granted through the partner portal body parameters cdataobject 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 card data token cdata for more details payload object cardobject required wallet card object * see card object for structure and field definitions accountobject conditional user account object account typestring 16 required type of user identifier, e g phonenumber, email * see account object and user resolution account valuestring 64 required user identifier example card object { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "updatedat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https //{base-url}/main png" // add the required attributes for the selected card type and subtype }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678" } } example post /atw/v1/cards/1656147182764415319 [headers] authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 payload { "cdata" "<cdata_serialized>" } [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 pushed updating wallet card api this api allows partners to push an update to a wallet card that has already been added to samsung wallet samsung wallet applies the update to the existing wallet card instance s identified by each data[] refid under {cardid} if no wallet card matching a given refid exists, the update for that entry fails an administrator must grant permission for partners to use this api request type value description method post url /atw/v1/cards/{cardid}/updates for requests targeting the kr region, prepend kr/ to the path e g , /kr/atw/v1/cards/{cardid}/updates headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials> * see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required wallet card identifier granted through the partner portal body parameters cdataobject 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 card data token cdata for more details payload object cardobject required wallet card object containing the updated data * see card object for structure and field definitions * data[] refid identifies the existing wallet card instance s to update example post /atw/v1/cards/1656147182764415319/updates [headers] authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140004 payload { "cdata" "<cdata_serialized>" } [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 due to something that is perceived to be a client error, including when no wallet card matching refid exists 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request
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
doctemplate management api this subsection defines apis and governance rules for managing wallet card templates a wallet card template represents the structural and operational definition of a wallet card service it defines the card type and subtype design configuration operational flags and policies lifecycle state template lifecycle wallet card templates operate under a controlled lifecycle model each template transitions through defined states before it becomes eligible for issuing wallet card instances typical lifecycle states include status description draft initial state when a card is first created all fields and settings are fully editable verifying verification process by samsung administrators requires completion of general information and csr certificate signing request registration * see key & certificate lifecycle certificate-based onboarding rejected card did not pass verification rejection reasons are emailed to the partner cards can be revised and resubmitted active card has been approved and is now visible to users activation is final and cannot be undone blocked card has been blocked by samsung administrator-only action templates must reach an appropriate operational state before wallet card instances can be issued base template requirement before issuing any wallet card instance, a base template must be created the base template serves as the structural foundation for the associated wallet card type and defines its operational configuration card management tools wallet card templates and instances can be managed using the following tools wallet partners portal intended for managing individual templates or smaller batches provides a user interface for lifecycle management, status updates, and administrative review server api access designed for partners managing high volumes of wallet cards supports automation and scalable integration templates and cards created via api remain visible and manageable in the samsung wallet partners portal testing mode when a wallet card template is first created, it is automatically placed in testing mode in testing mode, the wallet card is not publicly available to end users testing mode must be manually disabled after validation is complete once testing mode is turned off, it cannot be re-enabled testing mode must be disabled before official deployment template management apis after successful onboarding, partners can create and manage wallet card templates and issue wallet card instances to samsung wallet the card template management interfaces provide apis to add wallet card templates update wallet card templates retrieve wallet card templates these apis define and manage the configuration under which wallet card instances are created once a template is properly configured, authorised partners may add wallet cards to users directly from the partner server using the adding wallet cards process a wallet card template may require administrative approval before it transitions to the active state and becomes eligible for issuing wallet card instances service domain environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card template this section describes how to create a wallet card templates in samsung wallet [request] type value description method post url /partner/v1/card/template header authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials>* see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string payload ctemplatestring required actual payload data in basic json format to establish the communication between partners and samsung wallet * see template specsthis must be in the secure jwt json web token format * see card data token cdata section for more details example post /partner/v1/card/template /*[headers]*/ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 payload { "ctemplate" "<jwt_serialized>" } [response] type value description http status 200 ok payload cardidstring 32 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 template wallet card templates 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/{cardid} headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials> * see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template payload ctemplateobject required actual payload data in basic json format to establish the communication between partners and samsung wallet * see template specsthis must be in the secure jwt json web token format * see card data token cdata section for more details [response] type value description http status 200 ok payload cardidstring 32 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 get wallet card template retrieve one wallet card template created through the api by its wallet card id cardid [request] type value description method get url /partner/v1/card/template/{cardid} headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials>* see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cardidstring 32 required wallet card identifier issued through the partner portal get /partner/v1/card/template/3hdpejr6qi380 authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok payload templateobject required wallet card template object { "resultcode" "0", "resultmessage" "success", "template" { "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" null, "privacymodeyn" "n", "sharebuttonexposureyn" "y", "state" "verifying", "applogoimg" "", "desc" "" } } [result] http status code description 200 200 ok 400 400 bad request 401 401 unauthorized — the authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable get wallet card templates wallet card templates created through the api can be retrieved via the template list api and are also visible and manageable through the wallet partners portal partners can view and manage all wallet card templates they have created results can be paged with the offset and limit query parameters if both are omitted, the api returns the full list without paging metadata for backward compatibility [request] type value description method get url /partner/v1/card/templates headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme i e , bearer <credentials> * see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string query parameters offsetinteger optional zero-based start index default 0 must not be negative limitinteger optional number of items to return default 20; maximum 100 if offset and limit are both omitted, the full list is returned without paging metadata values outside 1–100 return 400 bad request wdt1n1002 get /partner/v1/card/templates?offset=0&limit=20 authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok payload templatesobject array required wallet card template object totalcountinteger optional total number of templates matching the request included only when offset or limit is supplied offsetinteger optional resolved offset value included only when offset or limit is supplied limitinteger optional resolved limit value included only when offset or limit is supplied example 200 ok { "resultcode" "0", "resultmessage" "success", "templates" [ { "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" null, "privacymodeyn" "n", "sharebuttonexposureyn" "y", "state" "verifying", "applogoimg" "", "desc" "" }, { "cardid" "3ctei2riqi9iq", "title" "wallet card title 02", "countrycode" "us", "cardtype" "generic", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" "", "privacymodeyn" "n", "state" "verifying", "category" "membership", "applogoimg" "", "desc" "ntf_us_generic" } ] } example paged { "resultcode" "0", "resultmessage" "success", "totalcount" 137, "offset" 0, "limit" 20, "templates" [{ "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "state" "verifying" }] } [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 template specs template attributes wallet card types wallet card type wallet card subtype boardingpass airlines, trains, buses, others ticket performances, sports, movies, entrances, others coupon others giftcard others loyalty others idcard employees, nationals, students, drivers, guests, others digitalkey doors, hotels, cars, others payasyougo evcharges, others generic others reservation rentalcars, restaurants, accommodations, etickets, taxis, activities, others transitcard others clip businesstrips, trips, others wallet card templates attributes type value description payload cardtemplateobject required wallet card template object cardtemplate titlestring 32 conditional wallet card name* required when adding wallet card template cardtemplate countrycodestring 2 conditional the main headquarters location * required when adding wallet card template cardtemplate cardtypestring 100 conditional this value is set to cardtype * required when adding wallet card template cardtemplate subtypestring 100 conditional this value is set to subtype * required when adding wallet card template cardtemplate designtypestring 100 optional the value that defines the design type of the wallet card * for generic templates i e , when cardtype is set to generic , set designtype to one of the following values "generic 01", "generic 02", or "generic 03" * default "generic 01" cardtemplate prtnrapppckgnamestring 128 optional the application package name cardtemplate applogoimgstring 200 optional the banner logo image url cardtemplate nonetworksupportynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureynstring 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate prtnrcarddatastring 1000 optional partner url for the get card data endpoint implement the endpoint according to the referenced api contract example https //{yourdomain} cardtemplate prtnrcardstatestring 1000 optional partner url for the send card state send card event endpoint implement the endpoint according to the referenced api contract example https //{yourdomain} cardtemplate statestring 15 optional wallet card's state * default 'draft' cardtemplate testingmodeoffstring 1 optional testmode off this must be set to either 'y' or 'n' * default ‘n’ * available only when updating templates cardtemplate saveinserverynstring 2 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate categorystring 20 optional select from the following values “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others” * this field is applicable only to generic card templates i e , when cardtype is set to generic cardtemplate descstring 500 optional description cardtemplate layoutobject optional defines presentation rules for card data in samsung wallet this field is applicable only when the designtype is set to generic-{subtype}-default for detailed specifications, see the section layout specs examples boarding pass event ticket coupon gift card loyalty digital id pay as you go generic card layout specs this document provides detailed specifications for the layout field used when adding wallet card templates through the card management api it is intended to be referenced from the layout field description in adding wallet card template overview this section describes the specification of the layout field used when adding wallet card template the layout object defines presentation rules for card data in samsung wallet it does not contain display values directly instead, it references card data using attribute keys layout object structure the layout object consists of three sections header primary auxiliary each section defines a layout preset and a list of entry mappings type value description layout object layoutobject optional defines presentation rules for card data in samsung wallet layout headerobject required defines the header area of the card layout header presetstring 10 required header layout preset allowed values logo, logotext, text layout header entries[]array of object required list of entry mappings that define how header ui slots reference card data layout header entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout header entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primaryobject required defines the primary content area of the card layout primary presetstring 20 required primary layout preset generic cards landscape, square, vertical, textonlyboarding pass threefields, fourfields, fivefields layout primary entries[]array of object required list of entry mappings that define how primary ui slots reference card data layout primary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout primary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primary useboardingtimeboolean optional controls which time is displayed on the boarding pass card • false default displays the departure time• true displays the boarding start timeapplies only when cardtype = boardingpass layout auxiliaryobject required defines additional information displayed when the card is expanded layout auxiliary presetstring 20 optional defines the number of fields to be displayed allowed values twofields, threefields, fourfields layout auxiliary entries[]array of object required ordered list of fields rendered as label–value pairs each value is an attribute key layout auxiliary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout auxiliary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value illustrative layout fragment not a complete json document { … "layout" { "header" { "preset" "logotext", "entries" [ { "entryname" "image_01", "entrykey" "providerlogo" }, { "entryname" "field_01", "entrykey" "providername" }, { "entryname" "subfield_01", "entrykey" "vehiclenumber" } ] }, "primary" { "preset" "square", "entries" [ { "entryname" "image_01", "entrykey" "wideimage" }, { "entryname" "field_01", "entrykey" "grade" }, { "entryname" "field_02", "entrykey" "seatclass" } ] }, "auxiliary" { "preset" "twofields", "entries" [ { "entryname" "field_01", "entrykey" "entrance" }, { "entryname" "field_02", "entrykey" "seatnumber" } ] } } } header – required entryname by preset preset required entryname description logo image_01, subfield_01 logo image with secondary text logotext image_01, field_01, subfield_01 logo image with primary and secondary text text field_01, subfield_01 primary and secondary text without image primary – required entryname by preset preset required entryname description landscape image_01 landscape image only square image_01, field_01, field_02 square image with two text fields vertical image_01, field_01, field_02 vertical image with two text fields textonly field_01 single text field without image primary / auxiliary – field-based presets preset required entryname description twofields field_01, field_02 displays two label–value pairs threefields field_01, field_02, field_03 displays three label–value pairs fourfields field_01, field_02, field_03, field_04 displays four label–value pairs fivefields field_01, field_02, field_03, field_04, field_05 displays five label–value pairs allowed where applicable data mapping layout → card data the layout object does not contain display values each field defined in layout references card data using an attribute key this section describes how attribute keys are resolved data resolution rule when a field is defined in layout, the value is resolved from the following locations in order card data[] attributes card data[] attributes extendedfields[] entrykey standard attribute mapping if the entrykey defined in layout matches a field inside card data[] attributes the value is resolved directly from that attribute example layout … "primary" { … “preset” "square", "entries" [ { "entryname" "field_01", "entrykey" "providername " }, … } … card data[] "attributes" { … "providername" "samsung wallet" … } extended fields mapping in addition to predefined attributes, layout fields may reference values inside extendedfields extendedfields is a user-defined data container that allows partners to define additional fields not included in the standard card specification extendedfields structure extendedfields resolution logic if the layout field key does not exist in predefined attributes the system searches attributes extendedfields[] entrykey when a matching entrykey is found value → resolved from extendedfields[] value label → resolved from extendedfields[] label example layout referencing extendedfields result gatenumber → value "a12", label "gate" boardingzone → value "3", label "zone" mapping priority if the same key exists in both predefined attributes extendedfields the resolution priority is attributes predefined fields extendedfields summary layout fields reference data by attribute key standard attributes are resolved first extendedfields enables user-defined data expansion layout does not directly contain display value
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
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
You have successfully updated your cookie preferences.