Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
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
web
learn to develop with samsung explore our sdks and tools through code lab, blogs, tutorial videos, and more. learn easily, build confidently gain the knowledge you need to deeply understand various samsung services and technologies. apply what you learn to transform your ideas into reality. hands-on exercises packed with real-world use cases, code lab is your go-to learning platform designed to help you easily understand the usage of samsung services and technologies. visit code lab latest learning topics discover fresh content and learn something new today! code lab code lab apply motion graphics to your watch face using tag expressions and gyro effects learn to use tag expressions and gyro effects in watch face studio to create watch faces with dynamic and animation-like effects. code lab code lab implement in-app subscriptions using samsung iap learn how to integrate the samsung in-app purchase sdk into your application so that users can purchase and upgrade subscriptions directly within the app. code lab code lab access rich sleep data from samsung health measured by galaxy wearables create a health app for android devices, utilizing the samsung health data sdk to obtain samsung health's rich sleep data. blog blog create samsung wallet card templates using the server api the blog describes how to implement the adding samsung wallet card templates server api with your server. blog blog easy steps to capture and collect logs from galaxy watch how to collect a dumpstate log from your galaxy watch tutorial videos go to youtube samsung health oct 28, 2025 samsung health sdk suite webinar: discover new benefits and integration insights oct 28, 2025 samsung wallet, samsung pay aug 13, 2025 introduction of samsung wallet and samsung pay for partners aug 13, 2025 samsung log apr 8, 2025 how to apply lut on samsung log videos in premiere pro apr 8, 2025 more topics to explore foldables and large screens boost your app's value with foldables and large screen optimization. get started one ui beta program enjoy one ui features before their official release. get started newsletter monthly newsletter for samsung developers if you are not currently receiving the newsletter, you can subscribe here. 뉴스레터 전송을 위한 개인정보 수집∙이용에 동의합니다(필수). detail 광고성 정보 수신에 동의합니다(필수). detail i agree to data processing for sending newsletters. (required) detail i consent to receiving newsletters via email. (required) i consent to receiving newsletters via email. detail subscribe
Develop Samsung Wallet
doccard management api guidelines once your service is successfully onboarded, you gain the ability to design and deploy custom digital assets—such as boarding passes, coupons, tickets, and more—directly to samsung wallet the adding samsung wallet card templates section defines interfaces for providers to conveniently create wallet cards in samsung wallet the generated wallet card templates can be updated by following the instructions on the updating wallet card templates section authorized partners can add wallet cards to users directly from the partner server by following the instructions on the adding wallet cards section below service domain environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card templates this section describes how to create a wallet card in samsung wallet [request] type value description method post url /partner/v1/card/template headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id unique value for each template created by a partner this value is set to a number of 19 digits or less cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 required the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate cardtype string 100 required template card type for details, refer to wallet cards cardtemplate subtype string 100 required template card sub type for details, refer to wallet cards cardtemplate designtype string 100 optional the value that defines the design type of the wallet card for details, refer to wallet cards cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of the image is 1024*1024 e g http //www yourdomain com/banner_logo_image png cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, the user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance, parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrcardstate string 1000 optional [get card state] partner url check the url format below and implement api according to url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional when creating a card, you can transition the card's state from “draft” to “verifying” you can only choose “draft” or “verifying” * default 'draft' cardtemplate desc string 500 optional description example /** example card template object **/ { "prtnrid" "4083254626439156160", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "cardtype" "coupon", "subtype" "others", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/] { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable updating wallet card templates wallet card templates updated through api can also be checked and managed in the same way on the ‘wallet partners portal' partners can manage all wallet cards they have created [request] type value description method post url /partner/v1/card/template/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate cardid string 32 required the cardid response received when creating a card cardtemplate templaterefid string 19 required partner template id the unique value for each template created by a partner this value is set to a number with 19 digits or less cardtemplate title string 32 optional wallet card name cardtemplate countrycode string 2 optional the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of that image is 1024*1024 cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate nonetworksupportyn string 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional if this value is set, user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others cardtemplate prtnrcarddata string 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomainn cardtemplate prtnrcardstate string 1000 optional partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional if the card status is “draft”, you can only select “verifying” cardtemplate testingmodeoff string 1 optional this value can be set only when the card status is active normal service is possible only when the testing mode is changed to off * default ‘n’ cardtemplate desc string 500 optional description [example] /* *example card template object **/ { "prtnrid" "4083254626439156160", "cardid" "3hdpejr6qi380", "templaterefid" "123456781864545365", "title" "coupon", "countrycode" "kr", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template/cardid=3hdpejr6qi380 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable adding wallet cards a typical addition to the wallet card is triggered by user interaction, such as pressing the add to wallet button or link the api also supports adding a wallet card automatically to the user for a special purpose with user’s consent this api allows partners to provide wallet cards to users the request payload must contain information about the target to which the card is added this information may be related to the user’s account, or it may contain information about a card that is already registered a push notification is sent to the user’s device to confirm successful card registration the success of card registration must be determined that the card is registered normally when it is updated to added of send card state an administrator must grant permission for partners to use this api card data specification card id {card id} is an id issued when the partner manager signs up for partner services and register the wallet card they want to service refer to partner onboarding guide document for details cdata actual payload data in basic json format to establish the communication between partners and samsung wallet see the details in the table below card data token the specific wallet card data mentioned as cdata must be secured in jwt json web token format see a chapter security for details [request] type value description method post url /atw/v1/cards/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required wallet card identifier granted through the partner portal body parameters cdata object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object card object required wallet card object card type string 16 required wallet card type *see wallet cards card subtype string 16 required wallet card sub type *see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds *utc±00 00 data[] updatedat long 13 required data update timestamp epoch timestamp in milliseconds *utc±00 00 data[] language string 8 required default card language code e g en, ko data[] attributes object required attributes container data[] attributes {fields} required attributes fields by card type*see wallet cards data[] localization[] array of object optional localized language container *see wallet cards localization[] language string 8 required multilingual content language code, e g en, ko localization[] attributes {fields} for displaying a given language, ‘data[] attributes’ can be replaced by localized versions *see wallet cards account object conditional user account object account type string 16 required type of user identifier, e g phonenumber, email account value string 64 required user identifier [example] /** example card object **/ { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678” } } /** example **/ post /atw/v1/cards/1656147182764415319 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "cdata" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable
Develop Samsung Wallet
webadd to wallet,boost your business. you can now create and publish content such as coupons, boarding pass or tickets to the users of samsung wallet. get started together with new partner you can now create and publish content such as coupons, boarding pass or tickets to the users of samsung wallet. this is enabled by a two-step process where you onboarding on our partner portal. what can beadded to samsung wallet boarding pass boarding passes can be added to wallet. registered boarding passes enable smoother check-ins and boarding time reminders. gift cards gift cards can be added to wallet. registered gift cards are securely stored and easy to access when needed. membership memberships can be added to wallet. registered membership cards display the membership point status and addtional membership program information. tickets movie and event tickets can be added to wallet. registered tickets can provide expiration reminders and additional ticket information. coupons coupons from various channels, such as sms, mms, email, and in-service can be added to wallet. registered coupons can provide expiration reminders and usage status information. generic cards generic cards can be added to wallet. registered generic cards can display various types of card art templates and undefined label fields. this type lets you add a variety of scalable cards to the wallet. ev charge cards ev charge cards can be added to wallet. registered ev charge cards allow the user to start charging their vehicles and receive benefits from their charging networks easily and conveniently. digital ids digital ids, such as driver's licenses, company ids, student ids, and others, can be added to wallet. registered digital ids can be used to access your place or prove your identity online and offline. boarding pass boarding passes can be added to wallet. registered boarding passes enable smoother check-ins and boarding time reminders. gift cards gift cards can be added to wallet. registered gift cards are securely stored and easy to access when needed. membership memberships can be added to wallet. registered membership cards display the membership point status and addtional membership program information. tickets movie and event tickets can be added to wallet. registered tickets can provide expiration reminders and additional ticket information. coupons coupons from various channels, such as sms, mms, email, and in-service can be added to wallet. registered coupons can provide expiration reminders and usage status information. generic cards generic cards can be added to wallet. registered generic cards can display various types of card art templates and undefined label fields. this type lets you add a variety of scalable cards to the wallet. ev charge cards ev charge cards can be added to wallet. registered ev charge cards allow the user to start charging their vehicles and receive benefits from their charging networks easily and conveniently. digital ids digital ids, such as driver's licenses, company ids, student ids, and others, can be added to wallet. registered digital ids can be used to access your place or prove your identity online and offline. how to designsamsung wallet we encourage you to learn and follow the rules and guidelines suggested to ensure message consistency and drive brand awareness. learn more news and blogs learn more how can we help you? faq search frequently asked questionsby keywords. join the forum visit the forum to ask questions andexchange ideas with other developers. get support submit a 1:1 support request and receive a response within 2 business days.
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
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
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
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
Develop Samsung Wallet
docoverview 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
Develop Samsung Wallet
docmanage wallet card the samsung wallet partners portal provides partners with the necessary tools and functionality to integrate the “add to samsung wallet” feature into their services this guide outlines the process of registering, managing wallet cards, and ensuring that everything runs smoothly refer to the partner onboarding guide for the samsung wallet portal the partners need to complete the following steps to register and gain access to the samsung wallet portal note-wallet portal currently offers 'add to samsung wallet' functionality to the partners overall managing process once registered and logged into the samsung wallet portal, partners can follow the steps to manage wallet cards and monitor performance step 1 - create wallet cards templates begin by drafting the cards that will be added to samsung wallet these cards can include loyalty cards, tickets, boarding passes, and more draft status - initially, these cards will be in draft status until they are fully configured and ready for testing manage cards partners can manage all registered wallet cards this includes edit, update, and monitor the status of the wallet cards general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet folder contents testing mode all data generated in testing mode is periodically deleted be sure to turn off the "testing mode" setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name partner app package name partner application package name wallet card template pre-defined partner wallet card template partner get card data url for the partner api call to receive card data if the partner uses this api, enter the url otherwise leave it blank partner send card state url for the partner api call to send a card state notification if the partner uses this api, enter the url otherwise leave it blank samsung server ips samsung wallet server ips which need to be allowed by the partner’s firewall, separately described for inbound and outbound wearable wallet assistance whether to support the wearable wallet service support ‘no network’ status whether to support wallet card opening during the ‘no network’ status description description of the wallet card select template the samsung wallet portal offers various wallet card templates optimized for different use cases, including boarding passes, tickets, coupons, and digital ids to streamline your integration, you can easily select the appropriate template from the select wallet card template pop-up window steps to select wallet card template navigate to the select wallet card template option within the portal in the wallet card type drop-down menu, select the category that best suits your use case e g , boarding pass, ticket, coupon, or digital id once the card type is selected, a list of templates will appear in the wallet card sub type section choose one of the available templates from the list that corresponds to your selected card type after selecting the template, you can proceed with configuring the card’s details, including the branding, content, and data fields specific to the selected template samsung wallet supports various wallet card types designed to cater to different use cases each card type is optimized for specific functions, making it easier for partners to provide a seamless experience to users note-refer to section wallet card type to learn more about it view wallet cards partners can easily manage all their registered wallet cards through the samsung wallet portal this includes the ability to view, edit, and delete wallet cards as needed step 2 - launch wallet cards verifying status once a wallet card is ready for launch, it must go through the verifying status before it can be activated and made available to users partners can launch and activate their cards once they have been reviewed and approved, ensuring the card meets all requirements steps to launch wallet cards to begin the launch process, click yes to confirm and approve the activation of the wallet card to begin the activation process, click the launch button for the card you wish to activate once a card is launched, the button text changes to launched the activation cannot be cancelled after the card is launched, its status will change to verifying during this stage, the system will conduct a final review to ensure all information is accurate and meets the necessary requirements after verification, the card will undergo administrator approval the admin will review and approve the card for activation once the card is approved by the administrator, its status will change to active, making it available for users to add to their samsung wallet launch wallet cards rejected status if the wallet card is rejected after launching, you can modify the card and re-launch steps to modify the card and re-launch the administrator registers the reason for rejection when rejecting the launched wallet card it is sent to the partner by email from the system, including the reason for rejection partners can apply for launch again by checking the reason for rejection and modifying the wallet card information step 3 – testing mode partners can use the testing mode to test a wallet card internally before it is officially released to users this feature ensures that all aspects of the card, including its functionality and user experience, are working as expected when you create a new wallet card, the testing mode option is enabled by default, allowing you to perform internal tests without affecting user access all data generated during testing is periodically deleted to ensure that no test data remains in the system once testing is complete even though testing mode is enabled, the card is still visible and accessible in the system testing does not prevent the card from being exposed to users, so you can verify its functionality without any restrictions once testing is complete and you are satisfied with the card’s performance, be sure to turn off testing mode note-remember to change the status from testing mode on to testing mode off to finalize the testing process and prepare the card for official release step 4 - admin approval active status after a wallet card is launched, it must go through an administrator approval process before it becomes active and visible to users steps for admin approval once the launch button is clicked, the card’s status automatically changes to verifying during this stage, the card is reviewed for accuracy, completeness, and compliance with samsung wallet requirements note-please ensure that testing is completed using either your own implementation or the add to wallet test tool, as the samsung wallet administrator will verify the results through server-side test logs an administrator will review the submitted wallet card to ensure it meets all content and technical guidelines if the card passes the review, it is approved for activation upon administrator approval, the card status updates 'active' once the card reaches active status, it becomes visible and accessible to end users, enabling them to add it to their wallets step 5 – add to samsung wallet integration to integrate the "add to samsung wallet" feature into your system, you need to insert the appropriate "add to wallet" script this script is available for various platforms, including web, android, and email/mms, and each platform requires a slightly different implementation approach follow the steps below to successfully implement the "add to wallet" button create the tokenized card data, known as cdata, which contains the actual wallet card content note-since cdata has a time-to-live ttl of 30 seconds, it is recommended that the system generates cdata in real time to ensure it remains valid when processed the cdata format varies depending on the card type e g , loyalty card, ticket, coupon refer to the cdata generation sample code on the partners portal for detailed guidance copy the sample ‘add to wallet’ script from partners portal’s wallet card page replace the placeholder "cdata" in the script with your generated tokenized card data apply the script to your system see partners portal’s wallet card for details note-for "add to wallet" integration, you may need some base data you can find that and other necessary information on partners portal and wallet api spec you can also add image beacon in the script for tracking effect analysis add to wallet script guide wallet card types wallet card type boarding pass ideal for airlines, train services, or event check-ins allows users to add their travel or event tickets to samsung wallet for easy access and quick scanning wallet card type tickets designed for digital tickets to events such as concerts, movies, sports games, or other events ensures smooth entry by providing users with a digital copy of their ticket directly on their device wallet card type coupons perfect for promotional offers, discount vouchers, gift cards, or loyalty rewards users can redeem or use these coupons directly from their samsung wallet, making the process faster and more efficient wallet card type digital id used for membership cards, loyalty programs, and identification purposes can store digital versions of cards like gym memberships, library cards, or other forms of identification wallet card type gift card digital versions of physical gift cards, which users can add to their samsung wallet for quick and easy access useful for retail, online stores, and various gift card services wallet card type loyalty card designed for businesses offering loyalty programs where customers earn points for purchases or engagement users can view their point balance, check available rewards, and redeem points directly from their samsung wallet
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.