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
doctemplate management api 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 draft initial state when a card is first created all fields and settings are fully editable verifying verification process by samsung administrators requires completion of general information and csr certificate signing request registration * see key & certificate lifecycle certificate-based onboarding rejected card did not pass verification rejection reasons are emailed to the partner cards can be revised and resubmitted active card has been approved and is now visible to users activation is final and cannot be undone blocked card has been blocked by samsung administrator-only action 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, authorised 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 may use the "bearer" authorisation scheme 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 may use the "bearer" authorisation scheme 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 [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 template retrieve one wallet card template created through the api by its wallet card id cardid [request] type value description method get url /partner/v1/card/template/{cardid} headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme 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 randomly generated uuid string path parameters cardidstring 32 required wallet card identifier issued through the partner portal get /partner/v1/card/template/3hdpejr6qi380 authorization <jwt_serialized> x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [response] type value description http status 200 ok payload templateobject required wallet card template object { "resultcode" "0", "resultmessage" "success", "template" { "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" "" } } [result] http status code description 200 200 ok 400 400 bad request 401 401 unauthorized — the 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 results can be paged with the offset and limit query parameters if both are omitted, the api returns the full list without paging metadata for backward compatibility [request] type value description method get url /partner/v1/card/templates headers authorizationstring 1024 required credential token the token may use the "bearer" authorisation scheme 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 query parameters offsetinteger optional zero-based start index default 0 must not be negative limitinteger optional number of items to return default 20; maximum 100 if offset and limit are both omitted, the full list is returned without paging metadata values outside 1–100 return 400 bad request wdt1n1002 get /partner/v1/card/templates?offset=0&limit=20 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 totalcountinteger optional total number of templates matching the request included only when offset or limit is supplied offsetinteger optional resolved offset value included only when offset or limit is supplied limitinteger optional resolved limit value included only when offset or limit is supplied 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" } ] } example paged { "resultcode" "0", "resultmessage" "success", "totalcount" 137, "offset" 0, "limit" 20, "templates" [{ "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "state" "verifying" }] } [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, 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 defines the 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 partner url for the get card data endpoint implement the endpoint according to the referenced api contract example https //{yourdomain} cardtemplate prtnrcardstatestring 1000 optional partner url for the send card state send card event endpoint implement the endpoint according to the referenced api contract example https //{yourdomain} cardtemplate statestring 15 optional wallet card's state * default 'draft' cardtemplate testingmodeoffstring 1 optional testmode off this must be set to either 'y' or 'n' * default ‘n’ * available only when updating templates cardtemplate 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 event ticket coupon gift card loyalty digital id pay as you go generic card 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 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 illustrative layout fragment not a complete json document { … "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 " }, … } … 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 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 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
doccreate and launch a card programme this chapter defines the card programme configuration and payload fields that determine how a card is presented in samsung wallet complete it before generating production add to samsung wallet links start with the portal workflow, then use the common data model and the specification for your selected card type read the barcode, structured-data and image pages only when your design uses those fields design completion criteria before moving to security and implementation, confirm that the card type and subtype match the approved use case; the card programme has a card id; every required common and card-type-specific attribute has a value source; all image assets meet the documented dimensions and formats; the barcode or qr-code format, if used, can be produced by the partner system; and the card has been validated in testing mode template management a wallet card template defines the ui layout, card attributes, and behaviour policies e g , privacy mode, capture prevention applied to wallet cards partners can create and manage wallet card templates using one of the following methods portal-based management create and manage templates manually through the partner portal api-based management create and manage templates programmatically through apis for automation and system integration this section provides an overview of template management via the portal and via apis overview the following figure illustrates the overall flow of wallet card template management and its usage description the partner creates and manages a wallet card template in advance via portal or api when issuing or registering a wallet card, the system references the template and applies the defined layout and policies template updates should be managed carefully, considering operational policies such as versioning and the scope of impact e g , new cards vs existing cards manage wallet card template via portal partners can create and manage wallet card templates using the portal portal-based management is useful for initial setup, manual operations, and administrative control main capabilities create a template view and search templates update a template manage template operational settings e g , status, test/production-related options basic procedure example sign in to the portal and navigate to the wallet card template management menu select create template enter required fields e g , title, card type/subtype configure optional/conditional fields as needed e g , no-network support, share button exposure, privacy mode, capture prevention save and verify the created template update the template or operational settings if required note portal ui labels and menu names may vary depending on the portal version step 1 - create wallet cards templates begin by drafting the cards that will be added to samsung wallet these cards can include loyalty cards, tickets, boarding passes, and more draft status - initially, these cards will be in draft status until they are fully configured and ready for testing private key helps to enable encryption and is the most important component of certificates manage cards partners can manage all registered wallet cards this includes edit, update, and monitor the status of the wallet cards general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet folder contents testing mode all data generated in testing mode is periodically deleted be sure to turn off the "testing mode" setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name partner app package name partner application package name wallet card template pre-defined partner wallet card template partner get card data url for the partner api call to receive card data if the partner uses this api, enter the url otherwise leave it blank partner send card state url for the partner api call to send a card state notification if the partner uses this api, enter the url otherwise leave it blank samsung server ips samsung wallet server ips which need to be allowed by the partner’s firewall, separately described for inbound and outbound wearable wallet assistance whether to support the wearable wallet service support ‘no network’ status whether to support wallet card opening during the ‘no network’ status description description of the wallet card select template the samsung wallet portal offers various wallet card templates optimised for different use cases, including boarding passes, tickets, coupons, and digital ids to streamline your integration, you can easily select the appropriate template from the select wallet card template pop-up window steps to select wallet card template navigate to the select wallet card template option within the portal in the wallet card type drop-down menu, select the category that best suits your use case e g , boarding pass, ticket, coupon, or digital id once the card type is selected, a list of templates will appear in the wallet card sub type section choose one of the available templates from the list that corresponds to your selected card type after selecting the template, you can proceed with configuring the card’s details, including the branding, content, and data fields specific to the selected template samsung wallet supports various wallet card types designed to cater to different use cases each card type is optimised for specific functions, making it easier for partners to provide a seamless experience to users note refer to section wallet card type to learn more about it view wallet cards partners can easily manage all their registered wallet cards through the samsung wallet portal this includes the ability to view, edit, and delete wallet cards as needed step 2 - launch wallet cards verifying status once a wallet card is ready for launch, it must go through the verifying status before it can be activated and made available to users partners can launch and activate their cards once they have been reviewed and approved, ensuring the card meets all requirements steps to launch wallet cards to begin the launch process, click yes to confirm and approve the activation of the wallet card to begin the activation process, click the launch button for the card you wish to activate once a card is launched, the button text changes to launched the activation cannot be cancelled after the card is launched, its status will change to verifying during this stage, the system will conduct a final review to ensure all information is accurate and meets the necessary requirements after verification, the card will undergo administrator approval the admin will review and approve the card for activation once the card is approved by the administrator, its status will change to active, making it available for users to add to their samsung wallet launch wallet cards rejected status if the wallet card is rejected after launching, you can modify the card and re-launch steps to modify the card and re-launch the administrator registers the reason for rejection when rejecting the launched wallet card it is sent to the partner by email from the system, including the reason for rejection partners can apply for launch again by checking the reason for rejection and modifying the wallet card information step 3 – testing mode partners can use the testing mode to test a wallet card internally before it is officially released to users this feature ensures that all aspects of the card, including its functionality and user experience, are working as expected when you create a new wallet card, the testing mode option is enabled by default, allowing you to perform internal tests without affecting user access all data generated during testing is periodically deleted to ensure that no test data remains in the system once testing is complete even though testing mode is enabled, the card is still visible and accessible in the system testing does not prevent the card from being exposed to users, so you can verify its functionality without any restrictions once testing is complete and you are satisfied with the card’s performance, be sure to turn off testing mode note remember to change the status from testing mode on to testing mode off to finalize the testing process and prepare the card for official release step 4 - admin approval active status after a wallet card is launched, it must go through an administrator approval process before it becomes active and visible to users steps for admin approval once the launch button is clicked, the card’s status automatically changes to verifying during this stage, the card is reviewed for accuracy, completeness, and compliance with samsung wallet requirements note please ensure that testing is completed using either your own implementation or the add to wallet test tool, as the samsung wallet administrator will verify the results through server-side test logs 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 approval readiness and required evidence before administrator approval is granted, the partner may be required to demonstrate that the proposed card programme has completed the necessary implementation, validation and operational readiness checks typical approval evidence may include successful end-to-end integration test results server-side test logs demonstrating expected registration, callback and update behaviour evidence that required security controls are implemented confirmation that the card template, content and user-facing behaviour match the approved use case verification that mandatory tracking, callback handling, and lifecycle processing are functioning correctly for access-related programmes, evidence of capability validation, security review completion and model-specific readiness important notes the exact approval scope and required evidence may vary depending on the card type, business model, region, and whether access capability is involved samsung may request additional validation artifacts, scenario-based test evidence, or security-related documentation for specific use cases completion of implementation alone does not guarantee approval administrator approval is granted only after samsung confirms that the service satisfies the applicable technical, operational, and policy requirements next — implement card addition after the card programme and template are ready, continue to secure your integration and add cards to samsung wallet the card addition contract and channel-specific entry-point guidance are maintained there so that this portal procedure does not duplicate them optional — configure a merchant push template 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 manage wallet card template via api partners can create and manage wallet card templates programmatically using the card template management this approach is recommended for automation, bulk operations, and integration with partner back-end systems prerequisites / access control api-based template management is available only after successful partner onboarding samsung administrative permission/approval is required to use server-side apis if your account is not authorised, the api features may be unavailable until approval is granted typical use cases automatically create/update templates from an internal system to standardize operations manage templates for multiple services/brands at scale integrate template lifecycle management into deployment pipelines or operational tools related specifications for detailed api definitions endpoints, headers, request/response formats and card-type-specific template specifications, refer to template management apis
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 behaviour 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 programme 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
docwhen to use advanced integrations the capabilities in this chapter are not prerequisites for a standard user-initiated add to samsung wallet integration implement them only when they are required by the approved business flow or operational scale if you are building your first card, return to build your first card and defer this chapter until the base flow works end to end advanced integrations extend the standard user-initiated add flow they introduce additional user-resolution, template-automation, action or device-capability requirements and should be selected during onboarding rather than discovered during implementation 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 authorisation is required an approved flow requires action data or nfc capability all apis defined in this section require authentication and authorisation as specified in security & authentication this section covers card template management server-initiated adding wallet card card template structural specification layout specification for generic design types notifications and ordinary lifecycle updates are covered in manage card lifecycle because they may be part of a standard integration
Develop Samsung Wallet
docnotifications 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 personalised push messages to samsung wallet users, linked to their wallet cards samsung wallet enables authorised 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 unauthorised 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 card data variables use double-bracket placeholders with [[ ]] syntax to resolve an attribute from each recipient wallet card at send time the partner does not include this value in the notification request card data variables are resolved independently of partner-supplied {{ }} variables and are supported by send notification, create targeted notification job, and adding notification templates massive the bracketed name must exactly match an attribute key defined for that card type in card specs missing or empty attributes resolve to an empty string; single brackets [ ] are not variables source content notification template hi {{name}}, your seat is [[seatnumber]] partner-supplied request data { "name" "logan" } card attributes { "seatnumber" "a12" } delivered notification hi logan, your seat is a12 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 notification behaviour occurs after card enrolment for this reason, geofence notification is described as a specialised 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 behaviour 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 behaviour on the device step 4 add the card and grant location access the user adds the card to samsung wallet to support location-triggered behaviour, 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 may use the "bearer" authorisation scheme e g , bearer <credentials> * refer to 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" "<ndata_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 may use the "bearer" authorisation scheme 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 may use the "bearer" authorisation scheme 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 may use the "bearer" authorisation scheme 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 may use the "bearer" authorisation scheme 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 [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 may use the "bearer" authorisation scheme 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 queryparameters notificationid string 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 start timestamp ms required start date unix timestamp in milliseconds endtimestamp ms required end date unix timestamp in milliseconds metric string 32 required metric impression|click [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.