Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials
blogcard template management is a crucial task for partners in the samsung wallet ecosystem that is typically handled through the wallet partners portal. manually altering numerous existing templates via the web interface can be inefficient and challenging. samsung provides a set of server-side apis to address this, allowing partners to programmatically manage and modify their card templates for greater operational agility. using these apis enables partners to integrate update capabilities directly into their own ecosystems. this automation facilitates the seamless maintenance of card offerings, helping partners keep their content dynamic and up-to-date. as a partner, this article walks you through the implementation of the update wallet card template api specifically using python. if you are a java developer or want to implement the add wallet card template api, you can follow the previous content on creating samsung wallet card templates. noteto follow this article, you'll need an existing card template and its cardid. make sure you have completed the samsung wallet onboarding to obtain the necessary certificates. also, you need permission to use this api. only permitted partners can use this api. api overview this section details the rest api designed for modifying a pre-existing wallet card template, enabling direct updates from a partner's server. endpoint url: direct requests to modify a card template to the following url. it is imperative to substitute {cardid} with the identifier of the specific card template you intend to alter. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{cardid} request headers: secure interaction with this api is restricted to authenticated partners. the headers detailed below are vital for establishing a secure and validated communication channel with the samsung server. authorization: this field must contain the bearer token. for comprehensive information, consult the json web token documentation. x-smcs-partner-id: this field must be populated with your unique partner identifier. x-request-id: a universally unique identifier (uuid) is required here, freshly generated for each request. request body: the payload of the request needs to be structured as a json object. this object must include a key named ctemplate, with its value being a jwt token. this specific jwt securely contains the complete data for the revised card template. for a deeper dive into the api specifications, check the official documentation. implementing the api to create a card template the update wallet card template api enables partners to modify existing card templates in the wallet partners portal. in this section, we implement python code to update a coupon card template, for example, by changing its title. extracting the keys from certificates extract the public and private keys from the certificate files obtained during the onboarding process. def getpublickey(crt_path): """ extract publick 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 jwk.jwk.from_pem(public_key_pem) except exception as error: print(f"error reading public key from {crt_path}: {error}") return none def getprivatekey(pem_path): ''' extract private key from a .pem file. ''' try: with open(pem_path, "rb") as pem_data: private_key = serialization.load_pem_private_key( pem_data.read(), password = none, backend = default_backend() ) return private_key.private_bytes( encoding=serialization.encoding.pem, format=serialization.privateformat.pkcs8, encryption_algorithm=serialization.noencryption() ) except exception as error: print(f"error reading private key from {pem_path}: {error}") return none generating the authorization token the samsung server uses a jwt format token to verify if the request is from an authorized partner. follow these steps to create an authorization token. create an authorization token header. set the payload content type to ‘auth’ since this is an authorization token. create the payload using the authorization token header. generate the authorization token. the following code snippet demonstrates these steps. 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"/partner/v1/card/template/{cardid}" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token generating a payload object token the request body includes a parameter named ctemplate, which is also a jwt token. create the jwt token using the following code snippet. 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 building and executing the request build and send the http request to the specified update endpoint. add all fields that you want to modify in the ’cdatapayload’ object. refer to the documentation to identify the fields that you can modify. def main(partnerid, cardid, certificateid, utctimestamp, requestid, endpoint): partnerpublickey = getpublickey("../cert/partner.crt") print(f"partnerpublickey {partnerpublickey}") samsungpublickey = getpublickey("../cert/samsung.crt") print(f"samsungpublickey {samsungpublickey}\n") partnerprivatekey = getprivatekey("../cert/private_key.pem") print(f"partnerprivatekey {partnerprivatekey}\n") authtoken = generateauthtoken(partnerid, certificateid, utctimestamp, partnerprivatekey, cardid) print(f"authtoken {authtoken}\n") cdatapayload = {} # --- add data here that you want to update. cdatapayload["cardtemplate"] = { "title": "update card tile", "countrycode": "kr", "saveinserveryn": "y" } data = json.dumps(cdatapayload).encode('utf-8') cdatatoken = generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data) print(f"cdatatoken: \n{cdatatoken}\n") # --- prepare json body (python dictionary) --- c_data_json_body = { "ctemplate": cdatatoken } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "x-smcs-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 template updated successfully: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to update wallet card template:") print(f"error: {e}") if response: print("response body:", response.text) running the application download the sample project and open it with any ide, then follow this process. configure: update ‘partner_id’, ‘certificate_id’, and, crucially, ‘card_id_to_update’ in src/main.py with your actual credentials and the id of the card you need to modify. place certificates: ensure your partner.crt, samsung.crt and private_key.pem files are in the cert/ directory. install dependencies: install all the required dependencies from the requirements.txt file. pip install -r requirements.txt execute: run the main script from the terminal. python src/main.py if the request is successful, the specified card template in the wallet partners portal is updated. the api returns the updated card id with a success status, otherwise it returns an error. find all the status codes in the '[result]' section of the documentation. wallet card template updated successfully: { "cardid": "cardid", "resultcode": "0", "resultmessage": "update_success" } conclusion by implementing the api to update an existing samsung wallet card template through this article, you can now automate and streamline the management of your card templates, ensuring that they always reflect the latest information. references for additional information on this topic, refer to the resources below. sample project code create samsung wallet card templates using the server api business support for special purposes 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
Develop Samsung Wallet
doccard management api guidelines once your service is successfully onboarded, you gain the ability to design and deploy custom digital assets—such as boarding passes, coupons, tickets, and more—directly to samsung wallet the adding samsung wallet card templates section defines interfaces for providers to conveniently create wallet cards in samsung wallet the generated wallet card templates can be updated by following the instructions on the updating wallet card templates section authorized partners can add wallet cards to users directly from the partner server by following the instructions on the adding wallet cards section below service domain environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card templates this section describes how to create a wallet card in samsung wallet [request] type value description method post url /partner/v1/card/template headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id unique value for each template created by a partner this value is set to a number of 19 digits or less cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 required the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate cardtype string 100 required template card type for details, refer to wallet cards cardtemplate subtype string 100 required template card sub type for details, refer to wallet cards cardtemplate designtype string 100 optional the value that defines the design type of the wallet card for details, refer to wallet cards cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of the image is 1024*1024 e g http //www yourdomain com/banner_logo_image png cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, the user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance, parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrcardstate string 1000 optional [get card state] partner url check the url format below and implement api according to url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional when creating a card, you can transition the card's state from “draft” to “verifying” you can only choose “draft” or “verifying” * default 'draft' cardtemplate desc string 500 optional description example /** example card template object **/ { "prtnrid" "4083254626439156160", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "cardtype" "coupon", "subtype" "others", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/] { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable updating wallet card templates wallet card 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/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate cardid string 32 required the cardid response received when creating a card cardtemplate templaterefid string 19 required partner template id the unique value for each template created by a partner this value is set to a number with 19 digits or less cardtemplate title string 32 optional wallet card name cardtemplate countrycode string 2 optional the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of that image is 1024*1024 cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomainn cardtemplate prtnrcardstate string 1000 optional partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional if the card status is “draft”, you can only select “verifying” cardtemplate testingmodeoff string 1 optional this value can be set only when the card status is active normal service is possible only when the testing mode is changed to off * default ‘n’ cardtemplate desc string 500 optional description [example] /* *example card template object **/ { "prtnrid" "4083254626439156160", "cardid" "3hdpejr6qi380", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template/cardid=3hdpejr6qi380 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable adding wallet cards a typical addition to the wallet card is triggered by user interaction, such as pressing the add to wallet button or link the api also supports adding a wallet card automatically to the user for a special purpose with user’s consent this api allows partners to provide wallet cards to users the request payload must contain information about the target to which the card is added this information may be related to the user’s account, or it may contain information about a card that is already registered a push notification is sent to the user’s device to confirm successful card registration the success of card registration must be determined that the card is registered normally when it is updated to added of send card state an administrator must grant permission for partners to use this api card data specification card id {card id} is an id issued when the partner manager signs up for partner services and register the wallet card they want to service refer to partner onboarding guide document for details cdata actual payload data in basic json format to establish the communication between partners and samsung wallet see the details in the table below card data token the specific wallet card data mentioned as cdata must be secured in jwt json web token format see a chapter security for details [request] type value description method post url /atw/v1/cards/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required wallet card identifier granted through the partner portal body parameters cdata object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object card object required wallet card object card type string 16 required wallet card type *see wallet cards card subtype string 16 required wallet card sub type *see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds *utc±00 00 data[] updatedat long 13 required data update timestamp epoch timestamp in milliseconds *utc±00 00 data[] language string 8 required default card language code e g en, ko data[] attributes object required attributes container data[] attributes {fields} required attributes fields by card type*see wallet cards data[] localization[] array of object optional localized language container *see wallet cards localization[] language string 8 required multilingual content language code, e g en, ko localization[] attributes {fields} for displaying a given language, ‘data[] attributes’ can be replaced by localized versions *see wallet cards account object conditional user account object account type string 16 required type of user identifier, e g phonenumber, email account value string 64 required user identifier [example] /** example card object **/ { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678” } } /** example **/ post /atw/v1/cards/1656147182764415319 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "cdata" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable
Develop Samsung Wallet
docmanage wallet card the samsung wallet partners portal provides partners with the necessary tools and functionality to integrate the “add to samsung wallet” feature into their services this guide outlines the process of registering, managing wallet cards, and ensuring that everything runs smoothly refer to the partner onboarding guide for the samsung wallet portal the partners need to complete the following steps to register and gain access to the samsung wallet portal note-wallet portal currently offers 'add to samsung wallet' functionality to the partners overall managing process once registered and logged into the samsung wallet portal, partners can follow the steps to manage wallet cards and monitor performance step 1 - create wallet cards templates begin by drafting the cards that will be added to samsung wallet these cards can include loyalty cards, tickets, boarding passes, and more draft status - initially, these cards will be in draft status until they are fully configured and ready for testing manage cards partners can manage all registered wallet cards this includes edit, update, and monitor the status of the wallet cards general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet folder contents testing mode all data generated in testing mode is periodically deleted be sure to turn off the "testing mode" setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name partner app package name partner application package name wallet card template pre-defined partner wallet card template partner get card data url for the partner api call to receive card data if the partner uses this api, enter the url otherwise leave it blank partner send card state url for the partner api call to send a card state notification if the partner uses this api, enter the url otherwise leave it blank samsung server ips samsung wallet server ips which need to be allowed by the partner’s firewall, separately described for inbound and outbound wearable wallet assistance whether to support the wearable wallet service support ‘no network’ status whether to support wallet card opening during the ‘no network’ status description description of the wallet card select template the samsung wallet portal offers various wallet card templates optimized for different use cases, including boarding passes, tickets, coupons, and digital ids to streamline your integration, you can easily select the appropriate template from the select wallet card template pop-up window steps to select wallet card template navigate to the select wallet card template option within the portal in the wallet card type drop-down menu, select the category that best suits your use case e g , boarding pass, ticket, coupon, or digital id once the card type is selected, a list of templates will appear in the wallet card sub type section choose one of the available templates from the list that corresponds to your selected card type after selecting the template, you can proceed with configuring the card’s details, including the branding, content, and data fields specific to the selected template samsung wallet supports various wallet card types designed to cater to different use cases each card type is optimized for specific functions, making it easier for partners to provide a seamless experience to users note-refer to section wallet card type to learn more about it view wallet cards partners can easily manage all their registered wallet cards through the samsung wallet portal this includes the ability to view, edit, and delete wallet cards as needed step 2 - launch wallet cards verifying status once a wallet card is ready for launch, it must go through the verifying status before it can be activated and made available to users partners can launch and activate their cards once they have been reviewed and approved, ensuring the card meets all requirements steps to launch wallet cards to begin the launch process, click yes to confirm and approve the activation of the wallet card to begin the activation process, click the launch button for the card you wish to activate once a card is launched, the button text changes to launched the activation cannot be cancelled after the card is launched, its status will change to verifying during this stage, the system will conduct a final review to ensure all information is accurate and meets the necessary requirements after verification, the card will undergo administrator approval the admin will review and approve the card for activation once the card is approved by the administrator, its status will change to active, making it available for users to add to their samsung wallet launch wallet cards rejected status if the wallet card is rejected after launching, you can modify the card and re-launch steps to modify the card and re-launch the administrator registers the reason for rejection when rejecting the launched wallet card it is sent to the partner by email from the system, including the reason for rejection partners can apply for launch again by checking the reason for rejection and modifying the wallet card information step 3 – testing mode partners can use the testing mode to test a wallet card internally before it is officially released to users this feature ensures that all aspects of the card, including its functionality and user experience, are working as expected when you create a new wallet card, the testing mode option is enabled by default, allowing you to perform internal tests without affecting user access all data generated during testing is periodically deleted to ensure that no test data remains in the system once testing is complete even though testing mode is enabled, the card is still visible and accessible in the system testing does not prevent the card from being exposed to users, so you can verify its functionality without any restrictions once testing is complete and you are satisfied with the card’s performance, be sure to turn off testing mode note-remember to change the status from testing mode on to testing mode off to finalize the testing process and prepare the card for official release step 4 - admin approval active status after a wallet card is launched, it must go through an administrator approval process before it becomes active and visible to users steps for admin approval once the launch button is clicked, the card’s status automatically changes to verifying during this stage, the card is reviewed for accuracy, completeness, and compliance with samsung wallet requirements note-please ensure that testing is completed using either your own implementation or the add to wallet test tool, as the samsung wallet administrator will verify the results through server-side test logs an administrator will review the submitted wallet card to ensure it meets all content and technical guidelines if the card passes the review, it is approved for activation upon administrator approval, the card status updates 'active' once the card reaches active status, it becomes visible and accessible to end users, enabling them to add it to their wallets step 5 – add to samsung wallet integration to integrate the "add to samsung wallet" feature into your system, you need to insert the appropriate "add to wallet" script this script is available for various platforms, including web, android, and email/mms, and each platform requires a slightly different implementation approach follow the steps below to successfully implement the "add to wallet" button create the tokenized card data, known as cdata, which contains the actual wallet card content note-since cdata has a time-to-live ttl of 30 seconds, it is recommended that the system generates cdata in real time to ensure it remains valid when processed the cdata format varies depending on the card type e g , loyalty card, ticket, coupon refer to the cdata generation sample code on the partners portal for detailed guidance copy the sample ‘add to wallet’ script from partners portal’s wallet card page replace the placeholder "cdata" in the script with your generated tokenized card data apply the script to your system see partners portal’s wallet card for details note-for "add to wallet" integration, you may need some base data you can find that and other necessary information on partners portal and wallet api spec you can also add image beacon in the script for tracking effect analysis add to wallet script guide wallet card types wallet card type boarding pass ideal for airlines, train services, or event check-ins allows users to add their travel or event tickets to samsung wallet for easy access and quick scanning wallet card type tickets designed for digital tickets to events such as concerts, movies, sports games, or other events ensures smooth entry by providing users with a digital copy of their ticket directly on their device wallet card type coupons perfect for promotional offers, discount vouchers, gift cards, or loyalty rewards users can redeem or use these coupons directly from their samsung wallet, making the process faster and more efficient wallet card type digital id used for membership cards, loyalty programs, and identification purposes can store digital versions of cards like gym memberships, library cards, or other forms of identification wallet card type gift card digital versions of physical gift cards, which users can add to their samsung wallet for quick and easy access useful for retail, online stores, and various gift card services wallet card type loyalty card designed for businesses offering loyalty programs where customers earn points for purchases or engagement users can view their point balance, check available rewards, and redeem points directly from their samsung wallet
Develop Samsung Wallet
docmanage wallet card refer to the partner onboarding guide for the samsung wallet portal the rp partner needs registration information on the wallet portal wallet portal currently offers 'verify with samsung wallet' functionality to the rp partners overall managing process the following image illustrates the process of managing samsung wallet cards create relaying party wallet card template partners can create and manage their wallet cards with this step-by-step guide manage wallet cards partners can manage all registered wallet cards partners can edit wallet cards and check their status general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the samsung wallet item description testing mode all data generated during testing mode is periodically deleted be sure to turn off the 'testing mode' setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name automatically generated partner app package name partner app package name wallet card template pre-defined partner’s wallet card template type > sub type > design type wallet card custom setting type authentication issuer set the authentication issuer for the relying party service to be provided as this wallet card please select authentication issuers from the identity provider groups only authentication issuers with the same “service location” as the relying party service are displayed ※ the identity provider of the “authentication issuer”is supported depending on the service location" set partner rp get request data url through which a partner receives a card data inquiry api call in case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/key ※ the attribute could be activated with the approval of a manager partner rp send authentication data url through which a partner receives a card data inquiry api callin case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/auth ※ the attribute could be activated with the approval of a manager samsung server ips samsung wallet server ips which need to be allowed at the partner’s firewall separately described for inbound and outbound calls service location select a regional limit for the wallet card if there was no selected location, the wallet card is shown in all locations if the specified location was selected, the wallet card is shown only in the selected location users can 'verify with samsung wallet' only in service locations where the wallet service is provided ※ the identity provider of the “authentication issuer” is supported depending on the "service location" set main headquarters location check to set it as a 'main location' as the company's main service country head office for creating and proceeding with wallet cards, notification e-mails such as wallet card approval requests are sent only to the selected main location wallet card data save in server set whether to store wallet card data in the server to protect personal information if the card has sensitive information, you can contact the developer support team not to save it description description of the wallet card select template partners can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id ※ for rp partners select "relying party type > other sub type" to set the relying party wallet card partners can select the type of wallet card needed to register from the 'select wallet card template' pop-up first, select the wallet card type and then select the wallet card sub type to select one of the templates belonging to it wallet card custom setting you must set the attributes of the "wallet card custom setting" according to the wallet card type you selected ※ for rp partners the "authentication issuer" attribute is a unique property of the relying party card the identity provider of the authentication issuer is supported depending on the "service location" set e g if service location is in the us, the authentication issuer field only supports an identity provider belonging to the us when the parent hierarchy value is checked, its children values created later are automatically checked in the united states, the authentication issuer is the state government, and the driver's license can be understood as an mdl mobile driver's license view wallet card partners can view all the registered information, edit and delete the wallet card launch wallet cards verifying status partners can launch and activate cards you can activate a card by clicking the launch button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, partners can modify and re-launch the administrator registers the reason for rejection when rejecting a launched wallet card partners will receive an email from the system, including the reason for rejection partners can apply for launching again by checking the reason for rejection and modifying the wallet card information testing mode partners can test a card internally to make sure everything works before officially release to the users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to ‘active’ after administrator approval when the card is activated, it becomes visible to the user verify with samsung wallet integration to integrate the wallet, you need to run the ‘verify with samsung wallet’ script into your system the verify with samsung wallet script is available for both web and android platforms each system has a different composition to implement the verify with samsung wallet button, follow the steps below in order create tokenized card data cdata card data is the actual content data of wallet card and it has several formats based on card type please refer to generate_cdata sample code for detail copy the sample verify with samsung wallet script from partner portal’s wallet card page and replace cdata with the data token created above apply the script to your system please see web_integration sample code and app_integration sample code for detail below is ‘verify with samsung wallet’ script guide in partner portal to integrate the ‘verify with samsung wallet’ you may need some base data you can find this base data and other necessary information on the partner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis
Develop Samsung Wallet
docgeneric card 'generic card' is defined for registering various forms of cards that aren't defined as other types partners can customize the items on the generic card to display by connecting them with card data wallet card type type sub-type generic others others wallet card data fields attributes type value description payload object cardtemplateobject required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtypestring 100 conditional this value is set to “generic” * required when creating a template cardtemplate subtype string 100 conditional this value is set to “others” * required when creating a template cardtemplate designtype string 100 optional select from these values “generic 01”, “generic 02”, “generic 03”* default “generic 01” cardtemplate prtnrapppckgname string 128 optional app package name cardtemplate applogoimg string 200 optional banner logo image url cardtemplate nonetworksupportyn string 1 optional either 'y' or 'n'* default 'n' cardtemplate privacymodeyn string 1 optional either 'y' or 'n'* default 'n' cardtemplate preventcaptureyn string 1 optional screen capture prevention flag cardtemplate category string 20 optional select from the following values “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others” cardtemplate state string 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoff string 1 optional testmode offeither 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551319", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "generic", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "designtype" "generic 02", "nonetworksupportyn" "n", "category" "membership", "privacymodeyn" "n", "preventcaptureyn" "n" } }
tutorials web
blogthe previous tutorial, implementing "add to wallet" in an android application, showed how to generate and sign a card data token to add the card to samsung wallet. this tutorial demonstrates how you can perform server interactions with the samsung wallet server and retrieve information such as the card states on a user’s device. if you are a samsung wallet partner who is offering samsung wallet cards to your users, you might also want to know how you can track a provided wallet card’s status on a user’s device. follow along in this tutorial to learn how you can utilize the send card state api and retrieve this information to your own server. all code examples used in this tutorial can be found within the sample code provided at the end of this tutorial for further reference. card states and the send card state api the samsung wallet card’s status on a user’s device is represented by various states, such as added, updated, or deleted. whenever the card state of a card changes on a user’s device, samsung wallet server sends a notification to the configured partner server informing about the change. this api provided by samsung is called the send card state api. figure 1: samsung wallet card state changes samsung provides the send card state api as a means of server-to-server communication between the samsung server and the partner’s server and to let the partner know about the card state of their issued cards on user’s devices. with this api, partners can track the state of a wallet card on a user’s samsung galaxy device. prerequisites before you can test the send card state api, you need to: complete the samsung wallet onboarding process. create a samsung wallet card template. launch the wallet card template and have it in verifying or active status so that the card can be added to a user’s device. have an existing server to receive the notifications. you can use codesandbox or a similar online hosting service for testing. configure your firewall (if you use any) to accept incoming connections from the samsung wallet server (34.200.172.231 and 13.209.93.60). when you have completed all the prerequisites, proceed to the next step to configure your wallet card template to send requests to your server. configure the wallet card template for the send card state api to receive the send card state notifications on your server, you need to set your server’s url in the desired samsung wallet card’s options: go to the wallet partners portal. from the wallet cards dropdown, select “manage wallet card.” click the name of the wallet card. click “edit” and then scroll down to the “partner send card state” section to modify the partner server url. click “save” to set the partner server url for the card. figure 2: partner send card state url input field now, whenever a user adds or deletes an issued samsung wallet card to their device, the samsung wallet server automatically sends a post notification to the partner server url set in the wallet partners portal. next you need to learn about the specification of the request so that you can handle it from the server. send card state api specification and format for a complete description of the send card state api specification, see samsung wallet documentation. request method the send card state api uses a post method to send a request to the server. the api path for the request is fixed and uses the partner server url that you defined in section “configure the wallet card template for the send card state api.” api path and url parameters the api path at the very end of the "partner send card state" section is the path where the samsung server sends the send card state post request. so the complete api path url is: {partner server url}/cards/{cardid}/{refid}?cc2={cc2}&event={event}. here, cardid is the card id of the wallet card template and refid is the reference id field of the issued card data, which is a unique identifier. the cc2 query parameter is the 2-letter country code (iso 3166-1 alpha-2) and event is the card state event (added, deleted, or updated) occurring in the user’s device. consider the following example card configuration: partner server url: https://partner.server.url card id: 123 ref id for the issued card: abc country code: us in this configuration, whenever the user adds the card to their samsung wallet application, the samsung wallet server sends a send card state notification to the following url: https://partner.server.url/cards/123/abc?cc2=us&event=added. similarly, if a user from the united kingdom deletes a card with the refid xyz, the post request is sent to https://partner.server.url/cards/123/xyz?cc2=gb&event=deleted. therefore, you can know if a card was added or removed from the user’s device directly from the query parameters. post request body the post request body does not contain any information regarding the card state. rather it just provides a callback url that you can use if you want to send an update notification for the card. { "callback": "https://us-tsapi.walletsvc.samsung.com" } post request header the post request header contains all the required information for ensuring the authenticity of the request. it contains a request id with the name “x-request-id” and a jwt bearer token credential for authentication with the name “authorization” in the header. the samsung wallet server uses a bearer authorization token to ensure the authenticity of the requests being sent to the partner server. for details of the security factors, see authorization token. the bearer token is encoded in base64 following the jwt specification. it has three parts: jws header containing authentication related information, jws payload containing the api path, method, and refid, and jws signature, which validates that the bearer token is signed by the samsung server. jws header format: { "cty": "auth", // always “auth” "ver": "3", // can also be “2” for legacy card data token "partnerid": "4048012345678938963", // your partner id "utc": 1728995805104, // time of signing in milliseconds "alg": "rs256", "certificateid": "a123" // only provided for token version 3 } jws payload format: { "api": { "path": "/cards/3h844qgbhil00/2e19cd17-1b3e-4a3a-b904?cc2=gb&event=added", "method": "post" }, "refid": "2e19cd17-1b3e-4a3a-b904-f30dc91ac264" } finally, the bearer token contains a signature to verify the token. this is signed using the samsung private key and can be validated using the public key provided by samsung wallet during the onboarding process. after receiving any request from the samsung wallet server, your server should send back an http status code as a response. samsung server expects one of the following codes as a response: 200 ok 401 unauthorized 500 internal server error 503 service unavailable this is the complete specification of the send card state api that you need to be aware of before you implement the server. next, you need to configure your server to accept the post request in the specified format. configure the spring server to receive the post request to receive and interpret the send card state post notifications sent by the samsung wallet server, you need to configure a partner server and host the server at the url you specified earlier. to receive the post requests, this tutorial extends an existing server created using the spring boot framework. if you want to know how the spring server is configured, check out the “generate signed wallet card data” section in the implementing "add to wallet" in an android application tutorial. this cdata generation server is used as the base server application for this tutorial, so the dependencies are the same as well. now you can start implementing the tutorial. create a controller class to intercept the post request samsung wallet always sends the send card state post notification to the fixed api path url: {partner server url}/cards/{cardid}/{refid}. create a new controller class in your spring server to intercept any post request that is sent to this api path. @restcontroller @requestmapping("/cards") class cardstatecontroller { @postmapping(path = ["/{cardid}/{refid}"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string): httpstatuscode { // implement your logic here to process the card state. println("received card state notification for card id $cardid and reference id $refid.") return httpstatus.ok } } run the server and then add or delete a card from your samsung wallet. if the partner server url was set correctly in section “configure the wallet card template for the send card state api,” your server should receive a post request from the samsung server and print the following message to the console: “received card state notification.” update the controller class to receive the query parameters handle the query parameters from the request by adding the following parameters as the function’s parameters: @requestparam("cc2") cc2: string, @requestparam("event") event: string receive and print the request body using the @requestbody body: string parameter. the function should now look like this: @postmapping(path = ["/{cardid}/{refid}"], params = ["cc2", "event"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string, @requestparam("cc2") cc2: string, @requestparam("event") event: string, @requestbody body: string): httpstatuscode { // implement your logic here to process the card state. println("country code: $cc2") println("wallet card state event: $event") println("request body: $body") return httpstatus.ok } now whenever the samsung server sends a request to the server, it prints the device’s country code and the wallet card’s state event on the device. verify the post request this is the final and the most important step of this tutorial. before accepting any incoming post request, you should always validate the request by following the api specification mentioned earlier in the tutorial. the security procedures can include but are not limited to: matching your partnerid with the received partnerid custom parameter. checking the token version with the ver custom parameter. for token version 3, match your certificateid using the certificateid custom parameter. checking the time of signing using the utc custom parameter. matching the other jws header parameters with the values mentioned in the specification. matching the path from the jws payload with the received url. verifying the jwt. this section shows how you can implement each of these one by one. first, parse the authentication token and read the header. val signedjwt : signedjwt = signedjwt.parse(authtoken) val jwsheader : jwsheader = signedjwt.header match partnerid and jws header parameters: val ownpartnerid = "4048012345678938963" // your partner id from samsung wallet partner portal val receivedpartnerid = jwsheader.customparams["partnerid"] val ctype = jwsheader.contenttype val alg = jwsheader.algorithm.name // check if the jws header parameters match the expected values if (ctype == "auth" && alg == "rs256" && receivedpartnerid == ownpartnerid ) { println("jws header parameters matched") // proceed with further verification } check the token version and match certificateid: val ver = jwsheader.customparams["ver"] val owncertificateid = "a123" // your certificate id from samsung wallet partner portal val receivedcertificateid = jwsheader.customparams["certificateid"]?: "" // if partner uses token version 3 in the jws header of the cdata, // then samsung server also returns version 3 response along with the certificate id if(ver == "3" && receivedcertificateid == owncertificateid){ println("jws header certificate id matched") // proceed with further verification } check if the token was generated recently: // check if the timestamp is within acceptable range val utc = jwsheader.customparams["utc"] as long val timedelta = system.currenttimemillis() - utc println("time delta: $timedelta") if (timedelta < 600000l) { println("utc timestamp is within last 1 minute. time delta = $timedelta ms.") // proceed with further verification } match the api path with the received api path from the payload: val receivedapivalue = signedjwt.payload.tojsonobject()["api"]?.tostring()?: "" val receivedapipath = receivedapivalue.substring(6, receivedapivalue.length - 14) val expectedpath = "/cards/$cardid/$refid?cc2=$cc2&event=$event" // match the path in the payload with the expected path if (receivedapipath == expectedpath) { println("path matched") // proceed with further verification } finally, validate the token using the samsung certificate provided to you during the onboarding process: read the samsung certificate from a file and then extract the public key. for instructions, refer to the cdata generation server sample code at implementing "add to wallet" in an android application. build an rsakey object using the extracted public key. create an rsassaverifier object with the rsakey to verify the token. verify the token using the verifier. // verify the signature of the jwt token using the public key provided by samsung wallet. val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) val rsakey = rsakey.builder(samsungpublickey as rsapublickey).build() val verifier: rsassaverifier = rsassaverifier(rsakey) if(signedjwt.verify(verifier)){ println("verification successful") // implement your logic here to process the card state notification. // for example, you can update the card status in your database or trigger a notification to the user. // in this example, we simply return a 200 ok response indicating that the notification was successfully processed. return httpstatus.ok } else { println("verification failed") // return an appropriate http status code indicating that the notification could not be verified. return httpstatus.unauthorized } now the complete implementation of the controller class to receive and verify the send card state request is complete. once a send card state request is completely verified, you can accept the request as a valid card state update and make any changes as required. for example, you can update the card status information in your own database or trigger a notification to the user. summary by completing this tutorial, you are now able to receive card state updates from the samsung wallet server using the send card state api and validate them. in a future tutorial, we will discuss how you can expand the server interaction functionality even further and how you can update samsung wallet card information on user devices through the get card data api. if you want to discuss or ask questions about this tutorial, you can share your thoughts or queries on the samsung developers forum or contact us directly for any implementation-related issues through the samsung developer support portal. if you want to keep up-to-date with the latest developments in the samsung developers ecosystem, subscribe to the samsung developers newsletter. sample code you can click on the link given below to download the complete sample code used in this tutorial. wallet card state server sample code (55 kb) dec 2024 additional resources implementing "add to wallet" in an android application send card state authorization token iso 3166 country codes
Mobassir Ahsan
Develop Samsung Wallet
docloyalty 'loyalty' cards support enrolling loyalty cards also known as membership links urls to get points in real time can be provided in the partners portal if a partner needs to integrate communication between samsung wallet server and the partner’s server to support the feature, the partner has to set the links in the partners portal wallet card type type sub-type loyalty others others wallet card data fields attributes type value description payload object cardtemplateobject required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefidstring 19 required partner template id cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtype string 100 conditional this value is set to “loyalty” * required when creating a template cardtemplate subtypestring 100 conditional this value is set to “others” * required when creating a template cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url cardtemplate nonetworksupportyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate state string 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoff string 1 optional testmode off either 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551316", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "loyalty", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } }
Develop Samsung Wallet
doccoupon 'coupon' cards support digitized redeemable vouchers coupons in wallet for various channels can provide alarms before expiration and update usage status wallet card type type sub-type coupon others others wallet card data fields attributes type value description payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtype string 100 conditional this value is set to “coupon” * required when creating a template cardtemplate subtype string 100 conditional this value is set to “others” * required when creating a template cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url cardtemplate nonetworksupportyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate state string 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoff string 1 optional testmode off either 'y' or 'n'* default ‘n’available only when updating templates cardtemplate desc string 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551313", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "coupon", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } }
Develop Samsung Wallet
docdigital ids 'digital id' cards are used to present identification for employees, students, drivers, guests, etc wallet card type type sub-type idcard employees, nationals, students, drivers, guests, others employees nationals students drivers wallet card data fields attributes type value description payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id cardtemplate titlestring 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtypestring 100 conditional this value is set to “idcard” * required when creating a template cardtemplate subtype string 100 conditional select from these values employees, nationals, drivers, and others * required when creating a template cardtemplate saveinserverynstring 2 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate prtnrapppckgnamestring 128 optional the application package name cardtemplate applogoimgstring 200 optional the banner logo image url cardtemplate nonetworksupportyn string 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 privacymodeyn string 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 statestring 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoff string 1 optional testmode off either 'y' or 'n'* default ‘n’available only when updating templates cardtemplate desc string 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551317", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "idcard", "subtype" "employees", "applogoimg" "http //www yourdomain com/banner_logo_image png", "saveinserveryn" "y", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } }
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.