Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
tutorials
blogsamsung wallet partners can create and update card templates to meet their business needs through the wallet partners portal. however, if the partner has a large number of cards, it can become difficult to manage them using the wallet partners portal website. to provide partners with more flexibility, samsung provides server apis so that partners can easily create and modify samsung wallet card templates without using the wallet partners portal. with these apis, partners can also create their own user interface (ui) or dashboard to manage their cards. in this article, we implement the add wallet card templates api to create a card template for a coupon in the wallet partners portal. we focus on the api implementation only and do not create a ui for card management. prerequisites if you are new to samsung wallet, complete the onboarding process and get the necessary certificates. as a samsung wallet partner, you need permission to use this api. only authorized partners are allowed to create wallet card templates using this api. you can reach out to samsung developer support for further assistance. api overview the rest api discussed in this article provides an interface to add wallet card templates directly from the partner's server. this api utilizes a base url, specific headers, and a well-structured body to ensure seamless integration. url: this is the endpoint where the request is sent to create a new wallet card template. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template headers: the information provided in the headers ensures secure communication between the partner's server and samsung's server. authorization: the bearer token. see the json web token documentation for details. x-smcs-partner-id: this is your partner id. the partner id gives you permission to use the api. x-request-id: use a randomly generated uuid string in this field. body: the body must be in the jwt token format. convert the payload data (card template in json format) into a jwt token. for more details about the api, refer to the documentation. implementation of the api to create a card template the add wallet card templates api allows you to add a new card template to the wallet partners portal. you can also create the card in the portal directly, but this api generates a new card template from your server, without requiring you to launch the wallet partners portal. follow these steps to add a new card template. step 1: extracting the keys extract the following keys from the certificates. these keys are used while generating the jwt token. rsapublickey partnerpublickey = (rsapublickey) readpublickey("partner.crt"); rsapublickey samsungpublickey = (rsapublickey) readpublickey("samsung.crt"); privatekey partnerprivatekey = readprivatekey("private_key.pem"); extracting the public keys use the following code to extract the partner public key and the samsung public key from the partner.crt and samsung.crt certificate files, respectively. you received these certificate files during the onboarding process. private static publickey readpublickey(string filename) throws exception { // load the certificate file from resources classpathresource resource = new classpathresource(filename); try (inputstream in = resource.getinputstream()) { certificatefactory certfactory = certificatefactory.getinstance("x.509"); x509certificate certificate = (x509certificate) certfactory.generatecertificate(in); return certificate.getpublickey(); } } extracting the private key the following code extracts the private key from the .pem file you generated during the onboarding process. this key is needed to build the auth token. private static privatekey readprivatekey(string filename) throws exception { string key = new string(files.readallbytes(new classpathresource(filename).getfile().topath())); key = key.replace("-----begin private key-----", "").replace("-----end private key-----", "").replaceall("\\s", ""); byte[] keybytes = base64.getdecoder().decode(key); keyfactory keyfactory = keyfactory.getinstance("rsa"); return keyfactory.generateprivate(new pkcs8encodedkeyspec(keybytes)); } step 2: generating the authorization token samsung's server checks the authorization token of the api request to ensure the request is from an authorized partner. the authorization token is in the jwt format. follow these steps to create an authorization token: building the auth header create an authheader. set “auth” as its payload content type to mark it as an authorization token. as you can create multiple certificates, use the corresponding certificate id of the certificate that you use in the project. you can get the certificate id from “my account > encryption management” of the wallet partners portal. // create auth header jsonobject authheader = new jsonobject(); authheader.put("cty", "auth"); authheader.put("ver", 3); authheader.put("certificateid", certificateid); authheader.put("partnerid", partnerid); authheader.put("utc", utctimestamp); authheader.put("alg", "rs256"); creating the payload create the payload using the authheader. follow this code snippet to create the payload. // create auth payload jsonobject authpayload = new jsonobject(); authpayload.put("api", new jsonobject().put("method", "post").put("path", "/partner/v1/card/template")); authpayload.put("refid", uuid.randomuuid().tostring()); building the auth token finally, generate the authorization token. for more details, refer to the “authorization token” section of the security page private static string generateauthtoken(string partnerid, string certificateid, long utctimestamp, privatekey privatekey) throws exception { // create auth header // create auth payload // return auth token return jwts.builder() .setheader(authheader.tomap()) .setpayload(authpayload.tostring()) .signwith(privatekey, signaturealgorithm.rs256) .compact(); } step 3: generating a payload object token the request body contains a parameter named “ctemplate” which is a jwt token. follow these steps to create the “ctemplate.” creating the card template object select the proper card template you want to create from the card specs documentation. get the payload object as json format. now create the jsonobject from the json file using the following code snippet. // creating card template object jsonobject cdatapayload = new jsonobject(); cdatapayload.put("cardtemplate", new jsonobject() .put("prtnrid", partnerid) .put("title", "sample card") .put("countrycode", "kr") .put("cardtype", "coupon") .put("subtype", "others") .put("saveinserveryn", "y")); generating the jwe token create the jwe token using the following code snippet. for more details about the jwe format, refer to the “card data token” section of the security page. // jwe payload generation encryptionmethod jweenc = encryptionmethod.a128gcm; jwealgorithm jwealg = jwealgorithm.rsa1_5; jweheader jweheader = new jweheader.builder(jwealg, jweenc).build(); rsaencrypter encryptor = new rsaencrypter((rsapublickey) samsungpublickey); jweobject jwe = new jweobject(jweheader, new payload(string.valueof(cdatapayload))); try { jwe.encrypt(encryptor); } catch (joseexception e) { e.printstacktrace(); } string payload = jwe.serialize(); building the jws header next, follow this code snippet to build the jws header. set “card” as the payload content type in this header. // jws header jwsheader jwsheader = new jwsheader.builder(jwsalgorithm.rs256) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", 3) .customparam("certificateid", certificateid) .customparam("utc", utctimestamp) .build(); building the jws token generate the jws token from the previously generated jwe token and, finally, get the “ctemplate” jwt. follow the “jws format” section of the security page. private static string generatecdatatoken(string partnerid, publickey partnerpublickey, publickey samsungpublickey, privatekey partnerprivatekey, string certificateid, long utctimestamp) throws exception { // creating card template object // jwe payload generation // jws header // jws token generation jwsobject jwsobj = new jwsobject(jwsheader, new payload(payload)); rsakey rsajwk = new rsakey.builder((rsapublickey) partnerpublickey) .privatekey(partnerprivatekey) .build(); jwssigner signer = new rsassasigner( ); jwsobj.sign(signer); return jwsobj.serialize(); } step 4: building the request as all of the required fields to create the request have been generated, you can now create the request to add a new template. follow the code snippet to generate the request. private static request buildrequest(string endpoint, string partnerid, string requestid, string authtoken, string cdatatoken) { // prepare json body jsonobject cdatajsonbody = new jsonobject(); cdatajsonbody.put("ctemplate", cdatatoken); requestbody requestbody = requestbody.create( mediatype.parse("application/json; charset=utf-8"), cdatajsonbody.tostring() ); // build http request request request = new request.builder() .url(endpoint) .post(requestbody) .addheader("authorization", "bearer " + authtoken) .addheader("x-smcs-partner-id", partnerid) .addheader("x-request-id", requestid) .addheader("x-smcs-cc2", "kr") .addheader("content-type", "application/json") .build(); return request; } step 5: executing the request if the request is successful, a new card is added to the wallet partners portal and its “cardid” value is returned as a response. private static void executerequest(request request) { // execute http request try (response response = client.newcall(request).execute()) { if (response.issuccessful()) { system.out.println("wallet card template added successfully: " + response.body().string()); } else { system.out.println("failed to add wallet card template: " + response.body().string()); } } } implement as a server at this point, you can add a webpage ui for creating card templates and deploy it as a web service. in this sample project, there is no ui added. but, you can deploy this sample as a web service and test it. conclusion this tutorial shows you how you can create a new samsung wallet card template directly from your server by using a rest api. now that you can implement the api, you can add a ui and make it more user-friendly. also implement the updating wallet cards templates api for better card management. references for additional information on this topic, refer to the resources below: sample project code. business support for special purposes documentation.
M. A. Hasan Molla
tutorials
blogcard template management is a crucial task for partners in the samsung wallet ecosystem that is typically handled through the wallet partners portal. manually altering numerous existing templates via the web interface can be inefficient and challenging. samsung provides a set of server-side apis to address this, allowing partners to programmatically manage and modify their card templates for greater operational agility. using these apis enables partners to integrate update capabilities directly into their own ecosystems. this automation facilitates the seamless maintenance of card offerings, helping partners keep their content dynamic and up-to-date. as a partner, this article walks you through the implementation of the update wallet card template api specifically using python. if you are a java developer or want to implement the add wallet card template api, you can follow the previous content on creating samsung wallet card templates. noteto follow this article, you'll need an existing card template and its cardid. make sure you have completed the samsung wallet onboarding to obtain the necessary certificates. also, you need permission to use this api. only permitted partners can use this api. api overview this section details the rest api designed for modifying a pre-existing wallet card template, enabling direct updates from a partner's server. endpoint url: direct requests to modify a card template to the following url. it is imperative to substitute {cardid} with the identifier of the specific card template you intend to alter. https://tsapi-card.walletsvc.samsung.com/partner/v1/card/template/{cardid} request headers: secure interaction with this api is restricted to authenticated partners. the headers detailed below are vital for establishing a secure and validated communication channel with the samsung server. authorization: this field must contain the bearer token. for comprehensive information, consult the json web token documentation. x-smcs-partner-id: this field must be populated with your unique partner identifier. x-request-id: a universally unique identifier (uuid) is required here, freshly generated for each request. request body: the payload of the request needs to be structured as a json object. this object must include a key named ctemplate, with its value being a jwt token. this specific jwt securely contains the complete data for the revised card template. for a deeper dive into the api specifications, check the official documentation. implementing the api to create a card template the update wallet card template api enables partners to modify existing card templates in the wallet partners portal. in this section, we implement python code to update a coupon card template, for example, by changing its title. extracting the keys from certificates extract the public and private keys from the certificate files obtained during the onboarding process. def getpublickey(crt_path): """ extract publick key from a .crt file. """ try: with open(crt_path, "rb") as f: crt_data = f.read() certificate = x509.load_pem_x509_certificate(crt_data, default_backend()) public_key = certificate.public_key() public_key_pem = public_key.public_bytes( encoding=serialization.encoding.pem, format=serialization.publicformat.subjectpublickeyinfo ) return jwk.jwk.from_pem(public_key_pem) except exception as error: print(f"error reading public key from {crt_path}: {error}") return none def getprivatekey(pem_path): ''' extract private key from a .pem file. ''' try: with open(pem_path, "rb") as pem_data: private_key = serialization.load_pem_private_key( pem_data.read(), password = none, backend = default_backend() ) return private_key.private_bytes( encoding=serialization.encoding.pem, format=serialization.privateformat.pkcs8, encryption_algorithm=serialization.noencryption() ) except exception as error: print(f"error reading private key from {pem_path}: {error}") return none generating the authorization token the samsung server uses a jwt format token to verify if the request is from an authorized partner. follow these steps to create an authorization token. create an authorization token header. set the payload content type to ‘auth’ since this is an authorization token. create the payload using the authorization token header. generate the authorization token. the following code snippet demonstrates these steps. def generateauthtoken(partnerid, certificateid, utctimestamp, privatekey, cardid): auth_header = { "cty": "auth", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, "alg": "rs256" } auth_payload = { "api": { "method": "post", "path": f"/partner/v1/card/template/{cardid}" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token generating a payload object token the request body includes a parameter named ctemplate, which is also a jwt token. create the jwt token using the following code snippet. def generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data): jwe_header = { "alg": "rsa1_5", "enc": "a128gcm" } jwe_token = jwe.encrypt( data, samsungpublickey, encryption=jwe_header["enc"], algorithm=jwe_header["alg"] ) print(f"jwe_token: \n{jwe_token}\n") jws_header = { "alg": "rs256", "cty": "card", "ver": 3, "certificateid": certificateid, "partnerid": partnerid, "utc": utctimestamp, } jws_token = jws.sign( jwe_token, key=partnerprivatekey, algorithm='rs256', headers=jws_header ) print(f"jws_token: \n{jws_token}\n") return jws_token building and executing the request build and send the http request to the specified update endpoint. add all fields that you want to modify in the ’cdatapayload’ object. refer to the documentation to identify the fields that you can modify. def main(partnerid, cardid, certificateid, utctimestamp, requestid, endpoint): partnerpublickey = getpublickey("../cert/partner.crt") print(f"partnerpublickey {partnerpublickey}") samsungpublickey = getpublickey("../cert/samsung.crt") print(f"samsungpublickey {samsungpublickey}\n") partnerprivatekey = getprivatekey("../cert/private_key.pem") print(f"partnerprivatekey {partnerprivatekey}\n") authtoken = generateauthtoken(partnerid, certificateid, utctimestamp, partnerprivatekey, cardid) print(f"authtoken {authtoken}\n") cdatapayload = {} # --- add data here that you want to update. cdatapayload["cardtemplate"] = { "title": "update card tile", "countrycode": "kr", "saveinserveryn": "y" } data = json.dumps(cdatapayload).encode('utf-8') cdatatoken = generatecdatatoken(partnerid, samsungpublickey, partnerprivatekey, certificateid, utctimestamp, data) print(f"cdatatoken: \n{cdatatoken}\n") # --- prepare json body (python dictionary) --- c_data_json_body = { "ctemplate": cdatatoken } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "x-smcs-cc2": "kr", "content-type": "application/json" } # --- execute http request --- try: response = requests.post(endpoint, json=c_data_json_body, headers=headers) response.raise_for_status() print("wallet card template updated successfully: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to update wallet card template:") print(f"error: {e}") if response: print("response body:", response.text) running the application download the sample project and open it with any ide, then follow this process. configure: update ‘partner_id’, ‘certificate_id’, and, crucially, ‘card_id_to_update’ in src/main.py with your actual credentials and the id of the card you need to modify. place certificates: ensure your partner.crt, samsung.crt and private_key.pem files are in the cert/ directory. install dependencies: install all the required dependencies from the requirements.txt file. pip install -r requirements.txt execute: run the main script from the terminal. python src/main.py if the request is successful, the specified card template in the wallet partners portal is updated. the api returns the updated card id with a success status, otherwise it returns an error. find all the status codes in the '[result]' section of the documentation. wallet card template updated successfully: { "cardid": "cardid", "resultcode": "0", "resultmessage": "update_success" } conclusion by implementing the api to update an existing samsung wallet card template through this article, you can now automate and streamline the management of your card templates, ensuring that they always reflect the latest information. references for additional information on this topic, refer to the resources below. sample project code create samsung wallet card templates using the server api business support for special purposes documentation
M. A. Hasan Molla
tutorials
blogsamsung wallet allows users to conveniently store and access payment cards, passes, and now also custom gift cards—all in one secure place. with gift card integration, partners can deliver a personalized and rewarding experience to their users, enhancing brand connection and user convenience. in this article, you learn how to create and integrate your own gift card as a partner using samsung wallet’s card template system. learn to customize visuals, define key details like balance and expiration date, and enable a seamless ‘add to samsung wallet’ experience for your customers. gift card setup are you ready to dive into the world of samsung wallet and create your first card template? follow these simple steps to get started and bring your ideas to life! step 1: complete the onboarding process if you have not done it already. for details, check out the onboarding guide. step 2: log in to the wallet partners portal. this is your gateway to creating and managing your wallet cards. step 3: once logged in, head over to the wallet cards section. here, you find the create wallet card option. for more details about creating a card, don’t forget to check out the manage wallet cards documentation. step 4: choose the gift card template from the list of available card templates. step 5: customize your card. now comes the fun part! modify the card information to suit your needs. through adjusting colors, adding logos, or tweaking text, this is where your creativity shines. step 6: launch your card once you are satisfied with your edits. for more details on launching, refer to the launch wallet cards guide. notemanaging multiple cards through the wallet partners portal can be challenging. samsung offers server apis to simplify the process, enabling you to create and modify samsung wallet card templates efficiently, without relying on the portal. explore the following blog topic for detailed insights: create samsung wallet card templates using the server api. gift card specifications before generating the card data token for the ‘add to samsung wallet’ button, it’s essential to understand the structure of a sample gift card. every gift card in samsung wallet is built from a defined set of data fields that determine how the card looks and functions. these fields are part of the card’s json structure and control everything from how the card title appears to how barcode data is delivered when scanned. the following examples illustrate how different card elements map to the gift card specifications. each image highlights a specific group of parameters used when creating a gift card for samsung wallet. basic gift card information this image illustrates the core elements that define the basic structure of a gift card in samsung wallet. it highlights the required fields—such as title, applinkname, applinkdata, and applinklogo—which control the card’s main display name and linked actions. optional parameters like bgimage enhance the visual design by allowing a custom background. together, these specifications form the foundation of the card’s visible layout and branding. this image demonstrates the specification fields that define the card’s balance, expiration date, and barcode data in samsung wallet. this image illustrates how the barcode appears when the user taps the pay button on the gift card. the displayed barcode corresponds to barcode.serialtype, which specifies the presentation format (such as barcode or serialnumber). this configuration allows users to redeem their gift cards seamlessly by scanning the code at a merchant terminal. this image demonstrates the use of the csinfo field to store customer support information. telephone number, email address, and website address information can all be stored in it. this image illustrates how the gift card’s display language adapts to the user's device language settings through the localization field. localization allows the user to serve content in multiple languages. when a user sets their device to a specific language, the corresponding localized content is displayed on their device. these specifications collectively define how your gift card appears and behaves in samsung wallet. for more detailed insights, check out the comprehensive gift card document. gift card json structure once you’ve reviewed the gift card specifications, the next step is to define them in the json structure. this data structure contains all the parameters that describe your gift card—including its title, amount, expiration date, barcode details, and optional links. the json is used to generate the card data token, which securely transfers the card information when users tap ‘add to samsung wallet’. the following is an example json file for a sample gift card: { "card": { "type": "giftcard", "subtype": "others", "data": [ { "refid": {refid}, "createdat": {createdat}, "updatedat": {updatedat}, "language": "en", "attributes": { "title": "sample gift card", "eventid": "event-001", "logoimage": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/ghdkj4z2q5o23cwuxsupbg.png", "logoimage.darkurl": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/zdzswfkbtvuvaz35mskmzw.png", "providername": "gift card provider name testing", "user": "john smith", "csinfo": "{\"call\":\"(+82) 1588-3366\",\"website\":\"https://www.samsung.com/us/\"}", "applinklogo": "https://d3unf4s5rp9dfh.cloudfront.net/tango/03-11-2025-wallet-gift-card-applink-logo-image.png", "applinkname": "gift card link", "applinkdata": "https://developer.samsung.com/wallet", "bgimage": "https://d3unf4s5rp9dfh.cloudfront.net/tango/03-11-2025-wallet-gift-card-design-v2.png", "fontcolor": "", "amount": "100p", "startdate": {startdate}, "enddate": {enddate}, "barcode.value": "sdc0102025", "barcode.serialtype": "qrcode", "barcode.ptformat": "qrcodeserial", "barcode.ptsubformat": "qr_code" }, "localization": [ { "language": "ko", "attributes": { "title": "삼성 월렛" } } ] } ] } } noteif you do not specify a fontcolor value, it automatically adapts to your system settings. for instance, in dark mode, the font color is light, and in light mode, it is dark. gift card testing with the ‘add to wallet’ test tool you have created a gift card in the wallet partners portal, now check if the card works properly before further development process. follow these steps to check the card. sign in to the add to wallet test tool, navigate to the playground section, select the gift card from the dropdown menu, and press add to samsung wallet. navigate to the add to wallet menu on the add to wallet test tool site and follow the step-by-step guide provided in the add to samsung wallet test section in the online test tool documentation. ‘add to samsung wallet’ implementation after testing the card with the ‘add to wallet’ test tool, you can let users add it directly to samsung wallet. implement the ‘add to samsung wallet’ button so that user can add the card to their wallet. for more details, refer to the implementing atw button documentation. in the ‘add to samsung wallet’ button implementation process, the generated jwt token expires after 30 seconds. as a result, you need to implement the server logic so that this token generates after the user interaction like pressing a button. see the implementing "add to wallet" in an android application blog to get details on the server-side logic implementation process of an ‘add to samsung wallet’ button in an android application. conclusion bringing your gift cards to samsung wallet creates a secure, seamless, and branded experience for your users. by defining your card data, generating the token, and enabling the add to samsung wallet flow, you make digital gifting effortless and engaging. start integrating today and let users enjoy convenient, personalized gifting within samsung wallet. related resources utilize the add to samsung wallet service for digital cards introduce loyalty cards to your application with samsung wallet implementing "add to wallet" in an android application seamlessly integrate "add to wallet" for samsung wallet
Most Fowziya Akther Houya
tutorials
blogsamsung 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
tutorials
blogsamsung wallet provides an e-wallet service to its customers through wallet cards. adding a card to the user device is normally triggered by user interaction, cards are added to their device when the add to wallet button or link is pressed. the adding wallet cards api provides the functionality to add cards to user devices directly without user interaction. a partner can provide wallet cards to the user’s wallet directly using the user’s email or mobile number. this article demonstrates a complete implementation of the adding wallet cards api. in the example scenario, we add a coupon type card to a user device from a partner’s server using this api without any user interaction. system requirements the adding wallet cards api has the following prerequisites: new samsung wallet users must first complete the onboarding procedure and obtain the required security certificates. create a new coupon card template through the wallet partners portal and launch the card. as a partner you can also create a card template through the partner server. for more details, refer to the create samsung wallet card templates using the server api. using the adding wallet cards api requires explicit permission from samsung. contact samsung developer support for authorization. api fundamentals this restful interface enables partners to deliver wallet cards directly to user accounts from their servers. endpoint: the service url where card addition requests are processed. https://tsapi-card.walletsvc.samsung.com/atw/v1/cards/{cardid} headers: only verified partners can utilize this api. header information establishes secure communication between the partner and samsung servers. authorization: bearer token authentication. refer to json web token documentation for specifications. x-smcs-partner-id: your unique partner identifier required for api access. x-request-id: a unique uuid string that identifies each request. body: must include a cdata parameter containing a jwt token with card details and user account information. detailed api specifications are available in the official documentation. api implementation process the adding wallet cards api enables partners to deliver cards directly to the user's account or wallet. follow this step-by-step approach to implement the api. for a better understanding of the overall process, download the sample source code. step 1: cryptographic key management extract necessary keys from security certificates for jwt token generation in subsequent steps. public key retrieval the following function extracts public keys from partner.crt and samsung.crt certificate files received during the onboarding process. def getpublickey(crt_path): """ extract public 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 public_key_pem except exception as error: print(f"error reading public key from {crt_path}: {error}") return none private key retrieval this function retrieves the private key from the .pem file generated during the onboarding process. def getprivatekey(pem_path): ''' extract private key from a .pem file. ''' 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: authentication token creation samsung validates each api request through an authorization token in jwt format. to generate a valid authentication token: construct an authheader with auth as the payload content type. include the certificate id from my account > encryption management in the wallet partners portal. build the payload using the authheader structure. generate the final authorization token. the following code snippet implements the steps above. 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"/atw/v1/cards/{cardid}" }, } auth_token = jwt.encode( payload=auth_payload, key=privatekey, algorithm='rs256', headers=auth_header ) return auth_token step 3: card data token generation (cdata) the request payload requires a cdata parameter containing a jwt token with card information and user details. follow these steps to construct the cdata token. card information structure build a card data object containing all necessary information about the card to be delivered and the target user account. cdatapayload = { "card": { "type": "coupon", "subtype": "others", "data": [{ "refid": "e389dc8a-4616-494c-a8b3-80380f449fc2", "createdat": 1727913600000, "updatedat": 1727913600000, "language": "ko", "attributes": { "title": "strawberry icecream-1", "orderid": "order-001", "groupingid": "grouping-001", "mainimg": "https://djcpagh05u38x.cloudfront.net/wlt/kr/stg/ihghulmhriqfhi73ydqzca/ldzf4fwlq9i5iqoym1r2yw.png", "brandname": "cioud icecream", "expiry": 1762225720029, "issuedate": 1727913600000, "redeemdate": 1727913600489, "noticedesc": "<div>▶precautions<br>-this product is an example image and may be different from the actual product. <br>-only available within the expiration date.<br><br>", "editableyn": "n", "deletableyn": "y", "displayredeembuttonyn": "n", "addtowalletcouponyn": "y", "notificationyn": "y", "applinklogo": "https://play-lh.googleusercontent.com/o5iwmhhbrmiga_4xdsxmizthld-wwu2ln6fbz6znpdlmkif0i98sfhtwzkyzjan-tw=w240-h480-rw", "applinkname": "cioud icecream", "applinkdata": "https://www.samsung.com/us", "barcode.value": "1111222233334444", "barcode.serialtype": "barcode", "barcode.ptformat": "barcodeserial", "barcode.ptsubformat": "code128" }, }] }, "account": { "type": "email", "value": "example@samsung.com" } } cdata jwt token construction generate the jwt token using the following implementation. additional information about the jwt format is available in the card data token section of the security 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": "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 step 4: build http request and execute with all required components prepared, construct the card addition http request using the following code structure: # --- prepare json body (python dictionary) --- c_data_json_body = { "cdata": cdatatoken } # --- build http request --- headers = { "authorization": "bearer " + authtoken, "x-smcs-partner-id": partnerid, "x-request-id": requestid, "x-request-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 added successfully: " + json.dumps(response.json())) except requests.exceptions.requestexception as e: print("failed to add wallet card:") print(f"error: {e}") if response: print("response body:", response.text) running the application once the four steps described above are implemented, open the sample project and do the following: update the partner id, certificate id, and card id values in src/main.py with your actual credentials. replace the partner.crt, samsung.crt and private_key.pem files with your credential files in the /cert directory. install all dependencies listed in the requirements.txt file using command pip install -r requirements.txt. run the main script using the command python src/main.py in the terminal. after successful execution of the requests, you will get a success message. get the full response code in the response section of the documentation. a push notification is sent to the user’s device to confirm the successful card registration. once this is done, open your samsung wallet and navigate to the coupon card list and you will find the card there. conclusion now that you have familiarized yourself with the process of adding cards to the user device using the adding wallet cards api, you can implement this logic to your server and use it to improve your card management. additional resources for more information on this topic, consult the following resources. complete source code create samsung wallet card templates using the server api official samsung wallet api documentation
M. A. Hasan Molla
Develop Samsung Wallet
doccard template management this subsection defines apis and governance rules for managing wallet card templates a wallet card template represents the structural and operational definition of a wallet card service it defines the card type and subtype design configuration operational flags and policies lifecycle state template lifecycle wallet card templates operate under a controlled lifecycle model each template transitions through defined states before it becomes eligible for issuing wallet card instances typical lifecycle states include status description verifying initial state when a card template is first created all fields and settings are fully editable active the card template is published and visible to users this state is set by the partner through the update api when the card is ready to launch once active, the card cannot be reverted to a previous state blocked card has been blocked by samsung administrator-only action templates must reach an appropriate operational state before wallet card instances can be issued base template requirement before issuing any wallet card instance, a base template must be created the base template serves as the structural foundation for the associated wallet card type and defines its operational configuration card management tools wallet card templates and instances can be managed using the following tools • wallet partners portal ‐ intended for managing individual templates or smaller batches ‐ provides a user interface for lifecycle management, status updates, and administrative review • server api access ‐ designed for partners managing high volumes of wallet cards ‐ supports automation and scalable integration ‐ templates and cards created via api remain visible and manageable in the samsung wallet partners portal • testing mode when a wallet card template is first created, it is automatically placed in testing mode ‐ in testing mode, the wallet card is not publicly available to end users ‐ testing mode must be manually disabled after validation is complete ‐ once testing mode is turned off, it cannot be re-enabled testing mode must be disabled before official deployment template management apis after successful onboarding, partners can create and manage wallet card templates and issue wallet card instances to samsung wallet the card template management interfaces provide apis to • add wallet card templates • update wallet card templates • retrieve wallet card templates these apis define and manage the configuration under which wallet card instances are created once a template is properly configured, authorized partners may add wallet cards to users directly from the partner server using the adding wallet cards process a wallet card template may require administrative approval before it transitions to the active state and becomes eligible for issuing wallet card instances service domain environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card template this section describes how to create a wallet card templates in samsung wallet [request] type value description method post url /partner/v1/card/template 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 payload ctemplatestring required actual payload data in basic json format to establish the communication between partners and samsung wallet * see template specsthis must be in the secure jwt json web token format * see card data token cdata section for more details example post /partner/v1/card/template /*[headers]*/ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /*[payload]*/ { "ctemplate" "<jwt_serialized>" } [response] type value description http status 200 ok payload cardidstring 32 wallet card id example 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } result http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable updating wallet card template wallet card templates updated through api can also be checked and managed in the same way on the ‘wallet partners portal' partners can manage all wallet cards they have created [request] type value description method post url /partner/v1/card/template/{cardid} 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 payload ctemplateobject required actual payload data in basic json format to establish the communication between partners and samsung wallet * see template specsthis must be in the secure jwt json web token format * see card data token cdata section for more details example post /partner/v1/card/template/3hdpejr6qi380 /*[headers]*/ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /*[payload]*/ { "ctemplate" "<jwt_serialized>" } [response] type value description http status 200 ok payload cardidstring 32 wallet card id example 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } result http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable get wallet card templates wallet card templates created through the api can be retrieved via the template list api and are also visible and manageable through the wallet partners portal partners can view and manage all wallet card templates they have created [request] type value description method get url /partner/v1/card/templates 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 example get /partner/v1/card/templates /*[headers]*/ authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok payload templatesobject array required wallet card template object example 200 ok { "resultcode" "0", "resultmessage" "success", "templates" [ { "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" null, "privacymodeyn" "n", "sharebuttonexposureyn" "y", "state" "verifying", "applogoimg" “”, "desc" “” }, { "cardid" "3ctei2riqi9iq", "title" "wallet card title 02", "countrycode" "us", "cardtype" "generic", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" "", "privacymodeyn" "n", "state" "verifying", "category" "membership", "applogoimg" "", "desc" "ntf_us_generic" } ] } 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 template specs template attributes wallet card types wallet card type wallet card subtype boardingpass airlines, trains, buses, others ticket performances, sports, movies, entrances, others coupon others giftcard others loyalty others idcard employees, nationals, students, drivers, guests, others digitalkey doors, residents, hotels, cars, others payasyougo evcharges, others generic others reservation rentalcars, restaurants, accommodations, etickets, taxis, activities, others transitcard others clip businesstrips, trips, others wallet card templates attributes type value description payload cardtemplateobject required wallet card template object cardtemplate titlestring 32 conditional wallet card name* required when adding wallet card template cardtemplate countrycodestring 2 conditional the main headquarters location * required when adding wallet card template cardtemplate cardtypestring 100 conditional this value is set to cardtype * required when adding wallet card template cardtemplate subtypestring 100 conditional this value is set to subtype * required when adding wallet card template cardtemplate designtypestring 100 optional the value that definesthe design type of the wallet card * for generic templates i e , when cardtype is set to generic , set designtype to one of the following values "generic 01", "generic 02", or "generic 03" * default "generic 01" cardtemplate prtnrapppckgnamestring 128 optional the application package name cardtemplate applogoimgstring 200 optional the banner logo image url cardtemplate nonetworksupportynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureynstring 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate prtnrcarddatastring 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to get card data for instance, you can use https //{yourdomain} cardtemplate prtnrcardstatestring 1000 optional [get card state] partner url check the url format below and implement api according to url refer to send card state send card event for instance, you can use https //{yourdomain} cardtemplate statestring 15 optional wallet card's state* default 'verifying'a card is always created in the verifying state; this field cannot be set at creation time use this field in the update api to change the state to active only the verifying → active transition is supported cardtemplate testingmodeoffstring 1 optional testmode off this must be set to either 'y' or 'n' * default ‘n’ * available only when updating templates cardtemplate saveinserverynstring 2 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate categorystring 20 optional select from the following values “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others” * this field is applicable only to generic card templates i e , when cardtype is set to generic cardtemplate descstring 500 optional description cardtemplate layoutobject optional defines presentation rules for card data in samsung wallet this field is applicable only when the designtype is set to generic-{subtype}-default for detailed specifications, see the section layout specs examples boarding pass { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551312", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "boardingpass", "subtype" "airlines", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } event ticket { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551314", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "ticket", "subtype" "entrances", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } } coupon { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551313", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "coupon", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } } gift card { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551315", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "gift", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } } loyalty { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551316", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "loyalty", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } } digital id { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551317", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "idcard", "subtype" "employees", "applogoimg" "http //www yourdomain com/banner_logo_image png", "saveinserveryn" "y", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } pay as you go { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551318", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "payasyougo", "subtype" "evcharges", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } generic card { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551319", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "generic", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "designtype" "generic 02", "nonetworksupportyn" "n", "category" "membership", "privacymodeyn" "n", "preventcaptureyn" "n" } } layout specs this document provides detailed specifications for the layout field used when adding wallet card templates through the card management api it is intended to be referenced from the layout field description in the adding wallet card template overview this section describes the specification of the layout field used when adding wallet card template the layout object defines presentation rules for card data in samsung wallet it does not contain display values directly instead, it references card data using attribute keys layout object structure the layout object consists of three sections header primary auxiliary each section defines a layout preset and a list of entry mappings type value description layout object layoutobject optional defines presentation rules for card data in samsung wallet layout headerobject required defines the header area of the card layout header presetstring 10 required header layout preset allowed values logo, logotext, text layout header entries[]array of object required list of entry mappings that define how header ui slots reference card data layout header entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout header entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primaryobject required defines the primary content area of the card layout primary presetstring 20 required primary layout preset generic cards landscape, square, vertical, textonlyboarding pass threefields, fourfields, fivefields layout primary entries[]array of object required list of entry mappings that define how primary ui slots reference card data layout primary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout primary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primary useboardingtimeboolean optional controls which time is displayed on the boarding pass card - false default displays the departure time- true displays the boarding start timeapplies only when cardtype = boardingpass layout auxiliaryobject required defines additional information displayed when the card is expanded layout auxiliary presetstring 20 optional defines the number of fields to be displayed allowed values twofields, threefields, fourfields layout auxiliary entries[]array of object required ordered list of fields rendered as label–value pairs each value is an attribute key layout auxiliary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout auxiliary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value example { "layout" { "header" { “preset” "logotext", "entries" [ { "entryname" "image_01", "entrykey" "providerlogo" }, { "entryname" "field_01", "entrykey" "providername" }, { "entryname" "subfield_01", "entrykey" "vehiclenumber" } ] }, "primary" { “preset” "square", "entries" [ { "entryname" "image_01", "entrykey" "wideimage" }, { "entryname" "field_01", "entrykey" "grade" }, { "entryname" "field_02", "entrykey" "seatclass" } ] }, "auxiliary" { “preset” "twofields", "entries" [ { "entryname" "field_01", "entrykey" "entrance" }, { "entryname" "field_02", "entrykey" "seatnumber" } ] } } } header – required entryname by preset preset required entryname description logo image_01, subfield_01 logo image with secondary text logotext image_01, field_01, subfield_01 logo image with primary and secondary text text field_01, subfield_01 primary and secondary text without image primary – required entryname by preset preset required entryname description landscape image_01 landscape image only square image_01, field_01, field_02 square image with two text fields vertical image_01, field_01, field_02 vertical image with two text fields textonly field_01 single text field without image primary / auxiliary – field-based presets preset required entryname description twofields field_01, field_02 displays two label–value pairs threefields field_01, field_02, field_03 displays three label–value pairs fourfields field_01, field_02, field_03, field_04 displays four label–value pairs fivefields field_01, field_02, field_03, field_04, field_05 displays five label–value pairs allowed where applicable data mapping layout → card data the layout object does not contain display values each field defined in layout references card data using an attribute key this section describes how attribute keys are resolved data resolution rule when a field is defined in layout, the value is resolved from the following locations in order card data[] attributes card data[] attributes extendedfields[] entrykey standard attribute mapping if the entrykey defined in layout matches a field inside card data[] attributes the value is resolved directly from that attribute example layout … "primary" { … “preset” "square", "entries" [ { "entryname" "field_01", "entrykey" "providername " }, … } … example card data[] "attributes" { … "providername" "samsung wallet" … } extended fields mapping in addition to predefined attributes, layout fields may reference values inside extendedfields extendedfields is a user-defined data container that allows partners to define additional fields not included in the standard card specification extendedfields structure { "card" { "data" [ { … "attributes" { … "extendedfields" [ { "label" "gate", "value" "a12", "entrykey" "gatenumber" }, { "label" "zone", "value" "3", "entrykey" "boardingzone" } ] } } ] } } extendedfields resolution logic if the layout field key does not exist in predefined attributes the system searches attributes extendedfields[] entrykey when a matching entrykey is found value → resolved from extendedfields[] value label → resolved from extendedfields[] label example layout referencing extendedfields … "auxiliary" { “preset” "twofields", "entries" [ { "entryname" "field_01", "entrykey" "gatenumber" }, { "entryname" "field_02", "entrykey" "boardingzone" } ] } … result • gatenumber → value "a12", label "gate" • boardingzone → value "3", label "zone" mapping priority if the same key exists in both • predefined attributes • extendedfields the resolution priority is • attributes predefined fields • extendedfields summary • layout fields reference data by attribute key • standard attributes are resolved first • extendedfields enables user-defined data expansion • layout does not directly contain display value
Develop Samsung Wallet
docconcept & scope this section defines business-oriented and server-driven integration capabilities for samsung wallet cards unlike the standard add to samsung wallet integration model described, which is typically initiated by end-user interaction for example, clicking an add to wallet button or invoking a link , this section describes apis that enable authorized partners to manage wallet card templates and add wallet cards through backend server communication for approved business purposes these capabilities are intended for controlled operational scenarios where wallet card templates must be managed centrally card issuance is initiated by the partner backend system administrative authorization is required lifecycle governance and state transitions must be programmatically controlled all apis defined in this section require authentication and authorization as specified in security & authentication this section covers card template management server-initiated adding wallet card notification handling card template structural specification layout specification for generic design types
Develop Samsung Wallet
docnfc capabilities this section describes how nfc-related capabilities are defined and handled within the add to wallet process nfc support is an optional capability and is not enabled by default it applies only to wallet card templates that are explicitly configured to support nfc functionality nfc capability requires prior coordination with samsung and is available only to partners that have completed the required onboarding and approval process nfc capability configuration at template level nfc capability is determined at the wallet card template level when creating or configuring a wallet card template nfc capability may be specified as part of template configuration nfc configuration requires coordination and approval from samsung nfc capability is available only to approved partners the nfc configuration defined at the template level determines whether nfc-related data elements may be required during card issuance templates that are not configured for nfc support must follow the standard add to wallet flow without nfc-related processing effect on add to wallet processing when a wallet card template is configured to support nfc functionality additional nfc-related data elements may be required as part of the add to wallet request issuance behavior may differ from standard wallet cards depending on template configuration additional processing may occur during card issuance based on the configured nfc option cards whose templates are not configured for nfc capability must follow the standard add to wallet processing model relationship to access integration some nfc-enabled templates are intended to support access-related interactions for such templates additional integration steps are required beyond the scope of this specification detailed technical and operational requirements are defined in the separate access integration guide access-related nfc processing is governed by a dedicated integration program and is available only to approved partners this document does not define the technical details of nfc-based access issuance, provisioning, or runtime interaction
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 card template 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 wallet card 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 card 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 some card types support a flexible layout design 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 card template 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 card template 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 card template 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 card template 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 2 the cdata format varies depending on the card type e g , loyalty card, ticket, coupon 3 refer to the [_cdata generation sample code_][cdata generation sample code] on the partners portal for detailed guidance 4 copy the sample **‘add to wallet’** script from [_partners portal’s wallet card_][partners portal’s wallet card] page 5 replace the placeholder "cdata" in the script with your generated tokenized card data 6 apply the script to your system see [_partners portal’s wallet card_][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 step 6 – merchant push notification partners can create a message template for sending pushes on each of their wallet cards type partners can only choose the merchant push type message type you can choose a message type from marketing or others rejected comment if the merchant push notification is rejected after request approval, you can modify the message template the administrator registers the reason for rejection when rejecting the merchant push notification it is sent to the partner by email from the system, including the reason for rejection partners can request for approval again by checking the reason for rejection and modifying the message template approved date displays the date and time when the push message is approved by the administrator message template you can create the contents of the push, and it is also possible to put the available variables in '{{}}' after configuring the content, click harmfulness verification to verify whether there is a harmful expression in the content the verified result is displayed as pass or fail, and if it is fail, it shows the filtered harmful expression together even if the verified result is fail, an approval request can be made, but it can be rejected by the administrator if a different language is added to the default language in general information, the message template must also be entered for each added language request approval button after completing the message template, click this button to send an e-mail requesting approval to the administrator configure the wallet card layout samsung wallet offers the flexibility to customize card layouts according to your preferences samsung wallet supports 2 different layout types while all cards can use the default layout type, the flexible layout type is only available for specific cards this section defines the design and attributes of the wallet cards to be supported through the flexible layout type supported card types with flexible layout the card types that support the flexible layout type are as follows loyalty membership , coupon, event ticket, generic card, boarding pass create a card with flexible layout when creating a wallet card that supports the flexible layout type, the user can choose between the default and flexible layouts when selecting the card type to create a wallet card with a flexible layout create a wallet card select the wallet card template to use select the type and sub type for the wallet card template selecting a card type that supports a flexible layout will display the available flexible layout identifiable by the name 'generic-subtypename-default' note-please choose carefully, as the layout type cannot be changed once the card is activated card design and attribute configuration step 1 determine the layout preset to determine the layout preset in the template editor, click the preset change button to modify the layout design presets consist of a combination of three areas card header area, card primary area, and card auxiliary area select each tabs respectively to create the desired combination note-the design types provided vary by card type and area note-• changing the preset updates all previously saved layouts • once a card has been activated, its layout cannot be modified ensure thorough testing before releasing the card card header area choose from six option, including logo type and sub-text combinations logo type logo image, logo image + text, text only the card header area has the same configuration across all card types, and 6 available configurations card primary area the main section that determines the card's primary layout the card primary area is configured differently for each card types the primary area of loyalty membership , coupon, event ticket, generic card has 7 available configurations the primary area of a boarding pass has 4 available configurations card auxiliary area select the number of text fields needed to provide additional information the card auxiliary area is configured differently for each card types the auxiliary area of loyalty membership ,, coupon, event ticket, generic card has 5 available configurations the auxiliary area of a boarding pass has 6 available configurations step 2 define key values for each attribute in the layout to define the key values for each attribute click on an empty container in the card preview where the key has not been set when an empty container consists of a label and a value pair, the label and value are selected as a group setting either a label or a value synchronizes and applies the values across all grouped containers click the entry key button to view the supported attribute names please refer to the wallet card spec for details on the attributes of each entry key boarding pass | event ticket | coupon | loyalty membership | generic card select an attribute from the list or if the desired attribute is not available, enter the value directly in the direct input field when selecting from the attribute list, samsung wallet's supported text will appear in your application save the key value by clicking the save button once all configurations are complete, click apply to implement the layout step 3 prepare card data matching the layout design to prepare the card data matching the chosen layout design refer to the specifications for each card type for wallet card data if you used direct input during layout setup, provide an extendedfields attribute corresponding to the key value entrykey the key entered in the input field label the name displayed in your application value the data corresponding to the label "extendedfields" "[{\"label\" \"group/boarding\", \"value\" \"6/10 35\", \"entrykey\" \"group/boarding\"}]"
Develop Samsung Wallet
docnotification 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
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.
You have successfully updated your cookie preferences.