Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials mobile
blogare you a company looking to enhance your users' experience by allowing them to add digital content such as tickets, coupons, or boarding passes to samsung wallet? or perhaps you're an online merchant interested in integrating samsung pay as a secure payment option for your customers? look no further! the samsung wallet partner portal is the perfect solution for your needs. the samsung wallet partner portal is a dedicated platform designed for companies who wish to collaborate with samsung wallet. by becoming a partner, you'll gain access to a wide range of services and resources that will enable you to seamlessly integrate your digital content or payment systems with samsung wallet. how to become a partner to become a partner and start collaborating with samsung wallet, simply visit the samsung wallet partner portal and follow the onboarding process. once registered, you'll gain access to the portal's features and resources, allowing you to start integrating your digital content. to help you better understand the partner portal onboarding process and usage, we've prepared a tutorial video for you: notethe tutorial video also has a helpful guide for online merchants interested in integrating secure samsung pay functionalities into their mobile app or website. don't miss out on new business opportunities by joining the samsung wallet partner portal now! if you have any further questions, submit a support request or join the forum. for more information, please refer to the following resources: samsung wallet for partner samsung pay for partner
tutorials
blogsamsung wallet partners can create and update card templates to meet their business needs through the wallet partners portal. however, if the partner has a large number of cards, it can become difficult to manage them using the wallet partners portal website. to provide partners with more flexibility, samsung provides server apis so that partners can easily create and modify samsung wallet card templates without using the wallet partners portal. with these apis, partners can also create their own user interface (ui) or dashboard to manage their cards. in this article, we implement the add wallet card templates api to create a card template for a coupon in the wallet partners portal. we focus on the api implementation only and do not create a ui for card management. prerequisites if you are new to samsung wallet, complete the onboarding process and get the necessary certificates. as a samsung wallet partner, you need permission to use this api. only authorized partners are allowed to create wallet card templates using this api. you can reach out to samsung developer support for further assistance. api overview the rest api discussed in this article provides an interface to add wallet card templates directly from the partner's server. this api utilizes a base url, specific headers, and a well-structured body to ensure seamless integration. url: this is the endpoint where the request is sent to create a new wallet card template. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template headers: the information provided in the headers ensures secure communication between the partner's server and samsung's server. authorization: the bearer token. see the json web token documentation for details. x-smcs-partner-id: this is your partner id. the partner id gives you permission to use the api. x-request-id: use a randomly generated uuid string in this field. body: the body must be in the jwt token format. convert the payload data (card template in json format) into a jwt token. for more details about the api, refer to the documentation. implementation of the api to create a card template the add wallet card templates api allows you to add a new card template to the wallet partners portal. you can also create the card in the portal directly, but this api generates a new card template from your server, without requiring you to launch the wallet partners portal. follow these steps to add a new card template. step 1: extracting the keys extract the following keys from the certificates. these keys are used while generating the jwt token. rsapublickey partnerpublickey = (rsapublickey) readpublickey("partner.crt"); rsapublickey samsungpublickey = (rsapublickey) readpublickey("samsung.crt"); privatekey partnerprivatekey = readprivatekey("private_key.pem"); extracting the public keys use the following code to extract the partner public key and the samsung public key from the partner.crt and samsung.crt certificate files, respectively. you received these certificate files during the onboarding process. private static publickey readpublickey(string filename) throws exception { // load the certificate file from resources classpathresource resource = new classpathresource(filename); try (inputstream in = resource.getinputstream()) { certificatefactory certfactory = certificatefactory.getinstance("x.509"); x509certificate certificate = (x509certificate) certfactory.generatecertificate(in); return certificate.getpublickey(); } } extracting the private key the following code extracts the private key from the .pem file you generated during the onboarding process. this key is needed to build the auth token. private static privatekey readprivatekey(string filename) throws exception { string key = new string(files.readallbytes(new classpathresource(filename).getfile().topath())); key = key.replace("-----begin private key-----", "").replace("-----end private key-----", "").replaceall("\\s", ""); byte[] keybytes = base64.getdecoder().decode(key); keyfactory keyfactory = keyfactory.getinstance("rsa"); return keyfactory.generateprivate(new pkcs8encodedkeyspec(keybytes)); } step 2: generating the authorization token samsung's server checks the authorization token of the api request to ensure the request is from an authorized partner. the authorization token is in the jwt format. follow these steps to create an authorization token: building the auth header create an authheader. set “auth” as its payload content type to mark it as an authorization token. as you can create multiple certificates, use the corresponding certificate id of the certificate that you use in the project. you can get the certificate id from “my account > encryption management” of the wallet partners portal. // create auth header jsonobject authheader = new jsonobject(); authheader.put("cty", "auth"); authheader.put("ver", 3); authheader.put("certificateid", certificateid); authheader.put("partnerid", partnerid); authheader.put("utc", utctimestamp); authheader.put("alg", "rs256"); creating the payload create the payload using the authheader. follow this code snippet to create the payload. // create auth payload jsonobject authpayload = new jsonobject(); authpayload.put("api", new jsonobject().put("method", "post").put("path", "/partner/v1/card/template")); authpayload.put("refid", uuid.randomuuid().tostring()); building the auth token finally, generate the authorization token. for more details, refer to the “authorization token” section of the security page private static string generateauthtoken(string partnerid, string certificateid, long utctimestamp, privatekey privatekey) throws exception { // create auth header // create auth payload // return auth token return jwts.builder() .setheader(authheader.tomap()) .setpayload(authpayload.tostring()) .signwith(privatekey, signaturealgorithm.rs256) .compact(); } step 3: generating a payload object token the request body contains a parameter named “ctemplate” which is a jwt token. follow these steps to create the “ctemplate.” creating the card template object select the proper card template you want to create from the card specs documentation. get the payload object as json format. now create the jsonobject from the json file using the following code snippet. // creating card template object jsonobject cdatapayload = new jsonobject(); cdatapayload.put("cardtemplate", new jsonobject() .put("prtnrid", partnerid) .put("title", "sample card") .put("countrycode", "kr") .put("cardtype", "coupon") .put("subtype", "others") .put("saveinserveryn", "y")); generating the jwe token create the jwe token using the following code snippet. for more details about the jwe format, refer to the “card data token” section of the security page. // jwe payload generation encryptionmethod jweenc = encryptionmethod.a128gcm; jwealgorithm jwealg = jwealgorithm.rsa1_5; jweheader jweheader = new jweheader.builder(jwealg, jweenc).build(); rsaencrypter encryptor = new rsaencrypter((rsapublickey) samsungpublickey); jweobject jwe = new jweobject(jweheader, new payload(string.valueof(cdatapayload))); try { jwe.encrypt(encryptor); } catch (joseexception e) { e.printstacktrace(); } string payload = jwe.serialize(); building the jws header next, follow this code snippet to build the jws header. set “card” as the payload content type in this header. // jws header jwsheader jwsheader = new jwsheader.builder(jwsalgorithm.rs256) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", 3) .customparam("certificateid", certificateid) .customparam("utc", utctimestamp) .build(); building the jws token generate the jws token from the previously generated jwe token and, finally, get the “ctemplate” jwt. follow the “jws format” section of the security page. private static string generatecdatatoken(string partnerid, publickey partnerpublickey, publickey samsungpublickey, privatekey partnerprivatekey, string certificateid, long utctimestamp) throws exception { // creating card template object // jwe payload generation // jws header // jws token generation jwsobject jwsobj = new jwsobject(jwsheader, new payload(payload)); rsakey rsajwk = new rsakey.builder((rsapublickey) partnerpublickey) .privatekey(partnerprivatekey) .build(); jwssigner signer = new rsassasigner( ); jwsobj.sign(signer); return jwsobj.serialize(); } step 4: building the request as all of the required fields to create the request have been generated, you can now create the request to add a new template. follow the code snippet to generate the request. private static request buildrequest(string endpoint, string partnerid, string requestid, string authtoken, string cdatatoken) { // prepare json body jsonobject cdatajsonbody = new jsonobject(); cdatajsonbody.put("ctemplate", cdatatoken); requestbody requestbody = requestbody.create( mediatype.parse("application/json; charset=utf-8"), cdatajsonbody.tostring() ); // build http request request request = new request.builder() .url(endpoint) .post(requestbody) .addheader("authorization", "bearer " + authtoken) .addheader("x-smcs-partner-id", partnerid) .addheader("x-request-id", requestid) .addheader("x-smcs-cc2", "kr") .addheader("content-type", "application/json") .build(); return request; } step 5: executing the request if the request is successful, a new card is added to the wallet partners portal and its “cardid” value is returned as a response. private static void executerequest(request request) { // execute http request try (response response = client.newcall(request).execute()) { if (response.issuccessful()) { system.out.println("wallet card template added successfully: " + response.body().string()); } else { system.out.println("failed to add wallet card template: " + response.body().string()); } } } implement as a server at this point, you can add a webpage ui for creating card templates and deploy it as a web service. in this sample project, there is no ui added. but, you can deploy this sample as a web service and test it. conclusion this tutorial shows you how you can create a new samsung wallet card template directly from your server by using a rest api. now that you can implement the api, you can add a ui and make it more user-friendly. also implement the updating wallet cards templates api for better card management. references for additional information on this topic, refer to the resources below: sample project code. business support for special purposes documentation.
M. A. Hasan Molla
tutorials
blogintroduction smartphones have become an essential part of our everyday lives. users are continually searching for more convenient ways to perform their tasks on their smartphones, driving them toward services with greater usability. as smartphones advance, our lives become simpler. galaxy users have completely embraced the convenience of paying with samsung pay, and no longer carry physical payment cards. this led to the evolution of samsung pay into samsung wallet, incorporating biometric-authentication-based security solutions and adding various features to replace conventional wallets. since june 2022, samsung wallet has been expanding its service area based on the existing samsung pay launching countries. this article aims to introduce samsung wallet and guide you through the integration process of the "add to samsung wallet" feature, which allows you to digitize various content and offer them as wallet cards. notice this article introduces non-payment service cards. if you want to learn more about the payment service of samsung wallet, visit the samsung pay page. you can get information on online payment services such as in-app payments, web checkout, and w3c payments. add to samsung wallet service let's delve deeper into the "add to samsung wallet" feature. digitized content registered in samsung wallet comes in the form of cards called wallet cards. registering a wallet card is effortless: simply click the "add to samsung wallet" button, and the card is stored securely on users’ galaxy smartphones. "add to samsung wallet" button and wallet card notice the benefits of using wallet cards can be found in the commercial video forgetting can be awesome. wallet cards the "add to samsung wallet" service is an open platform that supports offering various types of content such as wallet cards. we are streamlining service integration with content providers across different regions and adding useful features. boarding pass event ticket loyalty gift card coupon id card generic card pay as you go (in progress) reservation (in progress) digital key (in progress) notice generic card supports unstructured forms of cards. be a samsung wallet partner partner onboarding to begin offering content through samsung wallet, you must first register as a partner on the samsung wallet partner portal. the integration process is detailed on the samsung developer portal. to join the samsung wallet partner portal, create a samsung account that is used as the service administrator. wallet card management once enrolled, you can create service cards on the wallet cards menu. each card is assigned a card id representing the service, and you can set the card type and linking information. you can manage cards according to their status – test or live. configuring wallet card notice after completing all required forms for the wallet card, click the launch button to request card activation. before providing the service to actual users, remember to turn off the 'test mode.' how to safely secure user data key generation and certificate request the registration process includes certificate exchange to securely transmit service data. refer to the diagram and developer guide, security key & certificate creation guide, to complete the certificate registration and partner enrollment smoothly. certificates exchange process ensuring data security to prevent forgery and leakage of user card data, secure tokenization processing is required. json web token (jwt), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. in particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used. process of generating and verifying security tokens notice depending on how partners provide content services to users, you can choose how to deliver data to the samsung wallet service. two ways to transfer wallet card data add to samsung wallet interface provides two methods for partners to deliver users digital content as wallet cards. data transmit link the general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the samsung wallet service when the user clicks the button. as long as samsung wallet support is confirmed, you can generate a link containing the user's card data and configure the "add to samsung wallet" button to run the link when pressed, either on an application or web page. data transmit process data fetch link another method to transfer wallet card data is to include only the refid, which represents the user's content, in the "add to samsung wallet" link and transmit it to the samsung wallet service. when a user clicks the "add to samsung wallet" button, samsung servers refer to the get card data api information set on the wallet card and retrieve user content using the received refid to complete registration. data fetch process this method is suitable for providing user's data through email or mms messages where static links cannot be avoided. there is an option to secure these static links. data fetch process for static links setting up data synchronization on the partner portal, you can set up the wallet card information and configure the server interaction api that the content provider needs to prepare. this api is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on samsung wallet. register wallet cards when a user card is added to samsung wallet, samsung wallet servers use the send card state api to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with samsung wallet. when a wallet card is registered, added event is sent to the partner's server update wallet cards changes to the synchronization target content can be notified to the samsung wallet service through the update notification api. here, the value that distinguishes each piece of content is the refid that the partner must provide when registering the users’ wallet card. through the get card data api, samsung wallet servers can check the latest content information any time. if updates occur on the partner's side, updated event notifications should be sent to the samsung server in case users withdraw content from the partner's side in case users delete cards from samsung wallet notice both servers should verify requests using the authorization header of the api request. this authorization token is in jwt format, familiar from card data security. effortless wallet card registration with just one click this feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or mms message. various service channels javascript library for web developers we provide a javascript library and a user guide, implement the button, to help integrate your web pages. creating buttons and links in your app for configuring buttons in applications, utilize the button image resources. providing services via mms, email, or qr codes to provide services through fixed links, check out the details of the data fetch link. these static links can also be used by scanning qr codes. experience the service and practice you can experience service integration development using the codelab and use the testing tool to preregister the wallet cards created on the partner portal, which could be helpful. conclusion we've looked at how to provide digital content through the "add to samsung wallet" feature. we continuously update the guides on the developer portal, so please refer to them when preparing for integration. summary the "add to samsung wallet" service welcomes participation from content service partners and developers. for inquiries or technical support, please contact us through the form provided on the developer portal. i hope this post has been helpful, and now i'll conclude my writing here. thank you. this post was written based on the sdc23 korea session.
Choi, Jonghwa
tutorials
blogcard template management is a crucial task for partners in the samsung wallet ecosystem that is typically handled through the wallet partners portal. manually altering numerous existing templates via the web interface can be inefficient and challenging. samsung provides a set of server-side apis to address this, allowing partners to programmatically manage and modify their card templates for greater operational agility. using these apis enables partners to integrate update capabilities directly into their own ecosystems. this automation facilitates the seamless maintenance of card offerings, helping partners keep their content dynamic and up-to-date. as a partner, this article walks you through the implementation of the update wallet card template api specifically using python. if you are a java developer or want to implement the add wallet card template api, you can follow the previous content on creating samsung wallet card templates. noteto follow this article, you'll need an existing card template and its cardid. make sure you have completed the samsung wallet onboarding to obtain the necessary certificates. also, you need permission to use this api. only permitted partners can use this api. api overview this section details the rest api designed for modifying a pre-existing wallet card template, enabling direct updates from a partner's server. endpoint url: direct requests to modify a card template to the following url. it is imperative to substitute {cardid} with the identifier of the specific card template you intend to alter. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{cardid} request headers: secure interaction with this api is restricted to authenticated partners. the headers detailed below are vital for establishing a secure and validated communication channel with the samsung server. authorization: this field must contain the bearer token. for comprehensive information, consult the json web token documentation. x-smcs-partner-id: this field must be populated with your unique partner identifier. x-request-id: a universally unique identifier (uuid) is required here, freshly generated for each request. request body: the payload of the request needs to be structured as a json object. this object must include a key named ctemplate, with its value being a jwt token. this specific jwt securely contains the complete data for the revised card template. for a deeper dive into the api specifications, check the official documentation. implementing the api to create a card template the update wallet card template api enables partners to modify existing card templates in the wallet partners portal. in this section, we implement python code to update a coupon card template, for example, by changing its title. extracting the keys from certificates extract the public and private keys from the certificate files obtained during the onboarding process. def getpublickey(crt_path): """ extract publick key from a .crt file. """ try: with open(crt_path, "rb") as f: crt_data = f.read() certificate = x509.load_pem_x509_certificate(crt_data, default_backend()) public_key = certificate.public_key() public_key_pem = public_key.public_bytes( encoding=serialization.encoding.pem, format=serialization.publicformat.subjectpublickeyinfo ) return jwk.jwk.from_pem(public_key_pem) except exception as error: print(f"error reading public key from {crt_path}: {error}") return none def getprivatekey(pem_path): ''' extract private key from a .pem file. ''' try: with open(pem_path, "rb") as pem_data: private_key = serialization.load_pem_private_key( pem_data.read(), password = none, backend = default_backend() ) return private_key.private_bytes( encoding=serialization.encoding.pem, format=serialization.privateformat.pkcs8, encryption_algorithm=serialization.noencryption() ) except exception as error: print(f"error reading private key from {pem_path}: {error}") return none generating the authorization token the samsung server uses a jwt format token to verify if the request is from an authorized partner. follow these steps to create an authorization token. create an authorization token header. set the payload content type to ‘auth’ since this is an authorization token. create the payload using the authorization token header. generate the authorization token. the following code snippet demonstrates these steps. def generateauthtoken(partnerid, certificateid, utctimestamp, privatekey, cardid): auth_header = { "cty": "auth", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, "alg": "rs256" } auth_payload = { "api": { "method": "post", "path": f"/partner/v1/card/template/{cardid}" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token generating a payload object token the request body includes a parameter named ctemplate, which is also a jwt token. create the jwt token using the following code snippet. def generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data): jwe_header = { "alg": "rsa1_5", "enc": "a128gcm" } jwe_token = jwe.encrypt( data, samsungpublickey, encryption=jwe_header["enc"], algorithm=jwe_header["alg"] ) print(f"jwe_token: \n{jwe_token}\n") jws_header = { "alg": "rs256", "cty": "card", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, } jws_token = jws.sign( jwe_token, key=partnerprivatekey, algorithm='rs256', headers=jws_header ) print(f"jws_token: \n{jws_token}\n") return jws_token building and executing the request build and send the http request to the specified update endpoint. add all fields that you want to modify in the ’cdatapayload’ object. refer to the documentation to identify the fields that you can modify. def main(partnerid, cardid, certificateid, utctimestamp, requestid, endpoint): partnerpublickey = getpublickey("../cert/partner.crt") print(f"partnerpublickey {partnerpublickey}") samsungpublickey = getpublickey("../cert/samsung.crt") print(f"samsungpublickey {samsungpublickey}\n") partnerprivatekey = getprivatekey("../cert/private_key.pem") print(f"partnerprivatekey {partnerprivatekey}\n") authtoken = generateauthtoken(partnerid, certificateid, utctimestamp, partnerprivatekey, cardid) print(f"authtoken {authtoken}\n") cdatapayload = {} # --- add data here that you want to update. cdatapayload["cardtemplate"] = { "title": "update card tile", "countrycode": "kr", "saveinserveryn": "y" } data = json.dumps(cdatapayload).encode('utf-8') cdatatoken = generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data) print(f"cdatatoken: \n{cdatatoken}\n") # --- prepare json body (python dictionary) --- c_data_json_body = { "ctemplate": cdatatoken } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "x-smcs-cc2": "kr", "content-type": "application/json" } # --- execute http request --- try: response = requests.post(endpoint, json=c_data_json_body, headers=headers) response.raise_for_status() print("wallet card template updated successfully: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to update wallet card template:") print(f"error: {e}") if response: print("response body:", response.text) running the application download the sample project and open it with any ide, then follow this process. configure: update ‘partner_id’, ‘certificate_id’, and, crucially, ‘card_id_to_update’ in src/main.py with your actual credentials and the id of the card you need to modify. place certificates: ensure your partner.crt, samsung.crt and private_key.pem files are in the cert/ directory. install dependencies: install all the required dependencies from the requirements.txt file. pip install -r requirements.txt execute: run the main script from the terminal. python src/main.py if the request is successful, the specified card template in the wallet partners portal is updated. the api returns the updated card id with a success status, otherwise it returns an error. find all the status codes in the '[result]' section of the documentation. wallet card template updated successfully: { "cardid": "cardid", "resultcode": "0", "resultmessage": "update_success" } conclusion by implementing the api to update an existing samsung wallet card template through this article, you can now automate and streamline the management of your card templates, ensuring that they always reflect the latest information. references for additional information on this topic, refer to the resources below. sample project code create samsung wallet card templates using the server api business support for special purposes documentation
M. A. Hasan Molla
tutorials digital payments
blogthis article demonstrates how to integrate samsung pay in-app payments into your android application, covering everything from account setup to release. follow these steps to ensure a smooth integration process so you can start accepting payments with samsung pay quickly. figure 1: steps of implementing samsung pay set up and configure samsung pay register as a partner to begin accepting payments through samsung pay, first you need to register as a samsung pay partner and complete your samsung pay developer profile. visit the samsung account website go to the samsung account web site and do one of the following: if this is your first time on the site, click “create account” at the top right corner to create an account. for a smooth approval, use a business email (not personal) for registering your account. if you already have a samsung account, simply log in. complete your developer profile follow these steps to enable your samsung pay developer account: go to the samsung pay developer portal and log in with a business account. become a pay partner by creating a business account. provide appropriate data which exactly matches your business and legal documents. read the terms and conditions carefully and accept them. submit your partnership request. the approval process generally takes a few days. if you encounter any issues, please contact developer support for assistance. configure your service and app while working with the samsung pay, you will encounter the terms “service” and “app.” let’s unpack them below. understanding services and apps service: an interface to the samsung pay system that provides the payment facilities. the service talks with the samsung pay system and collaborates with the partner system and payment gateway for processing payments. app: an app works like a bridge between the service and the partner application. the app ensures the communication and security between the partner application and the service. create an in-app payment service to create an in-app payment service, from the samsung pay partner portal, follow the steps below: select service management, under my projects in the top-right corner menu, in the service management screen, click create new service. select the in-app online payment service type, then click save and next. enter the service information, attach a valid csr file for secure payment, and then click save and next. fill in the required details to define your in-app service. if you have created one previously, you can also use it instead. then click save and next to advance to the next step. define a tentative debug date by clicking generate new date. click add samsung account to add the samsung accounts that will be used for testing purposes. click done. figure 2: creating an in-app payment service this completes the creation of your service and links it with your application. wait for it to be approved. the team will contact you promptly once your request has been processed. in case of any delays, feel free to reach out to 1:1 support for assistance. samsung pay feature development now that your partner account set up is complete, it's time to integrate samsung pay functionality into your android application. next we will integrate the samsung pay sdk and implement core payment features to enable seamless in-app transactions in your app. download and add the sdk go to the downloads page in samsung pay and scroll down to the android section to download the samsung pay sdk. sdk components the samsung pay sdk has the following components: java library (samsungpay_x.xx.xx.jar): contains the classes and interfaces to integrate with the samsung pay. sample apps: demonstrates the implementation of samsung pay apis to simplify the process of building your own. add the sdk to your project create a folder called ‘libs’ if one does not already exist, and move the sdk .jar file into this folder. /app ├── libs/ │ └── samsungpay_x.xx.xx.jar ├── src/main/ │ ├── kotlin/ │ ├── res/ │ └── androidmanifest.xml configure gradle and dependencies update settings.gradle.kts add the ‘libs’ folder with the other repositories, if it is not there already. dependencyresolutionmanagement { repositories { google() mavencentral() flatdir { dirs 'libs' } } } add the sdk dependency in app/build.gradle.kts add the samsung pay sdk as a dependency for your application. dependencies { implementation(files("libs/samsungpay_x.xx.xx.jar")) } sync the gradle to apply the changes. configure android app manifest add the following configurations in your androidmanifest.xml. this ensures the compatibility and proper functioning of your application. add the element <queries> <package android:name="com.samsung.android.spay" /> </queries> add metadata <meta-data android:name="spay_sdk_api_level" android:value="2.xx" /> <!-- latest version is recommended] --> implement functionality now that the samsung pay sdk integration is complete, let us use this sdk to implement the complete functionality of the samsung pay sdk in your android application. here we will go through the complete flow of initiating a payment using the samsung pay sdk. check samsung pay availability initiating a payment starts by checking if samsung wallet is available for payment or not. initialize the samsung pay service with your partner credentials, then verify if samsung pay is supported. if available, display the samsung pay button in your app. val serviceid = "partner_service_id" val bundle = bundle() bundle.putstring(samsungpay.partner_service_type, samsungpay.servicetype.inapp_payment.tostring()) val partnerinfo = partnerinfo(serviceid, bundle) val samsungpay = samsungpay(context, partnerinfo) samsungpay.getsamsungpaystatus(object : statuslistener { override fun onsuccess(status: int, bundle: bundle) { when (status) { samsungpay.spay_not_supported -> samsungpaybutton.setvisibility(view.invisible) samsungpay.spay_not_ready -> { samsungpaybutton.setvisibility(view.invisible) val errorreason = bundle.getint(samsungpay.extra_error_reason) if (errorreason == samsungpay.error_setup_not_completed) samsungpay.activatesamsungpay() else if (errorreason == samsungpay.error_spay_app_need_to_update) samsungpay.gotoupdatepage() } samsungpay.spay_ready -> samsungpaybutton.setvisibility(view.visible) } } override fun onfail(errorcode: int, bundle: bundle) { samsungpaybutton.setvisibility(view.invisible) log.d(tag, "checksamsungpaystatus onfail() : $errorcode") } }) set up payment details and request the payment after the availability check is completed, you need to set up the payment details such as merchant information, transaction information, order number, and so on, before requesting the payment. the following code snippets show how to accomplish this. make customsheet create a simple custom payment sheet with amounts and items for the transaction. this sheet will be displayed during the payment process. you can customize the sheet according to your requirements. private fun makeupcustomsheet(): customsheet { val amountboxcontrol = amountboxcontrol(amount_control_id, mbinding.currency.selecteditem.tostring()) amountboxcontrol.additem( product_item_id, mcontext.getstring(r.string.amount_control_name_item), mdiscountedproductamount, "" ) amountboxcontrol.additem( product_tax_id, mcontext.getstring(r.string.amount_control_name_tax), mtaxamount + maddedbillingamount, "" ) amountboxcontrol.additem( product_shipping_id, mcontext.getstring(r.string.amount_control_name_shipping), mshippingamount + maddedshippingamount, "" ) amountboxcontrol.setamounttotal(totalamount, amountformat) val sheetupdatedlistener = sheetupdatedlistener { controlid: string, sheet: customsheet -> log.d(tag, "onresult control id : $controlid") updatecontrolid(controlid, sheet) } val customsheet = customsheet() customsheet.addcontrol(amountboxcontrol) return customsheet } make customsheetpaymentinfo create payment information with merchant details, order number, and card brand preferences. private fun maketransactiondetailswithsheet(): customsheetpaymentinfo { // get brandlist (supported card brands) val brandlist = getbrandlist() val customsheetpaymentinfo: customsheetpaymentinfo val customsheetpaymentinfobuilder = customsheetpaymentinfo.builder() customsheetpaymentinfobuilder.setaddressinpaymentsheet(mrequestaddressoptions.requestaddresstype) customsheetpaymentinfo = customsheetpaymentinfobuilder .setmerchantid("your_merchant_id") .setmerchantname("your_merchant_name") .setordernumber("your_order_number") .setaddressinpaymentsheet(customsheetpaymentinfo.addressinpaymentsheet.do_not_show) .setallowedcardbrands(brandlist) .setcardholdernameenabled(mbinding.cardbrandcontrol.displaycardholdername.ischecked) .setcustomsheet(makeupcustomsheet()) .build() return customsheetpaymentinfo } request the payment initiate the samsung pay payment process with transaction details and handle payment callbacks. mpaymentmanager.startinapppaywithcustomsheet( maketransactiondetailswithsheet(), object : customsheettransactioninfolistener{ override fun oncardinfoupdated( selectedcardinfo: cardinfo?, sheet: customsheet? ) { // update your controls if needed based on business logic for card information update. // updatesheet() call is mandatory pass the updated customsheet as parameter. try { paymentmanager.updatesheet(customsheet) } catch (e: java.lang.illegalstateexception) { e.printstacktrace() } catch (e: java.lang.nullpointerexception) { e.printstacktrace() } } override fun onsuccess( customsheetpaymentinfo: customsheetpaymentinfo?, paymentcredential: string?, extrapaymentdata: bundle? ) { // triggered upon successful payment, providing customsheetpaymentinfo and paymentcredential. // for example, you can send the payment credential to your server for further processing with pg. or you could send it directly to the pg as per business need. sendpaymentdatatoserver(paymentcredential) } override fun onfailure(errcode: int, errordata: bundle?) { // fired when the transaction fails, offering error codes and details. log.d(tag, "onfailure() : $errcode") showerrordialog(errcode, errordata) } }) testing and release test and validate to ensure a seamless and reliable integration of samsung pay, thorough testing is essential. this process validates transaction performance and guarantees a positive user experience for making a robust business impact. testing goes beyond error detection; it aims to comprehensively assess the quality and functionality of your samsung pay integration. release after successful testing, the next step is to secure release version approval from samsung through the samsung pay developers portal. once approved, your application can be launched, allowing you to monitor user satisfaction and optimize performance. conclusion by integrating samsung pay in-app payments, you’ve enabled secure, convenient transactions for samsung pay users. this implementation expands your payment options while providing a seamless checkout experience. additional resources for additional information on this topic, refer to the resources below. samsung pay faqs samsung pay in-app payment documentation
Yasin Hosain
featured
bloghave you heard the news about samsung galaxy unpacked 2023, which was announced on the samsung developers portal and global channels? if you’ve received an email invitation to galaxy unpacked 2023, scheduled for july 26, add it to samsung wallet for a quick and convenient way to enter the event hall. the "add to samsung wallet" service enables samsung device users to clip and save a variety of digital content, such as tickets, coupons, boarding passes, membership cards, to samsung wallet for easy access. “add to samsung wallet” allows them to do this conveniently without having to leave the other online channels they are using, such as an application, website, email, or sms/mms message. smart ways to use "add to samsung wallet" 1. add your galaxy unpacked 2023 invitation on july 26, expect new, wonderful, and innovative android tablets, smart watches, and the most anticipated of all, 5th-generation foldable phones, to be revealed at galaxy unpacked 2023. you can also attend galaxy unpacked remotely by watching the real-time live stream on the samsung electronics website and youtube channel. try adding the invitation and entrance ticket for galaxy unpacked 2023 to samsung wallet for ease and convenience. open the email invitation on your galaxy mobile device and tap "add to samsung wallet" to add your ticket. 2. add other event tickets “add to samsung wallet” also supports different kinds of tickets, such as to movies, sports events, and concerts. the related apis allow you to implement the feature for your service, checking whether the user’s device supports samsung wallet and if so, enabling the "add to samsung wallet" button. for example, a tourist in france can add their tickets to exhibitions at the atelier des lumières art museum in paris and to the bassins de lumières in bordeaux to samsung wallet using the "add to samsung wallet" button (provided by splio). 3. add content from other services “add to samsung wallet” is not only for tickets! the "add to samsung wallet" feature also works with other content issued by our partners, such as boarding passes, coupons and membership cards: • add or register your boarding pass to samsung wallet to get push notifications for your boarding time and speed through the boarding process. • add coupons collected from various channels, including sms, mms and email, to samsung wallet. you can receive notifications and keep track of their validity. to learn more, see samsung wallet. special features for event tickets in samsung wallet • optional policy to prevent misuse of tickets • group ticket layout that presents multiple barcodes or qr codes in a single ticket • batch update the status for all tickets, for example, when an event is canceled or postponed; this feature requires the partner to share the relevant information. • provide up to 2 barcodes or qr codes for extra services at your event, such as coupons for snacks or parking, in addition to the barcode or qr code for the ticket itself • push notifications sent 1 hour before the event begins integrate "add to samsung wallet" for your event tickets for a detailed description of the registration process, development specifications, and testing tools for integrating “add to samsung wallet” to your service, go to the samsung wallet partner portal (english language links below). the partner portal contains tutorials that walk you through the integration process step-by-step. step 1. register as a partner at the samsung wallet partner portal https://developer.samsung.com/wallet/onboarding.html step 2. create and manage samsung wallet cards https://developer.samsung.com/wallet/manage.html step 3. integrate “add to samsung wallet” to your service https://developer.samsung.com/wallet/api/overview.html if you are in a country where the event ticket menu is not supported on galaxy devices, contact us through developer support and we will help you as quickly as possible.
Hye-In Min
Develop Samsung Wallet
doconboarding guide the onboarding process for a partner manager on the wallet partner portal involves several steps to ensure that businesses or partners can effectively integrate their services into samsung wallet and begin offering digital cards, passes, loyalty programs, and other services to their customers onboarding process the following sections contain a description of the samsung wallet onboarding process for new partners the partner manager should fill basic information of the company and card details on partner portal, choose the card type and template that fit their contents, which will then provide keys such as card id and partner id to ensure safe data communication, make sure to prepare security key factors samsung will sign the provided csr then deliver certificates used to create the secured data samsung account is necessary to manage own service for samsung wallet the account is used to sign-up/sign-in on partner portal the following section contains the steps to register a new samsung account at the wallet partners portal navigate to the wallet partners portal and click the sign in button enter the email address and password in the form and click sign in note-if you do not have a samsung account yet, click on create account at the bottom to create an account if creating a new account, enter the account details email address, password, name, date of birth, and zip code , and then click next sign up signing up for the samsung wallet service involves registering a partner to access and utilize the features offered by samsung wallet to utilize full functionality of the samsung wallet partners service, a partner needs to enter company information, set encryption information, and configure card information after verification, the partner will get the authority to use all services the new partner of wallet partners portal is the samsung account will be conducted by samsung developer the new partners register to create business account and agree to the terms and conditions the partners complete the company profile information to onboard, create and manage business in wallet partner here’s a step-by-step guide for a new partner to sign up for the samsung wallet partners portal create business account - to use the wallet partners portal, one must create business account to get started, one must have a samsung developer business account this account is required to manage company’s digital assets and integrate services with samsung wallet accept the terms and conditions - to use wallet partners portal, review and accept the terms and conditions of the samsung developer portal ensure to read through the guidelines carefully, as they outline the rules for integrating business with samsung wallet verify account profile – complete the company profile information then enter the company name, company website, username etc additional information for the business account is optional, but providing detailed information will help with the registration process after filling out the required details, click submit to send the registration form for review welcome onboard - once the business account is created and the information is submitted; the wallet partner onboarding process is complete after completing the onboarding process, a welcome email confirming that the business has been successfully registered with the samsung wallet partners portal set encryption information and request permission setting encryption information involves configuring security measures to protect sensitive data during transactions and interactions within the samsung wallet partners portal encryption is used to secure the data being exchanged, preventing unauthorized access or interception once the encryption information is configured, one will need to request permission to access specific services within the samsung wallet partners portal permissions are necessary for performing operations such as adding or managing digital assets e g , cards, tickets, loyalty programs and accessing sensitive business data few points to remember only one account allowed per company manage the cards with one account for partners, one can only manage cards registered with the account multiple users with one account at same time is not allowed if someone else is signed in with the same account, the account in use will be signed out steps to set encryption information we need to perform encryption authentication to use the wallet partners portal create a csr that will request a digital certificate to be issued by a trusted authority we support multiple csr registrations if you click the + button, the csr registration area will be added if you click the - button, the csr registration area will be deleted go to the wallet partners portal and input the csr registration details item description encryption type select end to end encryption csr or none upload later csr csr certificate signing request the samsung public key is the key used for data encryption this can be used to issue and delete wallets csr is a file used to request signature of a certificate after uploading csr to the portal, csr will be signed using the samsung certificate please be careful not to expose samsung public key and csr due to security issues upload a * csr file only none upload later you need to set the encryption information csr to utilize the full functionality of samsung wallet service even if the subscription is done, you must upload the csr file later samsung public key samsung public key is sent to the partner’s email account signed certificate the signed certificate is sent to the partner’s email account complete encryption authentication to verify the correctness of the setup click done to submit the encryption information and complete the process a welcome email is sent when a user completes the sign-up process in addition, information required for the completion of csr is sent along with it security factors security factors refer to the various protocols and measures taken to secure the data and ensure the privacy and safety of the partners the service flow describes the series of steps or actions taken to complete a specific task in the wallet partners portal, from initial account creation to the use of services the service flow also ensures that data is handled securely csr certificate signing request process overview the certificate signing request csr process is critical for requesting a digital certificate from a certificate authority ca openssl, an open-source command-line tool, is commonly used to create the necessary files for csr generation and private key creation, which are essential to establish secure communication private key private key helps to enable encryption and is the most important component of certificates the private key should remain secure, as it is used for signing the csr and encrypting communication openssl genpkey -out domain key -algorithm rsa -pkeyopt rsa_keygen_bits 2048 note-if you want to make the private key more secure, adding ‘-des3’ on the command encrypts it with a password creating a certificate signing request the csr contains the public key and additional information such as the organization’s details this is required when a digital certificate is to be signed by a trusted certificate authority ca steps to create a csr from an existing private key open a terminal and use openssl to generate a csr domain csr using the existing private key openssl req -out domain csr -key domain key -new -sha256 it will also prompt you to provide csr information, such as a country name c the two-letter country code e g , us for the united states b state or province name st your state or province c locality name l your city or locality d organization name o your organization’s legal name e organizational unit ou optional the department or business unit within the organization f common name cn the domain name e g , www yourdomain com g email address email your contact email address you are about to be asked to enter information that will be incorporated into your certificate request what you are about to enter is what is called a distinguished name or a dn there are quite a f ew fields but you can leave some blank for some fields there will be a default value, if you enter ' ', the field will be left blank ----- country name 2 letter code [xx] kr state or province name full name [] seoul locality name eg, city [default city] sample city organization name eg, company [default company ltd] sample company organizational unit name eg, section [] sample section common name eg, your name or your server's hostname [] domain email address [] email@email com please enter the following 'extra' attributes to be sent with your certificate request a challenge password [] an optional company name [] once completed, the csr file domain csr will be generated note-‘password’ is optional attribute an important field is ‘common name’, which should be the exact fully qualified domain name fqdn of our domain creating a key and csr together both the private key and csr can be created with a single command openssl req -newkey rsa 2048 -nodes -keyout domain key -out domain csr note-if you want your private key encrypted, you can remove the ‘-nodes’ option for additional information https //en wikipedia org/wiki/public_key_certificate https //www openssl org my account the my account section in samsung wallet allows to manage profile, payment methods, security settings, and other account details navigate to the samsung wallet page, in top-right corner, select the my account section to manage the profile and encryption settings in this section, manage ‘wallet partner management’ to modify company information and manage the encryption settings note-after a signed certificate is generated, the encryption setting management fields can no longer be edited
Develop Samsung Wallet
docintroduction welcome to the samsung wallet cards integration guide samsung wallet is a secure and unified digital wallet solution designed for samsung galaxy devices, offering users a convenient way to store and manage a wide range of digital assets—including payment cards, loyalty memberships, travel tickets, coupons, digital ids, and more seamlessly integrated with samsung’s ecosystem, it enables contactless payments via samsung pay, supports biometric authentication for enhanced security, and allows for real-time interactions like push notifications and location-based reminders samsung wallet empowers partners and developers to deliver personalized, digital-first experiences while ensuring user data remains private and protected samsung wallet is an e-wallet service that allows users of samsung devices to securely store and access various digital items, such as credit cards, boarding passes, loyalty cards, and digital keys by combining multiple services into one platform, it streamlines everyday transactions and digital storage in a convenient and user-friendly interface users can add their ticket, coupon, boarding pass, and other types of data into samsung wallet using an add to wallet link via multiple online channels like app, web, e-mail, or social media messages benefits of samsung wallet cards service this document provides an overview for integration partners looking to enable digital items e g , tickets, coupons, and passes on samsung wallet this guide will walk you through the setup, onboarding, implementation, and management steps needed to launch your wallet-enabled services this document describes how to implement samsung wallet cards service features from the integration partner's point of view a partner account is a samsung developer account registered on the samsung wallet partners portal it allows samsung wallet partners to manage their wallet services, register card templates, access credentials partner id, card id , and communicate securely with samsung’s servers to integrate with samsung wallet cards, partners follow a structured process that enables their digital content—such as tickets, coupons, and passes—to be stored and managed in the samsung wallet app the implementation includes the following stages partner account setup to begin, the integration partner must create a samsung account and register as a service provider in the samsung wallet partners portal this account grants access to tools and resources needed for integration, including card management, api credentials, and documentation onboarding during onboarding, the partner submits basic company details, once submitted, samsung issues the following key integration credentials partner id card id certificates for secure communication via a signed csr these credentials are required for card generation, secure api calls, and managing wallet content add to samsung wallet integration the partner integrates the "add to samsung wallet" functionality into their digital platforms—such as apps, websites, or emails—by adding a button or link when end users click the button, the link triggers the process of creating and storing a digital card in samsung wallet partners can deliver content in two ways data transmit link encodes card content directly in a jwt json web token data fetch link samsung fetches the content from a partner's server upon user action each card is uniquely identified by a reference id refid reusing the same id updates the card silently wallet card management after cards are added to users' samsung wallet apps, the partner can manage them by interacting with samsung’s server apis this includes updating card content e g , time changes, status updates sending notifications for specific events cancelling or deleting cards receiving events via the send card state callback e g , when a user adds or removes a card these server-to-server communications ensure cards stay current and reflect real-time changes
tutorials web
blogthe previous tutorial, implementing "add to wallet" in an android application, showed how to generate and sign a card data token to add the card to samsung wallet. this tutorial demonstrates how you can perform server interactions with the samsung wallet server and retrieve information such as the card states on a user’s device. if you are a samsung wallet partner who is offering samsung wallet cards to your users, you might also want to know how you can track a provided wallet card’s status on a user’s device. follow along in this tutorial to learn how you can utilize the send card state api and retrieve this information to your own server. all code examples used in this tutorial can be found within the sample code provided at the end of this tutorial for further reference. card states and the send card state api the samsung wallet card’s status on a user’s device is represented by various states, such as added, updated, or deleted. whenever the card state of a card changes on a user’s device, samsung wallet server sends a notification to the configured partner server informing about the change. this api provided by samsung is called the send card state api. figure 1: samsung wallet card state changes samsung provides the send card state api as a means of server-to-server communication between the samsung server and the partner’s server and to let the partner know about the card state of their issued cards on user’s devices. with this api, partners can track the state of a wallet card on a user’s samsung galaxy device. prerequisites before you can test the send card state api, you need to: complete the samsung wallet onboarding process. create a samsung wallet card template. launch the wallet card template and have it in verifying or active status so that the card can be added to a user’s device. have an existing server to receive the notifications. you can use codesandbox or a similar online hosting service for testing. configure your firewall (if you use any) to accept incoming connections from the samsung wallet server (34.200.172.231 and 13.209.93.60). when you have completed all the prerequisites, proceed to the next step to configure your wallet card template to send requests to your server. configure the wallet card template for the send card state api to receive the send card state notifications on your server, you need to set your server’s url in the desired samsung wallet card’s options: go to the wallet partners portal. from the wallet cards dropdown, select “manage wallet card.” click the name of the wallet card. click “edit” and then scroll down to the “partner send card state” section to modify the partner server url. click “save” to set the partner server url for the card. figure 2: partner send card state url input field now, whenever a user adds or deletes an issued samsung wallet card to their device, the samsung wallet server automatically sends a post notification to the partner server url set in the wallet partners portal. next you need to learn about the specification of the request so that you can handle it from the server. send card state api specification and format for a complete description of the send card state api specification, see samsung wallet documentation. request method the send card state api uses a post method to send a request to the server. the api path for the request is fixed and uses the partner server url that you defined in section “configure the wallet card template for the send card state api.” api path and url parameters the api path at the very end of the "partner send card state" section is the path where the samsung server sends the send card state post request. so the complete api path url is: {partner server url}/cards/{cardid}/{refid}?cc2={cc2}&event={event}. here, cardid is the card id of the wallet card template and refid is the reference id field of the issued card data, which is a unique identifier. the cc2 query parameter is the 2-letter country code (iso 3166-1 alpha-2) and event is the card state event (added, deleted, or updated) occurring in the user’s device. consider the following example card configuration: partner server url: https://partner.server.url card id: 123 ref id for the issued card: abc country code: us in this configuration, whenever the user adds the card to their samsung wallet application, the samsung wallet server sends a send card state notification to the following url: https://partner.server.url/cards/123/abc?cc2=us&event=added. similarly, if a user from the united kingdom deletes a card with the refid xyz, the post request is sent to https://partner.server.url/cards/123/xyz?cc2=gb&event=deleted. therefore, you can know if a card was added or removed from the user’s device directly from the query parameters. post request body the post request body does not contain any information regarding the card state. rather it just provides a callback url that you can use if you want to send an update notification for the card. { "callback": "https://us-tsapi.walletsvc.samsung.com" } post request header the post request header contains all the required information for ensuring the authenticity of the request. it contains a request id with the name “x-request-id” and a jwt bearer token credential for authentication with the name “authorization” in the header. the samsung wallet server uses a bearer authorization token to ensure the authenticity of the requests being sent to the partner server. for details of the security factors, see authorization token. the bearer token is encoded in base64 following the jwt specification. it has three parts: jws header containing authentication related information, jws payload containing the api path, method, and refid, and jws signature, which validates that the bearer token is signed by the samsung server. jws header format: { "cty": "auth", // always “auth” "ver": "3", // can also be “2” for legacy card data token "partnerid": "4048012345678938963", // your partner id "utc": 1728995805104, // time of signing in milliseconds "alg": "rs256", "certificateid": "a123" // only provided for token version 3 } jws payload format: { "api": { "path": "/cards/3h844qgbhil00/2e19cd17-1b3e-4a3a-b904?cc2=gb&event=added", "method": "post" }, "refid": "2e19cd17-1b3e-4a3a-b904-f30dc91ac264" } finally, the bearer token contains a signature to verify the token. this is signed using the samsung private key and can be validated using the public key provided by samsung wallet during the onboarding process. after receiving any request from the samsung wallet server, your server should send back an http status code as a response. samsung server expects one of the following codes as a response: 200 ok 401 unauthorized 500 internal server error 503 service unavailable this is the complete specification of the send card state api that you need to be aware of before you implement the server. next, you need to configure your server to accept the post request in the specified format. configure the spring server to receive the post request to receive and interpret the send card state post notifications sent by the samsung wallet server, you need to configure a partner server and host the server at the url you specified earlier. to receive the post requests, this tutorial extends an existing server created using the spring boot framework. if you want to know how the spring server is configured, check out the “generate signed wallet card data” section in the implementing "add to wallet" in an android application tutorial. this cdata generation server is used as the base server application for this tutorial, so the dependencies are the same as well. now you can start implementing the tutorial. create a controller class to intercept the post request samsung wallet always sends the send card state post notification to the fixed api path url: {partner server url}/cards/{cardid}/{refid}. create a new controller class in your spring server to intercept any post request that is sent to this api path. @restcontroller @requestmapping("/cards") class cardstatecontroller { @postmapping(path = ["/{cardid}/{refid}"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string): httpstatuscode { // implement your logic here to process the card state. println("received card state notification for card id $cardid and reference id $refid.") return httpstatus.ok } } run the server and then add or delete a card from your samsung wallet. if the partner server url was set correctly in section “configure the wallet card template for the send card state api,” your server should receive a post request from the samsung server and print the following message to the console: “received card state notification.” update the controller class to receive the query parameters handle the query parameters from the request by adding the following parameters as the function’s parameters: @requestparam("cc2") cc2: string, @requestparam("event") event: string receive and print the request body using the @requestbody body: string parameter. the function should now look like this: @postmapping(path = ["/{cardid}/{refid}"], params = ["cc2", "event"]) fun handlecardstate(@pathvariable cardid: string, @pathvariable refid: string, @requestparam("cc2") cc2: string, @requestparam("event") event: string, @requestbody body: string): httpstatuscode { // implement your logic here to process the card state. println("country code: $cc2") println("wallet card state event: $event") println("request body: $body") return httpstatus.ok } now whenever the samsung server sends a request to the server, it prints the device’s country code and the wallet card’s state event on the device. verify the post request this is the final and the most important step of this tutorial. before accepting any incoming post request, you should always validate the request by following the api specification mentioned earlier in the tutorial. the security procedures can include but are not limited to: matching your partnerid with the received partnerid custom parameter. checking the token version with the ver custom parameter. for token version 3, match your certificateid using the certificateid custom parameter. checking the time of signing using the utc custom parameter. matching the other jws header parameters with the values mentioned in the specification. matching the path from the jws payload with the received url. verifying the jwt. this section shows how you can implement each of these one by one. first, parse the authentication token and read the header. val signedjwt : signedjwt = signedjwt.parse(authtoken) val jwsheader : jwsheader = signedjwt.header match partnerid and jws header parameters: val ownpartnerid = "4048012345678938963" // your partner id from samsung wallet partner portal val receivedpartnerid = jwsheader.customparams["partnerid"] val ctype = jwsheader.contenttype val alg = jwsheader.algorithm.name // check if the jws header parameters match the expected values if (ctype == "auth" && alg == "rs256" && receivedpartnerid == ownpartnerid ) { println("jws header parameters matched") // proceed with further verification } check the token version and match certificateid: val ver = jwsheader.customparams["ver"] val owncertificateid = "a123" // your certificate id from samsung wallet partner portal val receivedcertificateid = jwsheader.customparams["certificateid"]?: "" // if partner uses token version 3 in the jws header of the cdata, // then samsung server also returns version 3 response along with the certificate id if(ver == "3" && receivedcertificateid == owncertificateid){ println("jws header certificate id matched") // proceed with further verification } check if the token was generated recently: // check if the timestamp is within acceptable range val utc = jwsheader.customparams["utc"] as long val timedelta = system.currenttimemillis() - utc println("time delta: $timedelta") if (timedelta < 600000l) { println("utc timestamp is within last 1 minute. time delta = $timedelta ms.") // proceed with further verification } match the api path with the received api path from the payload: val receivedapivalue = signedjwt.payload.tojsonobject()["api"]?.tostring()?: "" val receivedapipath = receivedapivalue.substring(6, receivedapivalue.length - 14) val expectedpath = "/cards/$cardid/$refid?cc2=$cc2&event=$event" // match the path in the payload with the expected path if (receivedapipath == expectedpath) { println("path matched") // proceed with further verification } finally, validate the token using the samsung certificate provided to you during the onboarding process: read the samsung certificate from a file and then extract the public key. for instructions, refer to the cdata generation server sample code at implementing "add to wallet" in an android application. build an rsakey object using the extracted public key. create an rsassaverifier object with the rsakey to verify the token. verify the token using the verifier. // verify the signature of the jwt token using the public key provided by samsung wallet. val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) val rsakey = rsakey.builder(samsungpublickey as rsapublickey).build() val verifier: rsassaverifier = rsassaverifier(rsakey) if(signedjwt.verify(verifier)){ println("verification successful") // implement your logic here to process the card state notification. // for example, you can update the card status in your database or trigger a notification to the user. // in this example, we simply return a 200 ok response indicating that the notification was successfully processed. return httpstatus.ok } else { println("verification failed") // return an appropriate http status code indicating that the notification could not be verified. return httpstatus.unauthorized } now the complete implementation of the controller class to receive and verify the send card state request is complete. once a send card state request is completely verified, you can accept the request as a valid card state update and make any changes as required. for example, you can update the card status information in your own database or trigger a notification to the user. summary by completing this tutorial, you are now able to receive card state updates from the samsung wallet server using the send card state api and validate them. in a future tutorial, we will discuss how you can expand the server interaction functionality even further and how you can update samsung wallet card information on user devices through the get card data api. if you want to discuss or ask questions about this tutorial, you can share your thoughts or queries on the samsung developers forum or contact us directly for any implementation-related issues through the samsung developer support portal. if you want to keep up-to-date with the latest developments in the samsung developers ecosystem, subscribe to the samsung developers newsletter. sample code you can click on the link given below to download the complete sample code used in this tutorial. wallet card state server sample code (55 kb) dec 2024 additional resources implementing "add to wallet" in an android application send card state authorization token iso 3166 country codes
Mobassir Ahsan
Develop Samsung Wallet
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.