Filter

Card Templates 40
Sorry, no results
found for "Card Templates" on the website

tutorials

blog

Create Samsung Wallet Card Templates Using the Server API

samsung 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

https://developer.samsung.com/sdp/blog/en-us/2025/10/07/create-samsung-wallet-card-templates-using-the-server-api

tutorials

blog

Update Samsung Wallet Card Templates Using the Server API

card 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

https://developer.samsung.com/sdp/blog/en-us/2025/11/18/update-samsung-wallet-card-templates-using-the-server-api

tutorials

blog

Integrate Personalized Gift Cards for a Seamless Wallet Experience

samsung 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

https://developer.samsung.com/sdp/blog/en-us/2025/12/11/integrate-personalized-gift-cards-for-a-seamless-wallet-experience

tutorials

blog

Adding Cards to a User Wallet Using the Adding Wallet Cards API

samsung 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

https://developer.samsung.com/sdp/blog/en-us/2025/12/18/adding-cards-to-a-user-wallet-using-the-adding-wallet-cards-api

Develop Samsung Wallet

doc

NFC Capabilities

nfc capabilities this section describes how nfc-related capabilities are defined and handled within the add to wallet process nfc support is not enabled by default and applies only to wallet card templates that are explicitly configured to support nfc functionality nfc capability configuration at template level support for nfc functionality is determined at the wallet card template level when creating or configuring a wallet card template nfc capability may be specified as part of the template configuration nfc capability configuration requires coordination with samsung nfc capability is available only to partners that have completed the required onboarding process the nfc configuration defined at the template level determines how nfc-related elements are handled during card issuance effect on add to wallet processing when a wallet card template is configured to support nfc functionality nfc-related data elements may be required as part of the add to wallet request the structure and validation of such elements depend on the template configuration additional processing may occur during card issuance based on the configured nfc option cards whose templates are not configured for nfc support follow the standard add to wallet flow without nfc-related processing relationship to access integration for templates configured with nfc functionality, partners must implement additional integration steps to support nfc-based interactions these integration steps are not defined in this document detailed technical and operational requirements are provided in the separate access guide

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

Develop Samsung Wallet

doc

Manage Wallet Card

manage wallet card the samsung wallet partners portal provides partners with the necessary tools and functionality to integrate the “add to samsung wallet” feature into their services this guide outlines the process of registering, managing wallet cards, and ensuring that everything runs smoothly refer to the partner onboarding guide for the samsung wallet portal the partners need to complete the following steps to register and gain access to the samsung wallet portal note-wallet portal currently offers 'add to samsung wallet' functionality to the partners overall managing process once registered and logged into the samsung wallet portal, partners can follow the steps to manage wallet cards and monitor performance step 1 - create wallet card template begin by drafting the cards that will be added to samsung wallet these cards can include loyalty cards, tickets, boarding passes, and more draft status - initially, these cards will be in draft status until they are fully configured and ready for testing manage wallet card partners can manage all registered wallet cards this includes edit, update, and monitor the status of the wallet cards general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet folder contents testing mode all data generated in testing mode is periodically deleted be sure to turn off the "testing mode" setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name partner app package name partner application package name wallet card template pre-defined partner wallet card template partner get card data url for the partner api call to receive card data if the partner uses this api, enter the url otherwise leave it blank partner send card state url for the partner api call to send a card state notification if the partner uses this api, enter the url otherwise leave it blank samsung server ips samsung wallet server ips which need to be allowed by the partner’s firewall, separately described for inbound and outbound wearable wallet assistance whether to support the wearable wallet service support ‘no network’ status whether to support wallet card opening during the ‘no network’ status description description of the wallet card select card template the samsung wallet portal offers various wallet card templates optimized for different use cases, including boarding passes, tickets, coupons, and digital ids to streamline your integration, you can easily select the appropriate template from the select wallet card template pop-up window steps to select wallet card template navigate to the select wallet card template option within the portal in the wallet card type drop-down menu, select the category that best suits your use case e g , boarding pass, ticket, coupon, or digital id once the card type is selected, a list of templates will appear in the wallet card sub type section choose one of the available templates from the list that corresponds to your selected card type after selecting the template, you can proceed with configuring the card’s details, including the branding, content, and data fields specific to the selected template samsung wallet supports various wallet card types designed to cater to different use cases each card type is optimized for specific functions, making it easier for partners to provide a seamless experience to users note-refer to section wallet card type to learn more about it view wallet card template partners can easily manage all their registered wallet cards through the samsung wallet portal this includes the ability to view, edit, and delete wallet cards as needed step 2 - launch wallet card template verifying status once a wallet card is ready for launch, it must go through the verifying status before it can be activated and made available to users partners can launch and activate their cards once they have been reviewed and approved, ensuring the card meets all requirements steps to launch card template to begin the launch process, click yes to confirm and approve the activation of the wallet card to begin the activation process, click the launch button for the card you wish to activate once a card is launched, the button text changes to launched the activation cannot be cancelled after the card is launched, its status will change to verifying during this stage, the system will conduct a final review to ensure all information is accurate and meets the necessary requirements after verification, the card will undergo administrator approval the admin will review and approve the card for activation once the card is approved by the administrator, its status will change to active, making it available for users to add to their samsung wallet launch wallet card template rejected status if the wallet card is rejected after launching, you can modify the card and re-launch steps to modify the card and re-launch the administrator registers the reason for rejection when rejecting the launched wallet card it is sent to the partner by email from the system, including the reason for rejection partners can apply for launch again by checking the reason for rejection and modifying the wallet card information step 3 – testing mode partners can use the testing mode to test a wallet card internally before it is officially released to users this feature ensures that all aspects of the card, including its functionality and user experience, are working as expected when you create a new wallet card, the testing mode option is enabled by default, allowing you to perform internal tests without affecting user access all data generated during testing is periodically deleted to ensure that no test data remains in the system once testing is complete even though testing mode is enabled, the card is still visible and accessible in the system testing does not prevent the card from being exposed to users, so you can verify its functionality without any restrictions once testing is complete and you are satisfied with the card’s performance, be sure to turn off testing mode note-remember to change the status from testing mode on to testing mode off to finalize the testing process and prepare the card for official release step 4 - admin approval active status after a wallet card is launched, it must go through an administrator approval process before it becomes active and visible to users steps for admin approval once the launch button is clicked, the card’s status automatically changes to verifying during this stage, the card is reviewed for accuracy, completeness, and compliance with samsung wallet requirements note-please ensure that testing is completed using either your own implementation or the add to wallet test tool, as the samsung wallet administrator will verify the results through server-side test logs an administrator will review the submitted wallet card to ensure it meets all content and technical guidelines if the card passes the review, it is approved for activation upon administrator approval, the card status updates 'active' once the card reaches active status, it becomes visible and accessible to end users, enabling them to add it to their wallets step 5 – add to samsung wallet integration to integrate the "add to samsung wallet" feature into your system, you need to insert the appropriate "add to wallet" script this script is available for various platforms, including web, android, and email/mms, and each platform requires a slightly different implementation approach follow the steps below to successfully implement the "add to wallet" button create the tokenized card data, known as cdata, which contains the actual wallet card content note-since cdata has a time-to-live ttl of 30 seconds, it is recommended that the system generates cdata in real time to ensure it remains valid when processed the cdata format varies depending on the card type e g , loyalty card, ticket, coupon refer to the cdata generation sample code on the partners portal for detailed guidance copy the sample ‘add to wallet’ script from partners portal’s wallet card page replace the placeholder "cdata" in the script with your generated tokenized card data apply the script to your system see partners portal’s wallet card for details note-for "add to wallet" integration, you may need some base data you can find that and other necessary information on partners portal and wallet api spec you can also add image beacon in the script for tracking effect analysis add to wallet script guide step 6 – merchant push notification partners can create a message template for sending pushes on each of their wallet cards type partners can only choose the merchant push type message type you can choose a message type from marketing or others rejected comment if the merchant push notification is rejected after request approval, you can modify the message template the administrator registers the reason for rejection when rejecting the merchant push notification it is sent to the partner by email from the system, including the reason for rejection partners can request for approval again by checking the reason for rejection and modifying the message template approved date displays the date and time when the push message is approved by the administrator message template you can create the contents of the push, and it is also possible to put the available variables in '{{}}' after configuring the content, click harmfulness verification to verify whether there is a harmful expression in the content the verified result is displayed as pass or fail, and if it is fail, it shows the filtered harmful expression together even if the verified result is fail, an approval request can be made, but it can be rejected by the administrator if a different language is added to the default language in general information, the message template must also be entered for each added language request approval button after completing the message template, click this button to send an e-mail requesting approval to the administrator wallet card types wallet card type boarding pass ideal for airlines, train services, or event check-ins allows users to add their travel or event tickets to samsung wallet for easy access and quick scanning wallet card type tickets designed for digital tickets to events such as concerts, movies, sports games, or other events ensures smooth entry by providing users with a digital copy of their ticket directly on their device wallet card type coupons perfect for promotional offers, discount vouchers, gift cards, or loyalty rewards users can redeem or use these coupons directly from their samsung wallet, making the process faster and more efficient wallet card type digital id used for membership cards, loyalty programs, and identification purposes can store digital versions of cards like gym memberships, library cards, or other forms of identification wallet card type gift card digital versions of physical gift cards, which users can add to their samsung wallet for quick and easy access useful for retail, online stores, and various gift card services wallet card type loyalty card designed for businesses offering loyalty programs where customers earn points for purchases or engagement users can view their point balance, check available rewards, and redeem points directly from their samsung wallet

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

Develop Samsung Wallet

doc

Notification for Partners

notification for partners deliver personalized push messages to samsung wallet users, linked to their wallet cards samsung wallet enables authorized partners to send targeted push notifications using pre-approved message templates this feature supports marketing, transactional, and engagement-driven use cases only partners with administrative approval can access and use the notifications feature the notifications tab is hidden for unauthorized accounts notification workflow overview step 1 create notification template partners can create push message templates through the partner portal or notification api templates define the structure and content of the notification type only merchant push is supported message category choose from marketing or other variables use dynamic placeholders with {{ }} syntax e g , hello {{name}}, your pass for {{event}} is ready if your wallet card supports multiple languages, a message template must be provided for each language variant after drafting the message run harmfulness check to detect prohibited content results pass or fail even if failed, templates can still be submitted but may be rejected in the next step step 2 request template approval once the template is complete click the request approval button in the portal an administrator will review the content if rejected the reason is provided via system email partners can revise and resubmit the template for approval if approved the approved date will appear in the portal the template becomes eligible for use in the notification api step 3 push notification with template once a template is approved, partners can push notifications to users linked to their wallet cards using a secure post api request required parameters template id – issued after template approval reference id – a unique identifier tied to the user’s wallet card created during the add to wallet process only pre-approved templates can be used in push requests step 4 monitor impressions and clicks after the push is delivered, partners can track impressions – number of users who viewed the notification clicks – number of interactions with the push these metrics can be accessed through the partner portal dashboard, enabling performance evaluation of each campaign 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/{card id}/notifications/{template id}/send header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type e g , bearer <credentials> * refer to authorization token 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 card idstring 32 required wallet card identifier granted from partners portal template idstring 32 required approved notification template identifier from partners portal payload ndatastring required notification object json * this field needs to be encrypted * refer to security 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 data object required name-value pair for use in notification template [example] post /wltex/cards/12584806754/notifications/12353465344/send /*[headers]*/ authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /*[payload]*/ { “ndata” “eyjjdhkioijbvvriiiwidmvyi…” } /*[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 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 adding notification templates in general, card notification creation is possible through the ‘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 ‘wallet partners portal' [request] type value description method post url /partner/v1/card/template/{card id}/notification header authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters card idstring 32 required the wallet card identifier granted through the partner 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 security 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 eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/] { "ntemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [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/{card id}/notification headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters card idstring 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template [example] get /partner/v1/card/template/3hdpejr6qi380/notification [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr [response] type value description http status 200 ok [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/{card id}/stats/notifications headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string path parameters card idstring 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template query parameters notificationidstring 32 optional if specified, statistics are returned only for the specified notification if not specified, aggregated statistics for all notifications of the card are returned starttimetamp ms required start date unix timestamp in milliseconds endtimestamp ms required end date unix timestamp in milliseconds metricstring 32 required metric impression click [example] get /partner/v1/card/template/3hdpejr6qi380/stats/notifications?notificationid=123456789&start=1764514800000&end=1765465200000&metric=impression [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr [response] type value description http status 200 ok [200 ok] { "resultcode" "0", "resultmessage" "success", "statistics" [ [ 1764820800000, 1 ], [ 1764896400000, 2 ], [ 1764900000000, 1 ], [ 1764903600000, 0 ], [ 1764907200000, 1 ], [ 1765134000000, 0 ] ] } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable

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

Develop Samsung Wallet

doc

Card Management API Guidelines

card management api guidelines once your service is successfully onboarded, you gain the ability to design and deploy custom digital assets—such as boarding passes, coupons, tickets, and more—directly to samsung wallet the adding samsung wallet card templates section defines interfaces for providers to conveniently create wallet cards in samsung wallet the generated wallet card templates can be updated by following the instructions on the updating wallet card templates section authorized partners can add wallet cards to users directly from the partner server by following the instructions on the adding wallet cards section below service domain environment domain public domain https //tsapi-card walletsvc samsung com adding wallet card templates this section describes how to create a wallet card in samsung wallet [request] type value description method post url /partner/v1/card/template headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object titlestring 32 required wallet card name countrycodestring 2 required the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtypestring 100 required template card typefor details, refer to wallet cards subtypestring 100 required template card sub typefor details, refer to wallet cards designtypestring 100 optional the value that definesthe design type of the wallet card for details, refer to wallet cards applogoimgstring 200 optional the banner logo image url the maximum size of the image is 1024*1024 e g ttp //www yourdomain com/banner_logo_image png saveinserverynstring 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type prtnrapppckgnamestring 128 optional the application package name nonetworksupportynstring 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' sharebuttonexposureynstring 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' privacymodeynstring 1 optional if this value is set, the user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' preventcaptureynstring 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture categorystring 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance, parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others prtnrcarddatastring 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain prtnrcardstatestring 1000 optional [get card state] partner url check the url format below and implement api according to url refer to partner server api specification for instance, you can use https //yourdomain prtnrmempointstring 1000 optional [get membership point] partner url cardmetacpstring 1000 optional [get card meta cp] partner url getfulfillmentliststring 1000 optional [get fulfillment list] partner url prtnrbalancestring 1000 optional [get card balance] partner url statestring 15 optional when creating a card, you can transition the card's state from “draft” to “verifying” you can only choose “draft” or “verifying” * default 'draft' descstring 500 optional description example /** example card template object **/ { "title" "coupon", "countrycode" "kr", "cardtype" "coupon", "subtype" "others", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable updating wallet card templates wallet card templates updated through api can also be checked and managed in the same way on the ‘wallet partners portal' partners can manage all wallet cards they have created [request] type value description method post url /partner/v1/card/template/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required the wallet card identifier granted through the partner portal * the identifier is needed when updating a specific card template body parameters ctemplate object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object titlestring 32 required wallet card name countrycodestring 2 optional the main headquarters location code refer to iso-3166-1 alpha-2 for the country code prtnrapppckgnamestring 128 optional the application package name applogoimgstring 200 optional the banner logo image url the maximum size of that image is 1024*1024 saveinserverynstring 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type nonetworksupportynstring 1 optional sets whether to support opening the wallet card under 'no network' status this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'n' sharebuttonexposureynstring 1 optional sets whether to support the sharing function this feature cannot be modified after the wallet card is approved this must be set to either 'y' or 'n' * default 'y' privacymodeynstring 1 optional if this value is set, user authentication is required when using the card to protect the user's sensitive information this must be set to either 'y' or 'n' * default 'n' preventcaptureynstring 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture categorystring 20 optional this item can only be set if the card type is “generic” set the category to get more detailed statistical information for instance parking pass, membership, reservations, insurance, health, receipt, coupon stamp, note, photo, and others prtnrcarddatastring 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomainn prtnrcardstatestring 1000 optional partner url check the url format below and implement the api according to the url refer to partner server api specification for instance, you can use https //yourdomain prtnrmempointstring 1000 optional [get membership point] partner url cardmetacpstring 1000 optional [get card meta cp] partner url getfulfillmentliststring 1000 optional [get fulfillmet list] partner url prtnrbalancestring 1000 optional [get card balance] partner url statestring 15 optional if the card status is “draft”, you can only select “verifying” testingmodeoffstring 1 optional this value can be set only when the card status is active normal service is possible only when the testing mode is changed to off * default ‘n’ descstring 500 optional description [example] /* *example card template object **/ { "title" "coupon", "countrycode" "kr", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y" } /** example **/ post /partner/v1/card/template/cardid=3hdpejr6qi380 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "ctemplate" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload cardid wallet card id [example] 200 ok { "cardid" "3hdpejr6qi380", "resultcode" "0", "resultmessage" "success" } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable get wallet card templates wallet card templates created through the api can be retrieved via the template list api and are also visible and manageable through the wallet partners portal partners can view and manage all wallet card templates they have created [request] type value description method get url /partner/v1/card/templates headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer * see json web token x-smcs-partner-idstring 32 required partner id x-request-idstring 32 required request identifier random generated uuid string [example] /** example **/ get /partner/v1/card/templates [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr [response] type value description http status 200 ok [example] 200 ok { "resultcode" "0", "resultmessage" "success", "templates" [ { "cardid" "3hdpejr6qi380", "title" "wallet card title 01", "countrycode" "us", "cardtype" "loyalty", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" null, "privacymodeyn" "n", "sharebuttonexposureyn" "y", "state" "verifying", "applogoimg" “”, "desc" “” }, { "cardid" "3ctei2riqi9iq", "title" "wallet card title 02", "countrycode" "us", "cardtype" "generic", "subtype" "others", "nonetworksupportyn" "n", "testingmodeoff" "y", "provisioningtype" "na", "usemoreserviceyn" "n", "preventcaptureyn" "n", "prtnrapppckgname" “”, "privacymodeyn" "n", "state" "verifying", "category" "membership", "applogoimg" “”, "desc" "ntf_us_generic" } ] } [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable adding wallet cards a typical addition to the wallet card is triggered by user interaction, such as pressing the add to wallet button or link the api also supports adding a wallet card automatically to the user for a special purpose with user’s consent this api allows partners to provide wallet cards to users the request payload must contain information about the target to which the card is added this information may be related to the user’s account, or it may contain information about a card that is already registered a push notification is sent to the user’s device to confirm successful card registration the success of card registration must be determined that the card is registered normally when it is updated to added of send card state an administrator must grant permission for partners to use this api card data specification card id {card id} is an id issued when the partner manager signs up for partner services and register the wallet card they want to service refer to partner onboarding guide document for details cdata actual payload data in basic json format to establish the communication between partners and samsung wallet see the details in the table below card data token the specific wallet card data mentioned as cdata must be secured in jwt json web token format see a chapter security for details [request] type value description method post url /atw/v1/cards/{card id} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type i e , bearer <credentials>* see json web token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier random generated uuid string path parameters card id string 32 required wallet card identifier granted through the partner portal body parameters cdata object required actual payload data in basic json format to establish the communication between partners and samsung wallet this must be in the secure jwt json web token format * see the chapter security for more details payload object card object required wallet card object card type string 16 required wallet card type *see wallet cards card subtype string 16 required wallet card sub type *see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds *utc±00 00 data[] updatedat long 13 required data update timestamp epoch timestamp in milliseconds *utc±00 00 data[] language string 8 required default card language code e g en, ko data[] attributes object required attributes container data[] attributes {fields} required attributes fields by card type*see wallet cards data[] localization[] array of object optional localized language container *see wallet cards localization[] language string 8 required multilingual content language code, e g en, ko localization[] attributes {fields} for displaying a given language, ‘data[] attributes’ can be replaced by localized versions *see wallet cards account object conditional user account object account type string 16 required type of user identifier, e g phonenumber, email account value string 64 required user identifier [example] /** example card object **/ { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] }, "account" { "type" "phonenumber", "value" "+821012345678” } } /** example **/ post /atw/v1/cards/1656147182764415319 [headers] authorization eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 x-request-cc2 kr /** payload **/ { "cdata" "eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0z…" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 200 ok 400 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 401 unauthorized authorization token is invalid or expired 500 500 internal server error 503 503 service unavailable

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

Develop Samsung Wallet

doc

Manage Wallet Card

manage wallet card refer to the partner onboarding guide for the samsung wallet portal the rp partner needs registration information on the wallet portal wallet portal currently offers 'verify with samsung wallet' functionality to the rp partners overall managing process the following image illustrates the process of managing samsung wallet cards create relaying party wallet card template partners can create and manage their wallet cards with this step-by-step guide manage wallet cards partners can manage all registered wallet cards partners can edit wallet cards and check their status 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 samsung wallet item description testing mode all data generated during 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 automatically generated partner app package name partner app package name wallet card template pre-defined partner’s wallet card template type > sub type > design type wallet card custom setting type authentication issuer set the authentication issuer for the relying party service to be provided as this wallet card please select authentication issuers from the identity provider groups only authentication issuers with the same “service location” as the relying party service are displayed ※ the identity provider of the “authentication issuer”is supported depending on the service location" set partner rp get request data url through which a partner receives a card data inquiry api call in case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/key ※ the attribute could be activated with the approval of a manager partner rp send authentication data url through which a partner receives a card data inquiry api callin case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/auth ※ the attribute could be activated with the approval of a manager samsung server ips samsung wallet server ips which need to be allowed at the partner’s firewall separately described for inbound and outbound calls service location select a regional limit for the wallet card if there was no selected location, the wallet card is shown in all locations if the specified location was selected, the wallet card is shown only in the selected location users can 'verify with samsung wallet' only in service locations where the wallet service is provided ※ the identity provider of the “authentication issuer” is supported depending on the "service location" set main headquarters location check to set it as a 'main location' as the company's main service country head office for creating and proceeding with wallet cards, notification e-mails such as wallet card approval requests are sent only to the selected main location wallet card data save in server set whether to store wallet card data in the server to protect personal information if the card has sensitive information, you can contact the developer support team not to save it description description of the wallet card select template partners can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id ※ for rp partners select "relying party type > other sub type" to set the relying party wallet card partners can select the type of wallet card needed to register from the 'select wallet card template' pop-up first, select the wallet card type and then select the wallet card sub type to select one of the templates belonging to it wallet card custom setting you must set the attributes of the "wallet card custom setting" according to the wallet card type you selected ※ for rp partners the "authentication issuer" attribute is a unique property of the relying party card the identity provider of the authentication issuer is supported depending on the "service location" set e g if service location is in the us, the authentication issuer field only supports an identity provider belonging to the us when the parent hierarchy value is checked, its children values created later are automatically checked in the united states, the authentication issuer is the state government, and the driver's license can be understood as an mdl mobile driver's license view wallet card partners can view all the registered information, edit and delete the wallet card launch wallet cards verifying status partners can launch and activate cards you can activate a card by clicking the launch button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, partners can modify and re-launch the administrator registers the reason for rejection when rejecting a launched wallet card partners will receive an email from the system, including the reason for rejection partners can apply for launching again by checking the reason for rejection and modifying the wallet card information testing mode partners can test a card internally to make sure everything works before officially release to the users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to ‘active’ after administrator approval when the card is activated, it becomes visible to the user verify with samsung wallet integration to integrate the wallet, you need to run the ‘verify with samsung wallet’ script into your system the verify with samsung wallet script is available for both web and android platforms each system has a different composition to implement the verify with samsung wallet button, follow the steps below in order create tokenized card data cdata card data is the actual content data of wallet card and it has several formats based on card type please refer to generate_cdata sample code for detail copy the sample verify with samsung wallet script from partner portal’s wallet card page and replace cdata with the data token created above apply the script to your system please see web_integration sample code and app_integration sample code for detail below is ‘verify with samsung wallet’ script guide in partner portal to integrate the ‘verify with samsung wallet’ you may need some base data you can find this base data and other necessary information on the partner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis

https://developer.samsung.com/wallet/verifywithsamsungwallet/managewalletcard.html

Develop Samsung Wallet

doc

Generic Card

generic card 'generic card' is defined for registering various forms of cards that aren't defined as other types partners can customize the items on the generic card to display by connecting them with card data wallet card type type sub-type generic others others wallet card data fields attributes type value description payload object cardtemplateobject required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtypestring 100 conditional this value is set to “generic” * required when creating a template cardtemplate subtype string 100 conditional this value is set to “others” * required when creating a template cardtemplate designtype string 100 optional select from these values “generic 01”, “generic 02”, “generic 03”* default “generic 01” cardtemplate prtnrapppckgname string 128 optional app package name cardtemplate applogoimg string 200 optional banner logo image url cardtemplate nonetworksupportyn string 1 optional either 'y' or 'n'* default 'n' cardtemplate privacymodeyn string 1 optional either 'y' or 'n'* default 'n' cardtemplate preventcaptureyn string 1 optional screen capture prevention flag cardtemplate category string 20 optional select from the following values “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others” cardtemplate state string 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoff string 1 optional testmode offeither 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551319", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "generic", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "designtype" "generic 02", "nonetworksupportyn" "n", "category" "membership", "privacymodeyn" "n", "preventcaptureyn" "n" } }

https://developer.samsung.com/wallet/businesssupportforspecialpurposes/walletcards/genericcard.html

Didn’t find what you were looking for?

FAQ

Search frequently asked
questions
by keywords.

Join the Forum

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

Get Support

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

Preferences Submitted

You have successfully updated your cookie preferences.