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
doc5 2 card 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 5 2 1 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 5 2 2 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 5 2 3 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
doc5 4 card specs 5 4 1 boarding pass 'boarding pass' cards support one-off transit types such as airlines, trains, buses, ferries, and etc boarding passes in wallet can remind the user of boarding time and help during check-in depending on the integration level, it can provide status information updates related to flights, and journeys, such as boarding gate changes or cancellations wallet card type type sub-type boardingpass airlines, trains, buses, others airlines buses trains wallet card data fields attributes type value description payload object cardtemplateobject required wallet card template object cardtemplate prtnridstring 32 required partner id cardtemplate templaterefidstring 19 required partner template id cardtemplate titlestring 32 required wallet card name cardtemplate countrycodestring 2 conditional the main headquarters location * required when creating a template cardtemplate cardtypestring 100 conditional this value is set to “boardingpass” * required when creating a template cardtemplate subtypestring 100 conditional select from these values “airlines”, “trains”, or “buses” * required when creating a template 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 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 descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551312", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "boardingpass", "subtype" "airlines", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n" "sharebuttonexposureyn" "y" "privacymodeyn" "n" "preventcaptureyn" "n" } } 5 4 2 event ticket 'event ticket' cards support event commodities for performances, sports, movies, entrances, and etc event tickets in wallet can provide additional information about the event and an alarm before the event time and expiration ticket cards support event commodities for performances, sports, movies, and entrance wallet card type type sub-type ticket performances, sports, movies, entrances, others performances movies sports entrances wallet card data fields attributes type value description payload object cardtemplate object required wallet card template object cardtemplate prtnridstring 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 set “ticket”* required when creating a template cardtemplate subtypestring 100 conditional select from these values performances, sports, movies, entrances, and others * required when creating a template cardtemplate prtnrapppckgname string 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 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 statestring 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoffstring 1 optional testmode offeither 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551314", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "ticket", "subtype" "entrances", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } } 5 4 3 coupon '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", } } 5 4 4 gift card 'gift card' cards support enrolling prepaid cards also known as gift certificate, gift voucher or gift token links urls to get balance and transactions history in real time is 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 partners portal wallet card type type sub-type giftcard 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 cardtype string 100 conditional this value is set to “giftcard” * required when creating a template cardtemplate subtype string 100 conditional this value is set to “others” * required when creating a template cardtemplate prtnrapppckgnamestring 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 statestring 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoffstring 1 optional testmode off either 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551315", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "gift", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } } 5 4 5 loyalty '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" } } 5 4 6 digital 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" } } 5 4 7 pay as you go 'pay as you go' card supports a system that pays just before using the cost for the service wallet card type type sub-type payasyougo evcharges, others evcharges wallet card data fields attributes type value description payload object cardtemplate object required wallet card template object cardtemplate prtnridstring 32 required partner id cardtemplate templaterefidstring 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 “payasyougo” * required when creating a template cardtemplate subtypestring 100 conditional this value is set to “evcharges” * required when creating a template cardtemplate prtnrapppckgnamestring 128 optional app 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 privacymodeynstring 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 offeither 'y' or 'n'* default ‘n’available only when updating templates cardtemplate desc string 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551318", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "payasyougo", "subtype" "evcharges", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } 5 4 8 generic 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
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
doc3 2 manage 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 3 2 1 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 3 2 2 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
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
Learn Code Lab
codelabutilize the add to samsung wallet service for digital cards notescenes in the demo video are simulated and does not represent any real-world conditions or outcomes objective learn how to use the add to samsung wallet service so that users can store digital contents, such as boarding passes, tickets, and coupons, to their samsung wallet app partnership request to create, manage, and monitor performance of wallet cards with the samsung wallet partners site, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more by visiting samsung wallet partner onboarding process, here in samsung developers overview samsung wallet is an application that securely stores essential items such as boarding passes, tickets, and coupons, making them easily accessible from anywhere with this app, users can access various partner wallet cards in one place, simply by swiping up from the bottom of the screen the add to samsung wallet service provides interfaces for users to conveniently add digital content to samsung wallet here are examples of the supported wallet cards boarding pass journey information such as flights, trains, and buses can be provided as notifications, allowing easy retrieval when checking in by configuring server synchronization, updates to journey information such as gate changes, schedule changes, or cancellations can be received by the users ticket notifications about events and additional information, including benefits, can be provided based on real-time utilization of performances, sports games, movies, and admission tickets, status updates related to expiration and availability can be provided gift card gift card, also referred to as a prepaid card, provides real-time balance and transaction history loyalty loyalty cards function as membership credentials, managing membership information through these cards, loyalty points can be administered and redeemed id id cards can fulfill identification verification purposes, such as identity cards, employee cards, and licenses physical documents can be represented through wallet cards, and near field communication nfc -based authentication can be provided reservation reservation cards can contain diverse online booking details, including rental cars, restaurants, and accommodations ongoing reservation information can be managed as a journey pay as you go pay as you go cards allow users to register services that can be charged and utilized according to their preference for convenient use generic card generic cards enable users to create customized cards by selecting preferred card template layouts and designing elements notedepending on your country or region, some card types are not supported if you need assistance, please contact us at developer samsung com/dashboard/support the image below shows the process of managing wallet cards for more information, refer to manage wallet cards set up your environment you will need the following latest version of samsung wallet app from galaxy store samsung galaxy device that supports samsung wallet access to samsung wallet partners site internet browser, such as chrome openssl intellij idea or any java ide optional start the onboarding process partners can manage wallet cards and monitor performance with the samsung wallet partners site to join as partner generate a private key and certificate signing request csr using the openssl command you can follow the instructions in security factors notea private key enables encryption and is the most important component of certificates while csr, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country proceed to register in the samsung wallet partners site using your samsung account follow the samsung wallet partner onboarding process upload the generated csr for data encryption in encryption setting management section after registration, you will receive a welcome email noteupon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes signed certificate used along with the private key to sign data samsung certificate used to encrypt card data and validate authentication tokens in server api headers create a wallet card follow the steps below to create a wallet card in samsung wallet partners site click the wallet cards menu and choose create wallet card fill out the general information form with the details of the wallet card in wallet card template, choose a card type and sub type select the design type and click done you can choose from various types of wallet card templates optimized for partners after inputting all necessary details, click save to set the wallet card status to draft launch the wallet card you can launch and request activation of the card by clicking the launch button upon agreeing to proceed, the launch button text changes to launched and the card status becomes verifying add the card to samsung wallet using the test tool open a web browser on your computer or galaxy mobile device, and go to the following link partner walletsvc samsung com/addtowallettest go to add to wallet tab and click choose key file to upload your private key in the select card dropdown menu, select the created card to display the card details and populate sample data navigate to the form tab and modify the card data as desired notethe structure for configuring wallet cards follows the defined specification you can refer to the full list of card-specific attributes specification scroll down to the bottom of the page and click the add to samsung wallet button click done when a preview of the card shows on your mobile screen with a message indicating that the card has been added to your wallet once the card is added to your samsung wallet app, you can check its details by clicking on it noteyou can also go to the playground tab and add cards to the samsung wallet app even without creating a card on the wallet partners site update the status of the added card if a server api info partner get card data and partner send card state is registered in the wallet card, real-time updates of the user's registered cards can be provided notefor more information, see server interaction modify and update the card's status by utilizing the push notification feature of the test tool navigate to the push notification tab ensure that the correct private key is uploaded and the same card as in the add to wallet tab is selected copy the ref id value from the add to wallet tab and paste it into ref id field in the push notification tab in the status field, enter one of the following card states expired, redeemed, held, suspended, or deleted the current state is set to active then, click the request push notification button check the card in the samsung wallet app to confirm the change tokenize card data and implement the add to samsung wallet button to your service optional notethis step is optional, but if you want to learn how to integrate the add to samsung wallet button into your services like an android app, web app, or email, you can follow these steps the samsung wallet partners site provides generated add to samsung wallet scripts for each wallet card you create you can simply copy and paste these scripts into your partner apps web and android or include them in emails/mms messages to implement the add to wallet button, follow these steps go to the [add to wallet script guide] section of the card you created click show to view the available scripts and then copy the appropriate script for your service develop a program that can generate tokenized card data cdata the cdata represents the actual content of the wallet card and comes in different formats depending on the card type you can check the cdata generation sample code for reference the cdata is derived from the card data, which is in json format for testing purposes, you can utilize the generated json from the test tool follow the implementing atw button guide to determine where to incorporate the generated cdata and gain further insights into this process you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can utilize the add to samsung wallet service by yourself! to learn more about samsung wallet, visit developer samsung com/wallet
tutorials mobile
blogsamsung wallet is introducing a new feature called "generic card" for partners who cannot use other card types to fulfill their business requirements. this provides flexibility to modify various field labels for the card, according to the partners’ business needs. other cards, such as boarding passes and coupons serve a specific purpose, and their field labels cannot be modified. however, with a generic card, the label can be modified so it can be used for multiple purposes. in this article, you learn how to modify a generic card to use it as an insurance card. we will explain the details specification with example of the generic card. at the end of the article a guide will be provided to implement this card for your reference, to help you modify your generic card according to your needs. card setup before you begin creating a new card template, log in to the samsung wallet partner site and create a generic card. log in to the samsung wallet partner site. go to the wallet cards and then create wallet card. for more details about creating a card, check the manage wallet cards documentation. select generic card from the available card templates. modify the card information. when you have finished editing card information, launch the card to complete card setup. for more information on how to launch the card, see launch wallet cards. template editor use the template editor to modify the card template. from the "cardart" view, you can modify the card color, set a background image or change the logo image properties. from the "enlarge" view, you can modify the {{text1}} and {{text2}} labels. however, only the label itself can be changed in the template editor. to set the label value, you need to update the json file. from the "detail" view, you can modify the "textgroup" and "applink" properties. modify the text label according to your needs. it is also possible to add new text fields, with a maximum of 12 text fields allowed. after every modification, click save. finally, apply all changes by clicking apply. if you want to preview your changes, just click preview. add to samsung wallet now that the card has been created in the site, it is ready to be distributed to fulfill your business needs. implement the "add to samsung wallet" functionality to the platform where you are planning to distribute the cards. when users click "add to samsung wallet," the card is added to the wallet application on the user’s galaxy device. this functionality can be added through the application/mobile web, mms, or email. additionally, you can use a qr code on a computer web browser and kiosk. samsung provides a codelab guide for developers so that they can easily understand the implementation. for additional information on the codelab guide, read utilize the add to samsung wallet service for digital cards. further details can also be found in the implementing atw button documentation. card specifications to complete the "add to samsung wallet" button implementation, you must generate the card data token and create a final url. for more information, see add to samsung wallet. let’s start by reviewing the generic card specifications to generate the card data token. the generic card follows the specifications below. for more information on them, see the generic card section. name description title the main title of the generic card. in the sample card, the title is "card title." in the image below, the title is "insurance identification card." subtitle the subtitle of the generic card. in the sample card, it is "card subtitle". providername use this field to set the card provider name. for more information, check the card json example below. however, the provider name depends on your card type and should be modified accordingly. eventid enter an id as an event identifier. in case your card is prepaid, for example a gift card, or if you have vouchers to events, such as concerts, it is possible to define an event id. for instance: "event-001". groupingid enter an identifier to group related cards. startdate enter the starting date and the epoch timestamp in milliseconds. startdate.relativenotitime enter the amount of time within which you want to provide a notification to the user. the notification time is the relative time from the startdate. the value can be up to 2880 milliseconds. enddate enter the end date and the epoch timestamp in milliseconds. enddate.relativenotitime enter the amount of time within which you want to provide a notification to the user. the notification time is the relative time from the enddate. the value can be up to 2880 milliseconds. logoimage set the logo image url. the file size must not exceed 256 kb. also this image can be set from the template editor. logoimage.darkurl set the logo image url for the dark mode. the file size must not exceed 256 kb. logoimage.lighturl set the logo image url for the light mode. the file size must not exceed 256 kb. bgimage set the background image url. the file size must not exceed 512 kb. text{i} set the label-text value that should be displayed for each field containing the details of your card. the label is defined in the template editor, shown in the image below. to set the value of the label, update the json file. image{i} enter the image url, such as: "https://www.samsung.com/images/image1.png". this url is just an example, you must update it according to your needs. this field only works in generic card type3. we have used a type1 card in the example. so this field in the example json has no effect on the card. you can find all three card type sample uis here. image{i}.lighturl enter the image url in light mode, such as: "https://www.samsung.com/images/light.png". this url is just an example, you must update it according to your needs. image{i}.darkurl enter the image url in dark mode, such as: "https://www.samsung.com/images/dark.png". this url is just an example, you must update it according to your needs. serial{i} set the serial for barcode or qr code. serial{i}.serialtype serial presentation type. for more information on the presentation types (serialtype), see references. serial{i}.ptformat set the presentation format. for more details on the presentation formats (ptformat), see references. serial{i}.ptsubformat set the presentation subformat here. for more details on the barcode formats (ptsubformat), see references. serial{i}.errorcorrectionlevel set the error correction levels in this field. the amount of redundancy or error correction data included in the code varies. qr codes offer four levels of error correction: l, m, q, and h. the qr field looks like the following in your card: privacymodeyn set the user authentication if required. set the value to "y" or "n" bgcolor set the card art color. fontcolor set the card art font color. nonetworksupportyn set the value to "y" to open the wallet card when under the "no network" status. otherwise, set the value to "n" noticedesc set the the notice description here. see the image below of how it is added to card. applinklogo add the application link logo url in this field. applinkname add the application link name in this field. applinkdata add the application link url in this field. locations list of locations where the card will be used. this information can be used to provide location-based services. samsung wallet can use this information to show maps, names of places, and addresses. for more information on the locations field and json format, check references. card json example in previous sections, you have learned about the card specifications. next, let’s implement the generic card fields according to your needs. in this section, as the aim is to create an insurance card, you must use the fields accordingly. samsung provides a specifically formatted json structure. you need to configure the card data objects within the structure’s data array. for more details, see the generic card section. { "card": { "type": "generic", "subtype": "others", "data": [ { "createdat": 1709712961000, "updatedat": 1709712961000, "language": "en ", "refid": "933533e1-9284-461c-905f-bc177526a8d1", "attributes": { "title": "insurance identification card", "subtitle": "insurance card", "providername": "samsung insurance co.", "eventid": "1", "groupingid":"1", "startdate": 1731299205000, "startdate.relativenotitime": 500, "enddate": 1731320805000, "enddate.relativenotitime": 400, "logoimage": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "logoimage.darkurl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "logoimage.lighturl": "https://us-cdn-gpp.stg.mcsvc.samsung.com/mcp25/resource/2023/12/20/55ea769f-d14d-4c47-94cc-50cade36cdd9.png", "bgimage": "", "text1": "1234567", "text2": "samsung insurance co.", "text3": "jaqueline m", "text4": "samsung motors 2014 galaxy5", "text5": "11sam23sung3t", "text6": "(031)000-1235", "image1": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "image1.darkurl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "image1.lighturl": "https://us-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/3/5/b9445e3f-2ef5-4d81-9fca-b7a8a7cd599f.png", "serial1.value": ">1180mm2241b7c 0000000000000298060000000000 0 090870907 ", "serial1.serialtype": "qrcode", "serial1.ptformat": "qrcode", "serial1.ptsubformat": "qr_code", "serial1.errorcorrectionlevel": "m", "privacymodeyn": "y", "bgcolor": "#3396ff", "fontcolor": "#ffffff", "nonetworksupportyn": "n", "noticedesc": "{\"count\":2,\"info\":[{\"title\":\"notice1\",\"content\":[\"description1\",\"description2\"]},{\"title\":\"notice2\",\"content\":[\"description1\",\"description2\"]}]}", "applinklogo": "https://www.samsung.com/logo.png", "applinkdata": "https://www.samsung.com/", "applinkname": "samsung insurance co.", "locations": "[{\"lat\": 37.2573276, \"lng\": 127.0528215, \"address\": \"suwon\", \"name\": \"digital city\"}]" } } ] } } generic card testing with the "add to wallet" test tool now, you can test the generic card with the "add to wallet" test tool provided by samsung. just follow these steps: sign in to the add to wallet test tool. for more information, see the samsung wallet test tool. enter the private key in the "enter partner private key" field. in this tool, you find all cards that you have created from the samsung wallet partner site in the "select card" section. for more information, see the samsung wallet partner site. select the generic card that you have just created. now select json from the data field and modify the existing json data fields according to the card specification details. after modifying the json data fields, check if the json is valid. finally, if the private key is valid, the "add to samsung wallet" button becomes active at the bottom of the page. then, just click add to samsung wallet to finish adding the generic card. if you use the provided example json and add the card to the wallet, the card looks like the following: server integration in this step, server configuration is needed because the generated jwt token expires after 30 seconds. developers are advised to only generate this token after a user has clicked the "add to wallet" button. as you have already performed testing with the "add to wallet" test tool, you need to configure your server. for more information on the implementation of both the "add to samsung wallet" button and server-side logic, see implementing "add to wallet" in an android application. this article explains how you can distribute your card with your android application and how to generate the jwt token at runtime, after pressing the "add to samsung wallet" button. conclusion you have now learned the basics for how to set up a generic card and test it for your business needs. in case you have further questions, contact samsung developer support. related resources utilize the add to samsung wallet service for digital cards introduce loyalty cards to your application with samsung wallet implementing "add to wallet" in an android application seamlessly integrate "add to wallet" for samsung wallet
M. A. Hasan Molla
Develop Samsung Wallet
doc5 1 overview 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 create a base template before issuing any new wallet item or "wallet card" , you must first create a base template this serves as the foundation for your custom card types card management tools you can manage your wallet cards using two primary tools wallet partners portal ideal for creating and managing individual or smaller batches of cards provides a user-friendly interface for status management, updates, and review server api access designed for partners managing a high volume of cards allows for automation and scalable integration cards created via api are still visible and manageable through the wallet partners portal card lifecycle & status states wallet cards go through several status changes during their lifecycle each status affects what actions can be taken on a card state 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 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 important testing mode cards are automatically placed into testing mode when first created in this mode, the card is not live to end users you must manually switch testing mode off once testing is complete note testing mode cannot be re-enabled after it is turned off adding wallet cards to users wallet cards can be added to a user's samsung wallet in two ways standard add flow – user initiates the addition e g , via a qr code or deep link automatic add special case – select partners may be authorized to add cards automatically, without direct user interaction this functionality is strictly regulated and reserved for approved use cases only
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.