Filter

Send Notification API 60
Sorry, no results
found for "Send Notification API" on the website

tutorials

blog

Send Push Notifications to Samsung Wallet Users Using the Send Notification API

samsung wallet provides an e-wallet service to its customers through wallet cards, as well as offering features designed to enhance user engagement and drive business growth for partners. sending push notifications to users is such a feature. partners can send push notifications to users' wallet cards directly, using pre-approved message templates. these notifications can be used to send promotional messages or alert users about important updates. this article demonstrates a complete implementation of the send notification api. in the example scenario, we send a notification to a user's wallet card from a partner's server using this api. system requirements the notification api has the following prerequisites: complete the onboarding procedure to obtain the required security certificates if you are new to samsung wallet. now create your wallet card. follow the step 1 - create wallet card template section of the documentation. create your notification template and request for approval. follow the notification workflow overview to complete this step. remember to check the template to detect prohibited content. no additional approval is required if it passes. get permission from samsung to use the send notification api. reach out to samsung developer support for further support. api fundamentals as an authorized partner, you can send notifications to the users linked to your card, using the send notification api from your server. endpoint: the endpoint below processes the notification requests. url https://tsapi-card.walletsvc.samsung.com/{cc2}/wltex/cards/{cardid}/notifications/{templateid}/send headers: header information is required to ensure secure communication between the samsung server and the partner server. authorization: bearer token for authentication. refer to json web token documentation for specifications. x-smcs-partner-id: unique partner identifier required for api access. x-request-id: a unique uuid string that identifies each request. body: a payload including a parameter named ndata possessing a jwt token that contains the relevant data to identify the card user. see the official documentation for detailed api specifications. api implementation process the send notification api allows you to send personalized push notifications to users. download the sample source code and follow the step-by-step process below for a better understanding of the implementation of the api. step 1: managing cryptographic keys cryptographic keys are needed for authorization purposes. in this step, use the certificate you obtained during the onboarding process to extract the necessary keys. these keys are needed for jwt token generation. extracting the public keys extract the public keys from the partner.crt and samsung.crt certificate files. def getpublickey(crt_path): try: with open(crt_path, "rb") as f: crt_data = f.read() certificate = x509.load_pem_x509_certificate(crt_data, default_backend()) public_key = certificate.public_key() public_key_pem = public_key.public_bytes( encoding=serialization.encoding.pem, format=serialization.publicformat.subjectpublickeyinfo ) return public_key_pem except exception as error: print(f"error reading public key from {crt_path}: {error}") return none extracting the private key extract the private key from the .pem file generated during the onboarding process. def getprivatekey(pem_path): try: with open(pem_path, "rb") as data: private_key = serialization.load_pem_private_key( data.read(), password=none, backend=default_backend() ) return private_key except exception as error: print(f"error reading private key from {pem_path}: {error}") return none step 2: constructing the authorization token an authorization token is needed to validate the api request. construct an authorization header with auth as the payload content type and include the certificate and partner ids. retrieve these ids from my account > encryption management in the wallet partner portal, then build the payload and construct the authorization token. the following code snippet implements the actions described. def generateauthtoken(partnerid, certificateid, utctimestamp, privatekey, cardid, cc2, templateid): auth_header = { "cty": "auth", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, "alg": "rs256" } auth_payload = { "api": { "method": "post", "path": f"/wltex/cards/{cardid}/notifications/{templateid}/send" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token step 3: constructing the notification data token the request payload requires the ndata parameter, which is a jwt token that contains information about the notification data and the cards’ identifiers. follow these steps to construct the ndata token. defining the notification object the notification object is a json structured data object containing a list of reference ids and the data. the reference ids identify the specific cards to send the push notification to. you can use a list of reference ids to send the push notification to multiple recipients at a time. the data contains the name-value pairs used in the notification template. in our sample notification template, we used two name-value pairs (name and insert_end_date). notifcationobject = { "refids": [ "4afb049c-efef-43ca-8f03-1df55243477c" ], "data": { "name": "premium", "insert_end_date": "12/12/2026" } } constructing the notification data jwt token next, construct the jwt token for notification data (ndata). you can get more information about the jwt format in the "card data token" section of this documentation. def generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data): jwe_header = { "alg": "rsa1_5", "enc": "a128gcm" } jwe_token = jwe.encrypt( data, samsungpublickey, encryption=jwe_header["enc"], algorithm=jwe_header["alg"] ) print(f"jwe_token: \n{jwe_token}\n") jws_header = { "alg": "rs256", "cty": "notification", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, } jws_token = jws.sign( jwe_token, key=partnerprivatekey, algorithm='rs256', headers=jws_header ) print(f"jws_token: \n{jws_token}\n") return jws_token step 4: building and executing the post request construct the http post request to send the push notification using the following code structure. # --- prepare json body (python dictionary) --- payload = { "ndata": ndata } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "content-type": "application/json" } # --- execute http request --- try: response = requests.post(endpoint, json=payload, headers=headers) response.raise_for_status() print("wallet card template notificatiom: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to notify the wallet card user:") print(f"error: {e}") if response: print("response body:", response.text) running the sample application once the four steps described above are implemented, open the sample project and do the following: update the partner_id, certificate_id, card_id, and template_id values in src/main.py with your actual values. place your partner.crt, samsung.crt and private_key.pem files in the /cert directory. install all dependent libraries listed in the requirements.txt file. run the main script in the terminal. after the script is executed successfully, a push notification is sent to the user's wallet. conclusion now that you have implemented the send notification api sample application successfully, you can implement this api with your server to send customized push notifications. additional resources for more information on this topic, consult the following resources: complete source code official samsung wallet api documentation

M. A. Hasan Molla

https://developer.samsung.com/wallet/blog/en-us/2026/03/31/send-push-notifications-to-samsung-wallet-users-using-the-send-notification-api

tutorials

blog

Create Push Notification Templates Using the Samsung Wallet Server API

samsung wallet provides powerful tools for partners to engage with their users and improve the user experience. push notification is one of these features, allowing partners to send customized notifications to their users. but before they can do that, partners need to create a notification template and receive approval for it from samsung. partners can create individual notification templates from the wallet partners portal. as a partner, if you need to create a large number of card notifications, the adding notification templates server api comes in handy. in the example scenario in this blog, we create a notification template from a partner's server using the adding notification template api. system requirements the adding notification template api has the following prerequisites: complete the onboarding procedure to obtain the required security certificates if you are new to samsung wallet, and create your wallet card. get permission from samsung to use the adding notification template api as explicit permission is needed. reach out to samsung developer support for further assistance. api fundamentals to create a notification template, you need to handle an http post request which contains the endpoint, headers, and a body. for a successful execution of the api, you need to follow the following specification. endpoint: use the following url as endpoint. url https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{card id}/notification headers: to ensure secure communication between the samsung server and the partner server, implement the following headers. authorization: bearer token for authentication. for details, follow rest api authorization token. x-smcs-partner-id: use the samsung wallet partner id. x-request-id: a unique uuid string that identifies each request. body: contains detailed template data in the jwt token format. see the adding notification templates for a detailed api specification. api implementation the steps below show how to implement the adding notification template api. for a better understanding of the implementation process, download the sample source code. certificate management the keymanager class is a static utility class that provides methods for loading cryptographic keys from files. this separation of concerns ensures that certificate handling logic is isolated and reusable. loading public keys from certificate files first, you need to load rsa public certificates from x.509 certificate files. the getpublickeyrsa() method loads rsa public keys from the partner.crt and samsung.crt files you received during the onboarding process. if the certificate doesn't contain an rsa key, this method raises an exception. public static rsa getpublickeyrsa(string certpath) { try { var cert = new x509certificate2(certpath); return cert.getrsapublickey() ?? throw new invalidoperationexception("certificate does not contain rsa public key"); } catch (exception ex) { throw new invalidoperationexception($"failed to load certificate: {ex.message}", ex); } } loading private keys from a pem file the getprivatekeyrsa() method loads an rsa private key from a pem file. this is used to generate jwt tokens. public static rsa getprivatekeyrsa(string pempath) { try { string keydata = file.readalltext(pempath); // remove pem headers and whitespace keydata = keydata.replace("-----begin private key-----", "") .replace("-----end private key-----", "") .replace("-----begin rsa private key-----", "") .replace("-----end rsa private key-----", "") .replace("\n", "") .replace("\r", "") .trim(); byte[] keybytes = convert.frombase64string(keydata); var rsa = rsa.create(); rsa.importpkcs8privatekey(keybytes, out _); return rsa; } catch (exception ex) { console.writeline($"failed to load private key from {pempath}: {ex.message}"); return null; } } token generation the tokengenerator class is the heart of the implementation, responsible for creating secure tokens using cryptographic techniques. constructor and properties the class stores all necessary cryptographic keys and identifiers. private string _partnerid = ""; private string _certificateid = ""; private readonly rsa _samsungpublickey; private readonly rsa _partnerpublickey; private readonly rsa _partnerprivatekey; public tokengenerator(string partnerid, string certificateid, rsa samsungpublickey, rsa partnerpublickey, rsa partnerprivatekey) { _partnerid = partnerid; _certificateid = certificateid; _samsungpublickey = samsungpublickey; _partnerpublickey = partnerpublickey; _partnerprivatekey = partnerprivatekey; } generating an authentication token an authentication token proves that your request to samsung's server is legitimate. it contains the following: the api method and path being accessed. var authpayload = new dictionary<string, object> { ["api"] = new dictionary<string, string> { ["method"] = "post", ["path"] = $"/partner/v1/card/template/{cardid}/notification" } }; timestamp and other metadata like certificate id. retrieve this metadata from my account > encryption management in the wallet partners portal. a digital signature that verifies the sender's identity. the token is used in the authorization header of the http request. public string generateauthtoken(dictionary<string, object> authpayload, string contenttype_auth) { string datastr = jsonserializer.serialize(authpayload); string authtoken = signjws(datastr, contenttype_auth); return authtoken; } generating a notification template token next, generate the jwt token for notification template data (ntemplate). it is recommended to generate this token after a user action. for details about the jwt format, follow card data token (cdata). preparing a notification template define the notification template according to the following code snippet. define your message details and message type here. get details about the template fields from the “[request]” section of the adding notification templates documentation. var notificationtemplate = new { type = "m", messagetype = "m", messagedetails = new[] { new { languagecode = "en", message = "sample merchant push notification message." } }, forcesaveyn = "n" }; noteuse forcesaveyn = “y”, if you want to save the template even if the message is detected as harmful. if your message is detected as harmful, your template can be rejected by samsung. the default value of the forcesaveyn property is “n”. implementing encryption (jwe) the notification template data or payload is encrypted using the samsung public key and this encrypted payload is used for signing. public string generatecdata(string payloaddata, string notification) { string jwetokenstring = jwt.encode(payloaddata, _samsungpublickey, jwealgorithm.rsa1_5, jweencryption.a128gcm); string jwttokenstring = signjws(jwetokenstring, notification); return jwttokenstring; } implementing jws signing the encrypted jwe token is then signed with the partner's private key. this signature proves the token originated from a legitimate partner. samsung can verify this signature using the partner's public key. noteuse auth as the content type when signing an auth token and use notification as the content type when signing the notification template data. private string signjws(string payload, string contenttype) { try { // create header var header = new dictionary<string, object> { ["alg"] = "rs256", ["cty"] = contenttype, ["partnerid"] = _partnerid, ["ver"] = 3, ["certificateid"] = _certificateid, ["utc"] = datetimeoffset.utcnow.tounixtimemilliseconds() }; return jwt.encode(payload, _partnerprivatekey, jwsalgorithm.rs256, header); } catch (exception ex) { throw new invalidoperationexception($"jws signing failed: {ex.message}", ex); } } building and executing the post request the next stage of the process is to construct the http post request to generate a new notification. client.defaultrequestheaders.clear(); client.defaultrequestheaders.add("authorization", $"bearer {authtoken}"); client.defaultrequestheaders.add("x-smcs-partner-id", partnerid); client.defaultrequestheaders.add("x-request-id", requestid); try { httpresponsemessage response = await client.postasync(endpoint, content); response.ensuresuccessstatuscode(); string responsecontent = await response.content.readasstringasync(); console.writeline("successfully generated notification template: " + responsecontent); } catch (httprequestexception e) { console.writeline("failed to generate notification template: " + e.message); } catch (exception e) { console.writeline("unexpected error during http request: " + e.message); } running the sample application once you are done with the above steps, open the sample project and do the following: update the partnerid, cardid, and certificateid values in the src/program.cs file with your actual values. place your partner.crt, samsung.crt and private_key.pem files in the /cert directory. navigate to the src directory, then build and run the project. find the details for responses and errors from the [response] section of the documentation. # build the project dotnet build # run the application dotnet run conclusion now that you know how to create a new notification template using the adding notification template api, you can implement it with your server if you need to generate a larger number of notification templates at once. additional resources for more information on this topic, consult the following resources: download the complete source code official samsung wallet api documentation send push notifications to samsung wallet users using the send notification api blog

M. A. Hasan Molla

https://developer.samsung.com/wallet/blog/en-us/2026/06/23/create-push-notification-templates-using-the-samsung-wallet-server-api

tutorials

blog

Configuring Instant Server Notifications for Samsung IAP

in-app purchases are crucial for many applications, and the samsung in-app purchase (iap) service helps developers manage purchases, subscriptions, and refunds efficiently. to keep your server in sync with user transactions, samsung iap instant server notification (isn) sends real-time notifications to your backend server when purchase-related events occur. isn for samsung iap is a method used by samsung's system to notify your server about user activities related to in-app items and subscriptions. when a change occurs, samsung sends a notification to your server. a list of all events that trigger a notification is available here. in this article, we will build a spring boot server that handles these notifications. prerequisites to implement isn for samsung iap, it is important to focus on the requirements that helps you to most easily implement the process: create an iap public key in the seller portal. this key is used to authenticate the notifications you receive and verify that they are from the samsung iap isn system. the steps you need to follow are outlined in the create an iap public key in seller portal documentation. create an in-app item in the seller portal. follow the related documentation to create an in-app item. isn structure the isn for samsung iap service sends a notification to the application developer server. the structure of the notification is always a base64-encoded json web token (jwt) and consists of three parts. the three parts are: header payload signature header the jwt uses a jose (javascript object signing and encryption) header. similar to the envelope of a letter, the header indicates the type of notification being sent. for additional information, refer to the samsung iap isn header article. example encoded header: eyj0exaioijkv1qilcjhbgcioijsxxxxxxxx example decoded header: { "alg" : "rs256", "typ" : "jwt" } payload the payload is the actual content of the message, like the letter inside the envelope. this part contains the crucial information you need, like the user’s subscription details, the product they have subscribed to, and the current status of the subscription. more details about the payload check are available in the following documentation and data claims section. example encoded payload: eyjpc3mioijpyxauc2ftc3vuz2fwchmuy29tiiwic3viijoirvzftlrftkfnrsisimf1zci6wyjjb20ucgfja2fnzs5uyw1lil0sim5izii6mtcxnziwncwiawf0ijoxnze3mja0lcjkyxrhijp7innlbgxlck5hbwuiom51bgwsim nvbnrlbnroyw1lijoitwfydgluzsj9lcj2zxjzaw9uijoxxxxxxxx example decoded payload: { "iss": "iap.samsungapps.com", "sub": "event_name", "aud": ["com.package.name"], "nbf": 1717xxxxxx, "iat": 1717xxxxxx, "data": {..}, "version": "x.0" } signature the signature is the security feature that acts as a digital stamp to prove the message is genuine and hasn’t been tampered with. you can use this signature to verify that the data in the payload is authentic and was created by samsung. further information is provided in the signature documentation. now that we know the structure of the isn for samsung iap, we can configure the server to handle it. server configuration according to the isn for samsung iap requirements, you must set up a server to receive the notifications. below, we create a spring boot server. use your preferred ide (integrated development environment) or online spring initializr to create a spring boot server. follow the steps below to set up your own server. step 1: set up a spring boot project use the spring initializr tool to create a new project. choose the following dependency: spring web generate and download the project. step 2: import the project into ide open the project in the ide (intellij, eclipse, etc.) step 3: set up isn endpoint create a controller for isn notifications in the ide after importing the spring boot project. the controller receives post requests (subscription, refund and cancel) sent from samsung’s iap server. add necessary dependencies in the build.gradle file: { implementation 'com.auth0:java-jwt:4.0.0' //for jwt verifier implementation 'org.json:json:20230227' // for json parsing } load the public key detailed in the prerequisite section: private string loadpublickey(string filename) throws ioexception { classpathresource resource = new classpathresource(filename); stringbuilder contentbuilder = new stringbuilder(); try (inputstream inputstream = resource.getinputstream(); bufferedreader reader = new bufferedreader(new inputstreamreader(inputstream))) { string line; while ((line = reader.readline()) != null) { contentbuilder.append(line).append("\n"); } } return contentbuilder.tostring(); } remove headers, footers, and whitespace from the public key and convert it to the rsapublickey format. private rsapublickey getrsapublickeyfrompem(string pem) throws exception { string publickeypem = pem .replace("-----begin public key-----", "") .replace("-----end public key-----", "") .replaceall("\\s", ""); // remove headers, footers, and whitespace byte[] encoded = base64.getdecoder().decode(publickeypem); keyfactory keyfactory = keyfactory.getinstance("rsa"); x509encodedkeyspec keyspec = new x509encodedkeyspec(encoded); return (rsapublickey) keyfactory.generatepublic(keyspec); } create a jwt verifier with rsapublickey and, finally, verify the jwt. if the verification is successful, decode the jwt to retrieve the decoded json payload. the decoded payload contains the message of the notification. private void verifytoken(string token, rsapublickey publickey) { try { // create jwt verifier with rsa public key algorithm algorithm = algorithm.rsa256(publickey, null); // verify the jwt token jwtverifier verifier = jwt.require(algorithm) .withissuer("iap.samsungapps.com") .build(); decodedjwt jwt = verifier.verify(token); // decode the jwt token string payloadjson = new string(base64.getdecoder().decode(jwt.getpayload())); jsonobject jsonobject = new jsonobject(payloadjson); //print decoded json payload system.out.println("payload as json: " + jsonobject.tostring(4)); } catch (jwtverificationexception e) { system.out.println("invalid token: " + e.getmessage()); } } in this sample project, we have only printed the payload data to the console. you can use this according to your requirements. step 4: deploy the server the server needs a publicly accessible url to receive isn notifications. in our project, we have used codesandbox to get the publicly accessible url for the server. once you deploy the project on codesandbox, you will get a publicly accessible url that looks like this: https://abcde-8080.csb.app/iap/isn. testing with seller portal test your server with samsung galaxy store seller portal: set the codesandbox url as the isn url in seller portal. go to the in-app purchase section and create items with the required details. in the "isn url" field, set the publicly accessible server url. after setting the url, click the test button. a notification will be sent to the specified server immediately. you will also receive a notification on the server that you just deployed in the codesandbox. figure 1: testing with seller portal testing with a sample application now it is time to test the isn for samsung iap from the user application. further details are provided in the integrate the samsung in-app purchase orders api with your application article. download the sample application from this blog and then follow the instructions until you reach the "implementation of item subscription" section. in the sample application, after clicking the "buy" button, startpayment() is called. the onpayment() callback returns an indication of whether the purchase succeeds or fails. if the purchase is successful, the iap server sends a notification to your server. iaphelper.startpayment(itemid, string.valueof(1), new onpaymentlistener() { @override public void onpayment(@nonnull errorvo errorvo, @nullable purchasevo purchasevo) { if (purchasevo != null) { log.d("purchaseid" , purchasevo.getpurchaseid().tostring()); // purchase successfull }else { log.d("purchaseerror" , errorvo.tostring()); } } }); example response after successfully purchasing an item, a json response is returned. for more information on each parameter, you can check the item purchased documentation. example json response: "data" : { "itemid": "example_item_id", "orderid": "xxxx40601kra00xxxxx", "purchaseid": "xxxxx7245d57cc1ba072b81d06e6f86cd49d3da63854538eea689273787xxxxx", "testpayyn": "n", "betatestyn": "n", "passthroughparam": null } notefor different event types, it sends different data claims. for more detailed information regarding data claims, see data claims. conclusion by implementing the isn for samsung iap with your server, you can easily and securely stay in sync with user in-app purchases. integrating isn for samsung iap helps you improve your application management experience and grow your application’s revenue. following this guide will help you smoothly set up the system and provide a better way to manage your application. references for additional information on this topic, see the resources below: download the sample spring boot server samsung iap instant server notification documentation integrate the samsung in-app purchase orders api with your application

Md. Hossain

https://developer.samsung.com/sdp/blog/en-us/2025/03/25/configuring-instant-server-notifications-for-samsung-iap

tutorials

blog

Adding and Updating Samsung Wallet Cards Using Server APIs

in 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

https://developer.samsung.com/sdp/blog/en-us/2025/05/22/adding-and-updating-samsung-wallet-cards-using-server-apis

Develop Samsung Wallet

doc

Notification Service

notification service purpose and scope the notification service enables partners to send messages to users who have registered a wallet card issued by that partner notifications are template-driven and may be used for both service and marketing purposes, subject to template approval and content policy checks partners can create templates via the partner portal or programmatically, then use approved templates to deliver encrypted, jwt-wrapped notification payloads that target specific card instances delivery metrics impressions, clicks are recorded and exposed in the samsung wallet partners portal for campaign evaluation notification workflow deliver personalized push messages to samsung wallet users, linked to their wallet cards samsung wallet enables authorized partners to send targeted push notifications using pre-approved message templates this feature supports marketing, transactional, and engagement-driven use cases only partners with administrative approval can access and use the notifications feature the notifications tab is hidden for unauthorized accounts step 1 create notification template partners can create push message templates through the partner portal or notification api templates define the structure and content of the notification type only merchant push is supported message category choose from marketing or other variables use dynamic placeholders with {{ }} syntax e g , hello {{name}}, your pass for {{event}} is ready if your wallet card supports multiple languages, a message template must be provided for each language variant after drafting the message run harmfulness check to detect prohibited content results pass or fail even if failed, templates can still be submitted but may be rejected in the next step step 2 request template approval once the template is complete click the request approval button in the portal an administrator will review the content if rejected the reason is provided via system email partners can revise and resubmit the template for approval if approved the approved date will appear in the portal the template becomes eligible for use in the notification api step 3 push notification with template once a template is approved, partners can push notifications to users linked to their wallet cards using a secure post api request required parameters template id – issued after template approval reference id – a unique identifier tied to the user’s wallet card created during the add to wallet process only pre-approved templates can be used in push requests step 4 monitor impressions and clicks after the push is delivered, partners can track impressions – number of users who viewed the notification clicks – number of interactions with the push these metrics can be accessed through the partner portal dashboard, enabling performance evaluation of each campaign geofence notification geofence notification enables samsung wallet to provide a location-triggered notification for a wallet card that has already been added by the user this capability uses the locations field in wallet card data cdata and evaluates the user's device location against a configured geofence policy when the configured condition is met, samsung wallet may display a notification to the user this feature is based on card data registered through add to wallet, but the notification behavior itself is performed after card enrollment for this reason, geofence notification is described as a specialized notification scenario rather than as part of the core add to wallet flow at a high level, the partner provides location information and a geofencetype in the card data samsung wallet uses the provided location data and service configuration to evaluate whether a location-triggered notification should be displayed on the device prerequisites the wallet card must already be added to samsung wallet the partner must provide valid locations data in the wallet card data cdata the partner must provide a geofencetype for each location intended for geofence notification the user must allow location access on the device for location-triggered behavior availability of geofence notification may depend on service policy or feature enablement partner input example { "locations" "[{\ \"lat\" 37 12345,\ \"lng\" 127 12345,\ \"name\" \"store 1\",\ \"address\" \"110 example-ro\",\ \"geofencetype\" \"100\",\ \"message\" \"welcome to store 1 check your available benefits in samsung wallet \"\ }]" } the locations field is represented as a stringified json array in wallet card data cdata each location object may contain basic place information such as latitude, longitude, place name, and address for geofence notification, the partner additionally provides geofencetype as a string value and may provide a notification message geofence notification configuration for geofence notification, the partner provides geofencetype as a string value in each applicable location entry supported values are "100", "200", "300", "400", and "500" these values indicate the geofence radius in meters, such as 100 m, 200 m, 300 m, 400 m, and 500 m samsung wallet uses the provided value together with service-side configuration to apply the geofence notification scenario to the card each value must be provided as a string in the locations entry supported geofencetype values "100" 100 m radius "200" 200 m radius "300" 300 m radius "400" 400 m radius "500" 500 m radius geofence notification flow step 1 prepare card data the partner prepares wallet card data cdata and includes locations entries for the relevant places for geofence notification, each target location entry includes geofencetype and message step 2 register the card through add to wallet the partner submits the card through the add to wallet flow using the appropriate card template and wallet card data step 3 resolve geofence policy samsung wallet applies the geofence notification scenario associated with each geofencetype and prepares the card for location-triggered behavior on the device step 4 add the card and grant location access the user adds the card to samsung wallet to support location-triggered behavior, location access must be enabled on the device step 5 detect geofence events the device evaluates the user's location against the configured geofence conditions, such as entry, radius, and active time range step 6 display notification when the configured condition is satisfied, samsung wallet displays the notification associated with the location entry notification service apis send notification this api sends notifications to end users who have added the wallet card [request] type value description method post url /{cc2}/wltex/cards/{cardid}/notifications/{templateid}/send header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see rest api authorization token jwt / jws for more details x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cc2string 2 required country code cc2 from send card state send card event cardidstring 32 required wallet card identifier granted from samsung wallet partners portal template idstring 32 required approved notification template identifier from samsung wallet partners portal payload ndatastring required notification object json * this field needs to be encrypted * refer to card data token cdata for more details * the value of "cty" must be set to "notification" notification object refidsarray of string 100 required unique content identifier defined by the content provider dataobject required name-value pair for use in notification template example post /wltex/cards/12584806754/notifications/12353465344/send /* [headers] */ authorization bearer <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /* [payload] */ { "ndata" <jwt_serialized> } /*[notification object]*/ { "refids" [ "ref-20230304-0003", "ref-20230304-0004" ], "data" { "name" "logan", "place" "samsung wallet" } } [response] type value description http status 200 ok payload n/a [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request create targeted notification job this api creates a targeted notification job for users who match the specified filter conditions [request] type value description method post url /wltex/cards/{cardid}/notifications/{templateid}/jobs header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cardidstring 32 required wallet card identifier granted from samsung wallet partners portal template idstring 32 required approved notification template identifier from samsung wallet partners portal payload filterobject required targeting condition object the supported filter key is eventid dataobject optional name-value pair for use in notification template example post /wltex/cards/12584806754/notifications/12353465344/jobs /* [headers] */ authorization bearer <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /* [payload] */ { "filter" { "eventid" "event-003" }, "data" { "name" "logan", "place" "samsung wallet" } } [response] type value description http status 200 ok payload idstring targeted notification job identifier statusstring targeted notification job status the initial status is ready example 200 ok { "resultcode" "0", "resultmessage" "success", "id" "targeting-job-id", "status" "ready" } [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to a client error 401 unauthorized authorization token is invalid or expired 404 not found targeted notification job does not exist or does not belong to the requested card 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request get targeted notification job this api retrieves the status and timestamps of a targeted notification job [request] type value description method get url /wltex/cards/{cardid}/notifications/{templateid}/jobs/{jobid} header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cardidstring 32 required wallet card identifier granted from samsung wallet partners portal template idstring 32 required approved notification template identifier from samsung wallet partners portal jobidstring 36 required targeted notification job identifier returned when creating the job example get /wltex/cards/12584806754/notifications/12353465344/jobs/targeting-job-id /*[headers]*/ authorization bearer <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140004 [response] type value description http status 200 ok payload jobobject targeted notification job object job idstring targeted notification job identifier job statusstring targeted notification job status job createdatstring date and time when the targeted notification job was created job endedatstring date and time when the targeted notification job ended the value can be null while processing example 200 ok { "resultcode" "0", "resultmessage" "success", "job" { "id" "targeting-job-id", "status" "ready", "createdat" "2026-03-16t00 00 00z", "endedat" null } } [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to a client error 401 unauthorized authorization token is invalid or expired 404 not found targeted notification job does not exist or does not belong to the requested card 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request adding notification templates in general, card notification creation is possible through the samsung wallet partners portal however, a server api is provided for cases where it is necessary to create a large number of card notifications card notifications created through api can also be checked and managed in the same way on the samsung wallet partners portal [request] type value description method post url /partner/v1/card/template/{cardid}/notification header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required the wallet card identifier granted through the samsung wallet partners portal * the identifier is needed when updating a specific card template body parameters ntemplateobject required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter card data token cdata for more details payload object typestring 20 required notification type m merchant push, g geo push messagetypestring 20 required purpose of notification s service, m marketing messagedetails[]array of object required container of notification message messagedetails[] languagecodestring 20 required default notification language code,e g en, ko messagedetails[] messagestring 500 required notification message forcesaveynstring 10 optional sets whether to save when harmfulness is detected this must be set to either 'y' or 'n' * default 'n' example notification template object { "type" "m", "messagetype" "s", "messagedetails" [ { "languagecode" "en", "message" "it’s notification message " }] } example post /partner/v1/card/template/3hdpejr6qi380/notification /* [headers] */ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /* [payload] */ { "ntemplate" "<jwt_serialized>" } [response] type value description http status 200 ok payload harmfulresult harmfulness check result responded as “pass” or “fail” harmfullabels reason for harmfulness detection responded only when harmfulresult is “fail” save indicates whether the forcesaveyn option has been set when set to “y”, it is responded as “force” 200 ok { "resultcode" "0", "resultmessage" "success", "harmfulresult" "pass" } 200 ok { "resultcode" "0", "resultmessage" "success", "harmfulresult" "fail", "harmfullabels" "hate,violence" } 200 ok { "resultcode" "0", "resultmessage" "success", "save" "force", "harmfulresult" "fail", "harmfullabels" "violence" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable get notification templates [request] type value description method get url /partner/v1/card/template/{cardid}/notification headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template example get /partner/v1/card/template/3hdpejr6qi380/notification /* [headers] */ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok example 200 ok { "resultcode" "0", "resultmessage" "success", "templates" [ { "id" "4091356465432138240", "type" "m", "messagetype" "s", "approval" "approved", "messagedetails" [ { "languagecode" "en", "message" "hi! {{name}}, this is merchant push " } ] }, { "id" "4092425423713135680", "type" "m", "messagetype" "s", "approval" "none", "messagedetails" [ { "languagecode" "en", "message" " hi! {{name}}, this is merchant push" } ] }, ] } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable get notification statistics [request] type value description method get url /partner/v1/card/template/{cardid}/stats/notifications headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see rest api authorization token jwt / jws x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters cardidstring 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template query parameters notificationidstring 32 optional if specified, statistics are returned only for the specified notification if not specified, aggregated statistics for all notifications of the card are returned starttimetamp ms required start date unix timestamp in milliseconds endtimestamp ms required end date unix timestamp in milliseconds metricstring 32 required metric impression/click example get /partner/v1/card/template/3hdpejr6qi380/stats/notifications?notificationid=123456789&start=1764514800000&end=1765465200000&metric=impression /* [headers] */ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok example 200 ok { "resultcode" "0", "resultmessage" "success", "statistics" [ [ 1764820800000, 1 ], [ 1764896400000, 2 ], [ 1764900000000, 1 ], [ 1764903600000, 0 ], [ 1764907200000, 1 ], [ 1765134000000, 0 ] ] } [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

https://developer.samsung.com/wallet/businesssupportforspecialpurposes/notificationservice.html

tutorials web

blog

Receiving and Verifying Card States from the Samsung Wallet Server

the 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

https://developer.samsung.com/sdp/blog/en-us/2024/12/18/receiving-and-verifying-card-states-from-the-samsung-wallet-server

Develop Samsung Pay

doc

Implement a Save to Pay integration

implement a save to pay integration to implement save to pay on your website after the customer has selected the card to add to samsung wallet on your website, create a registration session using the post /registrations rest api operation save to pay returns a registration session id and the welcome ui's url in the response store the registration session id for later use include the save to pay javascript library for your website <script src="https //spay samsung com/s2p/libs/js/0 0 4/s2p min js"></script> display the welcome ui with the showwelcomemodal or showwelcomemodalpromise javascript method the welcome ui's url has an expiration time if you are unsure whether the url is still valid, use the get /registrations/{regid} rest api operation to retrieve a valid url wait while the customer scans the qr code on the welcome page when the save to pay process has started and samsung wallet is ready to proceed, save to pay sends you a wa_ready notification using the post /notifications rest api operation contact the card issuer to pre-provision the card and receive the provisioning data send the provisioning data encrypted card information in your response to the post /notifications rest api operation wait while the provisioning is completed within the payment system when the provisioning process is completed, save to pay sends you a wa_provisioned or wa_provision_failure notification using the post /notifications rest api operation there is no need to respond to that notification the welcome ui automatically redirects the customer when the process completes if you need to close the welcome ui on purpose for any reason, use the closewelcomemodal javascript method best practices keep your client certificate secure and monitor its expiration dates log and monitor inbound and outbound requests for verification and debugging maintain a testing staging environment for ongoing testing

https://developer.samsung.com/pay/issuer/save-to-pay/implement.html

Develop Samsung Pay

doc

Outbound REST API

outbound rest api save to pay uses the outbound rest api to send notifications to your server samsung sends notifications for key card provisioning events; for example, when samsung wallet is ready for provisioning, and when the provisioning completes successfully save to pay uses the base url that you provided to samsung during save to pay service registration to send api requests notesamsung uses a client certificate signed by your ca your system must verify the authenticity of samsung’s certificate for all requests arriving from samsung notify about status update notifies your server about card provisioning status updates from save to pay endpoint post /notifications request parameters parameter name type required/optional description header request-id string required unique request id header partner-id string required unique partner id, provided by samsung during onboarding request body json field type required/optional description event object required event information, including the associated registration session id event regid string required unique registration session id associated with the event event type enum required event type the possible values are wa_ready samsung wallet is ready for card provisioning wa_provisioned card provisioning was successful wa_provision_failure card provisioning failed, either for an unknown reason if the error parameter is absent or because the card is already present if the error parameter is card_already_present event error enum required additional error reason, used when the event type is wa_provision_failure the possible value is card_already_present event desc string optional event description emailmatches boolean conditional whether the email provided in the post /registrations operation matches the email address associated with the samsung wallet account required only is the email was provided in the post /registrations operation phonematches boolean conditional whether the phone number provided in the post /registrations operation matches the phone number associated with the samsung wallet account required only is the phone number was provided in the post /registrations operation user object required customer information user id string required customer's samsung account id device object required device information device id string required unique device id device imeilast4 string optional last 4 digits of the device imei number device seriallast4 string optional last 4 digits of the device serial number device locale country string optional device's country code in the iso 3166-1 alpha-2 format wallet object required wallet information wallet id string required unique wallet id response header name type required/optional description response-id string required unique response id that echoes back the request-id header from the request response body json field type required description card data encrypteddata string conditional provisioning data encrypted card information , required when responding to the wa_ready event example request { "event" { "regid" "395ce2e29485442cbd9bacdc77105126", "type" "wa_ready" }, "emailmatches" true, "phonematches" true, "user" { "id" "rcsm3gwjt9mxgfwy5sg123" }, "wallet" { "id" "gpccugejs9giih8zch1111" }, "device" { "id" "mtuxmte5mdawmjawmdm1n999", "imeilast4" "6166", "locale" { "country" "us" }, "seriallast4" "4934" } } 200 ok response { "card" { "data" { "encrypteddata" "*****" } } }

https://developer.samsung.com/pay/issuer/save-to-pay/api-reference-outbound-apis.html

Develop Samsung Wallet

doc

Overview

overview this section describes the add to samsung wallet process, which enables partners to register cards in samsung wallet and define their baseline data, presentation, and capabilities add to wallet is the standard and mandatory process for publishing wallet cards the lifecycle, portal operations, and rest apis described in this section apply to all supported card types most card services rely solely on the add to wallet process and do not require any additional feature integration scope add to samsung wallet defines card registration and lifecycle management template configuration and publication card metadata, layout, and action data definition capability declaration, including optional nfc support the behaviors and state transitions described in this section represent the canonical integration path for wallet cards optional feature extensions some card programs may support additional device-level capabilities beyond standard card presentation where applicable, such features are treated as optional extensions to the base add to wallet process detailed technical and operational requirements for those extensions are described in separate documentation service flow the add to samsung wallet atw service provides a set of interfaces that enable users to easily add digital content to their samsung wallet, enhancing convenience by allowing users to store, manage, and access items such as loyalty cards, tickets, boarding passes, and more directly within the app the service involves several steps, from content preparation to updates and managing card states preparation steps to prepare the contents intended to store on samsung wallet must be tokenized as jwt json web token when using data transmit link considering what environments, the button will be displayed in such as app, web, mms, or email when you plan to integrate this service refer to implement the button section for more details note-the data transmit link is used for communication between the partner’s server and samsung wallet this link sends any additional information related to the card such as updates or notifications about the card’s status add to wallet steps to add to wallet once users who want to store contents click or tab the linked button, it initiates the process of adding to samsung wallet if you are providing the full pass content, use the data transmit link option note-the data fetch link enables the partner's backend system to pull content dynamically when a user clicks the "add to wallet" button, the system fetches the necessary content e g , card details, event data, loyalty points using this link samsung will notify the result through server interface named send card state send card event this works as a callback for 'add to wallet' process delivering events and country code for the user wallet card to handle interactions after storing content in samsung wallet, server interfaces are required these interfaces are defined in the updating wallet card specs see api guidelines for more details update wallet cards steps to update wallet cards partners may need to update or modify the content stored in samsung wallet for example, a user might accumulate more loyalty points, or flight details may change to update the wallet card content, partners must call the samsung server api the cc2 path parameter must match the cc2 value from the send card state send card event api notification triggered by the added event refer to samsung server api section for more details update notification is for single content cancel notification is for calling off every user's wallet card content related to a specific event get card data payload has the same format of card information as the one of 'add to wallet' send card state send card event can also have an event 'deleted' to notify a wallet card deletion on samsung wallet by users gift cards and generic cards currently do not support update notification functionality card states wallet cards within samsung wallet can have various states e g , active, expired, used, suspended for each content provider’s notifications and user actions the state diagram below describes wallet card states from beginning to end state diagram

https://developer.samsung.com/wallet/addtosamsungwallet/overview.html

Develop Samsung IAP

doc

Price Increase Notifications

price increase notifications existing subscribers are always notified of a price increase to an existing subscription galaxy store sends the following message when the price increase does not require consent by the subscriber the first notification from galaxy store is sent after the 7-day waiting period has ended, on the user’s renewal date during the pre-notification period automatic notifications are sent every week during the pre-notification period galaxy store sends the following email message when the price increase requires consent by the subscriber the email notification links to a consent page, from which the existing subscriber can consent or reject the price increase noteconsent can only be given from the consent page on a samsung mobile device that is, the consent page only displays when viewed on a samsung mobile device if the existing subscriber opens the consent page from a computer or non-samsung mobile device, your app info page is displayed the first notification from galaxy store is sent after the 7-day waiting period has ended, on the user’s renewal date during the pre-notification period note that the price of the subscription is at the original price you may choose to send a notification to your existing subscribers before this time if the price increase requires consent by the existing subscriber, samsung recommends that you send a notification before this time and explain that their consent is required if they want to continue their subscription when the price increase takes effect samsung recommends that you also display a message when your app is launched with the same or similar information you should provide the deeplink to your app’s regular payment detail page from which your customers can access the consent page on their samsung mobile device samsungapps //subscriptiondetail?purchaseid={purchaseid} use the getownedlist api the subscriptionpricechangevo object to determine if consent is needed automatic notifications are sent every week during the pre-notification period and only when the subscriber has not given their consent to or rejected the price increase from the consent page that is, they take no action and are ignoring the notifications automatic notifications are stopped if an existing subscriber acknowledges a notification from the consent page either by consenting to or rejecting the price increase or when the pre-notification period ends pre-notification period the pre-notification period is how far in advance of the renewal date when the price increase is applied for the first time that the existing subscriber receives email notifications from galaxy store it can start any time after the 7-day waiting period ends the minimum length of time of the pre-notification period is based on the subscription period when the pre-notification period starts is based on the existing subscriber’s subscription renewal date when the price increase is applied for the first time the table below shows the minimum length of the pre-notification period by subscription period subscription period minimum length of pre-notification period weekly 2 weeks before renewal date monthly 1 month before renewal date 3 months 2 months before renewal date 6 months 2 months before renewal date annual 2 months before renewal date if an existing subscriber’s subscription is renewable during the pre-notification period, they will be able to renew their subscription at the current price, not the increased price see the examples for more information

https://developer.samsung.com/iap/subscription-guide/manage-subscription-price/price-increase-notifications.html

Didn’t find what you were looking for?

FAQ

Search frequently asked
questions
by keywords.

Join the Forum

Visit the Forum to ask
questions and exchange
ideas with other developers.

Get Support

Submit a 1:1 Support request
and receive a response
within 2 business days.

Preferences Submitted

You have successfully updated your cookie preferences.