Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials
blogwallet cards. notice this article introduces non-payment service cards. if you want to learn more about the payment service of samsung wallet, visit the samsung pay page. you can get information on online payment services such as in-app payments, web checkout, and w3c payments. add to samsung wallet service let's delve deeper into the "add to samsung wallet" feature. digitized content registered in samsung wallet comes in the form of cards called wallet cards. registering a wallet card is effortless: simply click the "add to samsung wallet" button, and the card is stored securely on users’ galaxy smartphones. "add to samsung wallet" button and wallet card notice the benefits of using wallet cards can be found in the commercial video forgetting can be awesome. wallet cards the "add to samsung wallet" service is an open platform that supports offering various types of content such as wallet cards. we are streamlining service integration with content providers across different regions and adding useful features. boarding pass event ticket loyalty gift card coupon id card generic card pay as you go (in progress) reservation (in progress) digital key (in progress) notice generic card supports unstructured forms of cards. be a samsung wallet partner partner onboarding to begin offering content through samsung wallet, you must first register as a partner on the samsung wallet partner portal. the integration process is detailed on the samsung developer portal. to join the samsung wallet partner portal, create a samsung account that is used as the service administrator. wallet card management once enrolled, you can create service cards on the wallet cards menu. each card is assigned a card id representing the service, and you can set the card type and linking information. you can manage cards according to their status – test or live. configuring wallet card notice after completing all required forms for the wallet card, click the launch button to request card activation. before providing the service to actual users, remember to turn off the 'test mode.' how to safely secure user data key generation and certificate request the registration process includes certificate exchange to securely transmit service data. refer to the diagram and developer guide, security key & certificate creation guide, to complete the certificate registration and partner enrollment smoothly. certificates exchange process ensuring data security to prevent forgery and leakage of user card data, secure tokenization processing is required. json web token (jwt), which includes encryption and signature, has a validity time basis for verification, thus providing enhanced security. in particular, when generating this token, the key and certificate previously obtained through the certificate exchange process are used. process of generating and verifying security tokens notice depending on how partners provide content services to users, you can choose how to deliver data to the samsung wallet service. two ways to transfer wallet card data add to samsung wallet interface provides two methods for partners to deliver users digital content as wallet cards. data transmit link the general way to transfer wallet card data is to organize tokenized data in the link attached to the button, and the card data is transmitted to the samsung wallet service when the user clicks the button. as long as samsung wallet support is confirmed, you can generate a link containing the user's card data and configure the "add to samsung wallet" button to run the link when pressed, either on an application or web page. data transmit process data fetch link another method to transfer wallet card data is to include only the refid, which represents the user's content, in the "add to samsung wallet" link and transmit it to the samsung wallet service. when a user clicks the "add to samsung wallet" button, samsung servers refer to the get card data api information set on the wallet card and retrieve user content using the received refid to complete registration. data fetch process this method is suitable for providing user's data through email or mms messages where static links cannot be avoided. there is an option to secure these static links. data fetch process for static links setting up data synchronization on the partner portal, you can set up the wallet card information and configure the server interaction api that the content provider needs to prepare. this api is an interface for managing card registrations, deletions, information, and state changes to sync with those registered on samsung wallet. register wallet cards when a user card is added to samsung wallet, samsung wallet servers use the send card state api to communicate card registration and deletion status to the content provider, allowing them to manage content that needs to be synchronized with samsung wallet. when a wallet card is registered, added event is sent to the partner's server update wallet cards changes to the synchronization target content can be notified to the samsung wallet service through the update notification api. here, the value that distinguishes each piece of content is the refid that the partner must provide when registering the users’ wallet card. through the get card data api, samsung wallet servers can check the latest content information any time. if updates occur on the partner's side, updated event notifications should be sent to the samsung server in case users withdraw content from the partner's side in case users delete cards from samsung wallet notice both servers should verify requests using the authorization header of the api request. this authorization token is in jwt format, familiar from card data security. effortless wallet card registration with just one click this feature is primarily composed of a link-connected button and can be provided through the content provider's application, web page, email, or mms message. various service channels javascript library for web developers we provide a javascript library and a user guide, implement the button, to help integrate your web pages. creating buttons and links in your app for configuring buttons in applications, utilize the button image resources. providing services via mms, email, or qr codes to provide services through fixed links, check out the details of the data fetch link. these static links can also be used by scanning qr codes. experience the service and practice you can experience service integration development using the codelab and use the testing tool to preregister the wallet cards created on the partner portal, which could be helpful. conclusion we've looked at how to provide digital content through the "add to samsung wallet" feature. we continuously update the guides on the developer portal, so please refer to them when preparing for integration. summary the "add to samsung wallet" service welcomes participation from content service partners and developers. for inquiries or technical support, please contact us through the form provided on the developer portal. i hope this post has been helpful, and now i'll conclude my writing here. thank you. this post was written based on the sdc23 korea session.
Choi, Jonghwa
Develop Samsung Wallet
docwallet card for add to wallet please take a look at the partner onboarding guide for the samsung wallet portal the partner needs registration information on the wallet portal wallet portal currently offers 'add to samsung wallet' functionality to the partners overall managing process the following image illustrates the process of managing wallet cards create wallet cards draft status 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 wallet item description 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 partners can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id you can select the type of wallet card from the select wallet card template pop-up window first, select the one you want in the wallet card type drop-down menu and then click wallet card sub type to select one of the templates belonging to the card type wallet card type boarding pass wallet card type tickets wallet card type coupons wallet card type digital id wallet card type gift card wallet card type loyalty membership 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, you can 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 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 is made visible to the user add to samsung wallet integration for wallet integration, you need to insert an "add to wallet" script to your system the "add to wallet" script is available for web, android, and email/mms each system has different script composition to implement an "add to wallet" button, follow the procedure below create the tokenized card data cdata card data is the actual content data of wallet card and it has several formats based on the card type refer to cdata generation sample code for details copy the sample "add to wallet" script from the partners portal’s wallet card page and replace "cdata" with the data token created above apply the script to your system see partners portal’s wallet card and android integration sample code for details below is the "add to wallet" script guide in the partners portal 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
Develop Samsung Wallet
docwallet card for verify with wallet please take a look at 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 wallet cards draft status 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 callin 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 ttype 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 format 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 are ‘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
tutorials
blogwallet card updates in a user’s samsung galaxy devices. this time, we look at the partner server api called “get card data” and how partners can use this api in order to add, update, or cancel issued wallet cards in user’s devices. prerequisites the prerequisites needed for this article are similar to those for our previous article about samsung wallet server apis. namely, we require a partner server where we can set up the get card data api endpoint. in order to set up and test this api, you need to: complete the samsung wallet onboarding process. create a samsung wallet card template. launch the wallet card template and have it in either the verifying or active status so that the card can be added to a user’s device. have an existing server to set up the get card data api endpoint. you can use codesandbox or a similar online hosting service for testing. configure your firewall (if you use any) to accept incoming connections from the samsung wallet server (34.200.172.231 and 13.209.93.60). when you have completed all the prerequisites, proceed to the next step to configure your wallet card template to send requests to your server. setting up the get card data api in the samsung wallet partners portal, open the desired wallet card template and then edit it to set the following “get” field: go to the wallet partners portal. from the wallet cards dropdown, select “manage wallet card.” click the name of the wallet card you want to edit. click “edit” and then scroll down to the “partner get card data” section to modify the partner server url. click “save” to set the server url for the card. get card data api specification for a complete description of the get card data api specification, please check the samsung wallet documentation. method: the get card data api uses a get method to fetch card information from the server. api path: the api path for the request is fixed and uses the “partner get card data” server url that you configured in the previous section. the samsung wallet server sends the get request to this exact url whenever it needs to fetch card data from the partner server. the format for the api path url for the complete get card data request is: {partner server url}/cards/{cardid}/{refid} if the samsung wallet server needs to fetch specific fields from the card data instead of the entire card, then it uses the additional query parameter named “fields” at the end of the url: {partner server url}/cards/{cardid}/{refid}?fields={fields} request header: the samsung wallet server includes 2 fields in the header when calling the get card data endpoint: authorization and x-request-id. an authorization bearer token is provided in the authorization field, so that the partner can verify the request before providing the data. request payload: the request does not contain any payload. expected response payload: the response to the get card data request must contain the card data in one of the following two formats: plain card data in the raw json format. encrypted card data in the cdata format. when the fields query parameter is used in the request url, the card data returned in the response can provide only the fields included in the request. however, it is acceptable to return the entire card data in the response as well. implementing the get card data api we will extend the spring server from the previous article to create the get card data api endpoint. in the api, we need to do 2 things: verify the incoming request to check that it is authentic and actually coming from the samsung wallet server. send the requested card’s data back as the response. the verification part is similar to the verification steps performed in the previous article. the request header contains the authorization bearer token, which we can use to verify the request. after verification, it is necessary to send back valid card data in the response to this get request. we can return either the plain card data or encrypt and tokenize it into cdata. in this implementation, we return the plain card data in the json format. in this example, we use a raw json file from a plaintext file called ticket_ref-001.json for simplicity. the complete get card data api implementation will therefore be as follows: @restcontroller @requestmapping("/cards") class carddatacontroller { // data transmit link @getmapping(path = ["/{cardid}/{refid}"]) fun providecarddata(@pathvariable cardid: string, @pathvariable refid: string, @requestparam("fields", defaultvalue = "") fields: string, @requestheader("authorization") authtoken: string, @requestheader("x-request-id") requestid: string,): string { if(verifyauthtoken(authtoken)){ return jwtgen.getplaincarddata() } else{ return httpstatus.unauthorized.tostring() } } } next, define the getplaincarddata() function, where the cdata is generated using the data provided in the ticket_ref-001.json file. fun getplaincarddata():string{ val data:string = getstringfromfile("sample/payload/ticket_ref-001.json") return data } warningalways verify the authenticity of the get card data request before returning the data in response. the authenticity of the request can be verified using the authorization token provided in the request header. adding cards to samsung wallet using data fetch link once you have configured the get card data api for your server, you can use the api to add cards to the user’s device directly. this is called the data fetch link and unlike the standard approach, it is not necessary to send the card information in the cdata format. instead, you can simply provide the user with the url and they can then add the card to their device by clicking the url. the url format for adding card data is as follows: https://a.swallet.link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} so, for example, if your certificateid is a123, cardid is 3h844abcdefg00, and refid is ref-001, then the slim api url for the add to wallet operation is: https://a.swallet.link/atw/v3/a123/3h844abcdefg00#clip?pdata=ref-001 to add the card to their wallet using this method, the user needs to simply visit this url from their device. once the user clicks the link, the samsung wallet server requests the card data from the previously configured get card data api and adds the wallet card to the device. notethe only information required to add a card to the device is the pdata (also known as refid). ensure that this value is a unique hash identifier so that it cannot be easily compromised by third parties figure 1: adding a card to the wallet using data fetch link updating card data using an update notification samsung wallet allows partners to update any issued card’s data using the previously configured get card data api. the card data can be updated in one of the following two ways: the card data is refreshed automatically every time the user opens the card in the detail view. the card data update is triggered manually when the partner sends an update notification. in this case, the card data is updated even when samsung wallet is running in the background, and it is not necessary to open the card in the detail view. when an update notification is sent, the state of the card is immediately updated on the device. afterwards, when the user opens samsung wallet in their device, the card data attributes are refreshed by calling the get card data api. this ensures that the wallet card data is always updated right before the user views it. in order to update card data manually and notify the user about the change, we need to configure the changes in the card data and then send an update notification to the samsung wallet server. once the update notification api is called following the specification, the card’s status and data are updated on the user’s device automatically. samsung wallet uses the refid as the unique identifier of samsung wallet cards. therefore, the refid of the specific card must be included in the payload of the update notification request in order to update the card. the complete specification for the update notification api can be found in the documentation: method: post api path: the request needs to be sent at:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/updates for the samsung wallet server domain url, we can either use the public domain (https://tsapi-card.walletsvc.samsung.com) or the private domain we received in our api callback. request header: the header must contain the authorization, x-smcs-partner-id, and x-request-id request header fields. the samsung wallet server uses this header information to verify the authenticity of the request. additionally, the header also needs to specify the content-type header, which must be set to application/json. request payload: the payload of the update notification must contain the card type, refid, and the new state of the card. optionally, the payload can also contain the fields to be updated so that only those specific fields are retrieved and updated. the payload must be in the following json format: { "card": { "type": "{card type}", "data": [ { "refid": "{ref id}", "state": "{update/deleted/expired}", "fields": "{fields, comma-separated, optional}" } ] } } steps for using the update notification: configure the authorization token. prepare the card data in your server for updating. prepare the header and payload with the refid of the selected card for updating. send the post request to the samsung wallet server for updating. once you send the update notification post request following the specification, the samsung wallet server updates the card on the user’s device. let us modify the data of the previously added card from our server and then call the update notification api. configuring the authorization token all samsung wallet server apis require the use of a bearer authorization token in order to ensure the security and authenticity of the request. you can find the complete specification of the authorization token required by samsung wallet in the documentation the authorization token generation process is very similar to generating cdata, except that for cdata, the payload needs to be encrypted first. for the authorization token, the payload is in plaintext and only contains the api path for verification. to create the bearer authorization token: configure the json payload that describes the method and api path of the request. configure a custom jws header following the jwt format specification. create a jws object using the payload and custom jws header. sign and validate the complete jws object with your partner private and public keys using the rs256 asymmetric algorithm. the complete function to generate the authorization token is given below: fun generateauthorizationtoken(): string{ val payload:string = getstringfromfile("sample/payload/api_path.json") .replace("{refid}", refid) .replace("{method}","get") .replace("{path}","/wltex/cards/cardid/updates/") val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("auth") .customparam("partnerid", partner_id) .customparam("certificateid", "a123") .customparam("ver", "3") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } preparing card data for update once the update notification is sent, the samsung wallet server queries the get card data api endpoint for the updated card data and then updates the wallet card with the latest data provided by the api. so before calling the update notification, make sure the card data provided by the api is up-to-date. for our example, let us change the value of the seatnumber field from a-07 to e-05 before calling the update notification api. prepare the request header and payload for the update notification the post request header contains the following fields: authorization, x-smcs-partner-id, and x-request-id. for our example, we set our partner id as the x-smcs-partner-id, a randomly generated code as x-request-id, and generate a bearer token following the authorization token generation process mentioned previously and use it as the authorization field value. next, we set the json payload, according to the previously mentioned format: { "card": { "type": "ticket", "data": [ { "refid": "ref-001", "state": "updated" } ] } } since the fields field is optional, we have omitted it in this example. sending the update notification to the samsung wallet server once everything is ready, we send the update notification post request to the samsung wallet server. we can use any method to send the request, such as postman, curl, or a plain http request. make sure that the update notification is sent immediately after generating the authorization token, as the token only has a ttl (time to live) of 30 seconds. once the update notification is sent, the user should immediately receive a “card information updated” push notification informing them of the card update. afterwards, the next time the user opens the samsung wallet application, the card details are up-to-date and the user can see their new seat number in their card. figure 2: updating card data using an update notification cancelling an event using a cancel notification there are times when you might need to cancel an event and recall all the issued wallet cards for it. in such case, samsung wallet makes it possible to cancel all issued cards with a specific eventid and send a notification regarding the cancelation to all users with the cards associated with the event. therefore, it is no longer necessary to modify issued cards one-by-one using their refid. instead the card issuer can cancel all cards under the event at one time. the process of sending a cancel notification is the same as the update notification process, except for the following differences: the payload needs to contain the eventid instead of the refid the state must always be canceled the post request endpoint url is:{samsung wallet server domain url}/{cc2}/wltex/cards/{cardid}/cancels you can find the complete specification for the cancel notification api in the samsung wallet documentation. now let us send a cancel notification following the same process as update notification: configure the authorization token. prepare the payload with the eventid for cancellation. send the post request to the samsung wallet server for cancellation. for our example, we add a few cards with the same event id to our wallet in different devices, then send a cancel notification following the specification. once the cancel notification is sent, all samsung wallet cards with the given eventid are deleted automatically from all devices and the affected users receive a "ticket canceled" push notification. figure 3: canceling an event using a cancel notification conclusion in this article, we have learned how to configure our server to use the get card data api, as well as how to use various samsung wallet server apis to add, update, delete, and cancel samsung wallet cards from user devices. if you have any further queries regarding this process, feel free to reach out to us through the samsung developers forum.
Mobassir Ahsan
Develop Samsung Wallet
docwallet card total number of wallet cards registered in the portal wallet card type total number of wallet card types registered in the portal wallet card template total number of templates registered in the portal recent trends provides key indicators and trend charts for the selected period you can change the period and wallet card type being reviewed item description registered registration by wallet card category impressions count when the coupon or banner is displayed on each screen page click count of click on a specific link to the number of total users who view a coupon or banner click through rate percentage of clicks against impressions in the coupon or banner[ctr % = clicks/impressions] stats of wallet cards provides detailed statistical information for the selected wallet card you can change the period, template, and wallet card type you can check detailed information and charts for each indicator item description registered registration by wallet card category number of registrations by wallet card category and registrations by template number of registrations by template , registered number of registrations for the specified wallet card category/template , registration by partner number of registrations by partner active device number of device registering cards in the wallet max number of unique device ids dmid the max number means the maximum value during the statistical period - the hourly graph shows the maximum time's value - the daily graph shows the maximum date's value top 10 of all templates statistics on top 10 templates based on number of registrations or clicks & ctr add to wallet - impressions number of impressions counts for 'add to wallet' button add to wallet - clicks number of clicks for 'add to wallet' button add to wallet – click through rate ratio of clicks against impressions for 'add to wallet' button[ctr % = clicks/impressions] wallet cards - impressions number of exposures of registered content wallet cards – clicks number of clicks on registered content wallet cards – click through rate click through rate of registered content age & gender age & gender statistics for impression/click/ctr data by wallet card / wallet category registered by end user push notification – impressions number of exposures of push notification content push notification – clicks number of clicks of push notification content
Learn Code Lab
codelabwallet cards with the samsung wallet partners site, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more by visiting samsung wallet partner onboarding process, here in samsung developers overview samsung wallet is an application that securely stores essential items such as boarding passes, tickets, and coupons, making them easily accessible from anywhere with this app, users can access various partner wallet cards in one place, simply by swiping up from the bottom of the screen the add to samsung wallet service provides interfaces for users to conveniently add digital content to samsung wallet here are examples of the supported wallet cards boarding pass journey information such as flights, trains, and buses can be provided as notifications, allowing easy retrieval when checking in by configuring server synchronization, updates to journey information such as gate changes, schedule changes, or cancellations can be received by the users ticket notifications about events and additional information, including benefits, can be provided based on real-time utilization of performances, sports games, movies, and admission tickets, status updates related to expiration and availability can be provided gift card gift card, also referred to as a prepaid card, provides real-time balance and transaction history loyalty loyalty cards function as membership credentials, managing membership information through these cards, loyalty points can be administered and redeemed id id cards can fulfill identification verification purposes, such as identity cards, employee cards, and licenses physical documents can be represented through wallet cards, and near field communication nfc -based authentication can be provided reservation reservation cards can contain diverse online booking details, including rental cars, restaurants, and accommodations ongoing reservation information can be managed as a journey pay as you go pay as you go cards allow users to register services that can be charged and utilized according to their preference for convenient use generic card generic cards enable users to create customized cards by selecting preferred card template layouts and designing elements notedepending on your country or region, some card types are not supported if you need assistance, please contact us at developer samsung com/dashboard/support the image below shows the process of managing wallet cards for more information, refer to manage wallet cards set up your environment you will need the following latest version of samsung wallet app from galaxy store samsung galaxy device that supports samsung wallet access to samsung wallet partners site internet browser, such as chrome openssl intellij idea or any java ide optional start the onboarding process partners can manage wallet cards and monitor performance with the samsung wallet partners site to join as partner generate a private key and certificate signing request csr using the openssl command you can follow the instructions in security factors notea private key enables encryption and is the most important component of certificates while csr, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country proceed to register in the samsung wallet partners site using your samsung account follow the samsung wallet partner onboarding process upload the generated csr for data encryption in encryption setting management section after registration, you will receive a welcome email noteupon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes signed certificate used along with the private key to sign data samsung certificate used to encrypt card data and validate authentication tokens in server api headers create a wallet card follow the steps below to create a wallet card in samsung wallet partners site click the wallet cards menu and choose create wallet card fill out the general information form with the details of the wallet card in wallet card template, choose a card type and sub type select the design type and click done you can choose from various types of wallet card templates optimized for partners after inputting all necessary details, click save to set the wallet card status to draft launch the wallet card you can launch and request activation of the card by clicking the launch button upon agreeing to proceed, the launch button text changes to launched and the card status becomes verifying add the card to samsung wallet using the test tool open a web browser on your computer or galaxy mobile device, and go to the following link partner walletsvc samsung com/addtowallettest go to add to wallet tab and click choose key file to upload your private key in the select card dropdown menu, select the created card to display the card details and populate sample data navigate to the form tab and modify the card data as desired notethe structure for configuring wallet cards follows the defined specification you can refer to the full list of card-specific attributes specification scroll down to the bottom of the page and click the add to samsung wallet button click done when a preview of the card shows on your mobile screen with a message indicating that the card has been added to your wallet once the card is added to your samsung wallet app, you can check its details by clicking on it noteyou can also go to the playground tab and add cards to the samsung wallet app even without creating a card on the wallet partners site update the status of the added card if a server api info partner get card data and partner send card state is registered in the wallet card, real-time updates of the user's registered cards can be provided notefor more information, see server interaction modify and update the card's status by utilizing the push notification feature of the test tool navigate to the push notification tab ensure that the correct private key is uploaded and the same card as in the add to wallet tab is selected copy the ref id value from the add to wallet tab and paste it into ref id field in the push notification tab in the status field, enter one of the following card states expired, redeemed, held, suspended, or deleted the current state is set to active then, click the request push notification button check the card in the samsung wallet app to confirm the change tokenize card data and implement the add to samsung wallet button to your service optional notethis step is optional, but if you want to learn how to integrate the add to samsung wallet button into your services like an android app, web app, or email, you can follow these steps the samsung wallet partners site provides generated add to samsung wallet scripts for each wallet card you create you can simply copy and paste these scripts into your partner apps web and android or include them in emails/mms messages to implement the add to wallet button, follow these steps go to the [add to wallet script guide] section of the card you created click show to view the available scripts and then copy the appropriate script for your service develop a program that can generate tokenized card data cdata the cdata represents the actual content of the wallet card and comes in different formats depending on the card type you can check the cdata generation sample code for reference the cdata is derived from the card data, which is in json format for testing purposes, you can utilize the generated json from the test tool follow the implementing atw button guide to determine where to incorporate the generated cdata and gain further insights into this process you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can utilize the add to samsung wallet service by yourself! to learn more about samsung wallet, visit developer samsung com/wallet
tutorials mobile
blogwallet card which you must create and launch within the samsung wallet portal. after successfully launching the card, you can create an “add to wallet” link for it. prerequisites before you can create wallet cards for samsung wallet, complete the samsung wallet partner registration and onboarding process, including encryption setup. after onboarding, you receive an email with your public key and signed security certificate. keep this information in a safe place. important your company can only obtain partnership for a single samsung account. store your private key securely, as it is needed for wallet card management. your encryption settings cannot be modified without administrator approval. creating wallet cards samsung wallet supports the following wallet card types: boarding pass event ticket coupon gift card loyalty card id card create your wallet card at the samsung wallet portal. you can create as many cards as you need. the samsung wallet portal also allows you to manage your cards and monitor their performance. testing wallet cards use the “add to wallet” test tool to test the card at any time, before or after launching it: in the samsung wallet portal, enable testing mode for the card you want to test. skip this step if you have already launched the card. on your samsung device, go to the “add to wallet” test tool and sign in with your samsung account. select the card from the list and provide test data in the appropriate fields. in the “partner’s private key” field, paste your decrypted private key. this must be the same private key that was used during onboarding. noteif your private key is encrypted, you must first decode it with the ssl command. an encrypted key starts with the following text: -----begin encrypted private key----- once decoded, the key starts with the following text: -----begin private key----- 5. tap the “add to samsung wallet” button to add the card to samsung wallet on your device. for more information about testing wallet cards, see “add to wallet” test tool. launching wallet cards when you are ready to make the wallet card accessible to users, click “launch” to start the verification process. launching a card cannot be canceled. figure 1: wallet card launched the samsung wallet administrator reviews the card and approves or rejects it. if your card is rejected, check the rejection email for the reason. modify the card to address the issue and launch it again. for more information about wallet card verification, see launch wallet cards (verifying status) and launch wallet cards (rejected status). implementing “add to wallet” links after launching your wallet card, create a link that users can click to add the content to their samsung wallet. to include the card data in tokenized form, use the following url format: https://a.swallet.link/atw/v1/{card id}#clip?cdata={cdata token} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. cdata query parameter contains the encrypted card data in jwt format. for more information, see the "cdata token generation" section below. if the encrypted card data is longer than 2048 bytes, or you do not want to include the tokenized data in the url, store and reference the card data on your server. create the url in the following format: https://a.swallet.link/atw/v1/{card id}#clip?pdata={reference id} where: {card id} path parameter is the unique identifier for the wallet card in the samsung wallet portal. #clip hash parameter is case-sensitive. pdata query parameter is the unique identifier for the card data stored on your server. for more information on “add to wallet” links, see add to wallet interface. cdata token generation the card data in basic json format must be provided as a jwt (json web token). for token generation details, see security. you can also study the cdata generation sample code. to ensure your cdata token is valid, keep the following requirements in mind: pay attention to the mandatory fields in the card object. all timestamps are utc epoch time in milliseconds. card data attributes vary based on the card type. for detailed card data specifications, see wallet cards. your private key must match the key used for the security certificate signed by samsung. if you are using the correct private key, the following commands generate the same hash: $ openssl rsa -noout -modulus -in partner.key | openssl md5 $ openssl x509 -noout -modulus -in partner.crt | openssl md5 generated jwt tokens expire in 30 seconds. the “add to wallet” link must be used within this time. otherwise, you must generate a new token and new link. next steps to integrate the “add to wallet” feature as a button in your application or website, see implement the button. you can update the information on a card that has been stored in a user’s samsung wallet by communicating between your server and the samsung server. for information, see server interaction. if you have any questions or face difficulties implementing the content in this article, you can contact samsung developer support. related resources samsung wallet documentation integrate “add to samsung wallet” button into partner services code lab
M. A. Hasan Molla
Develop Samsung Wallet
docwallet card for interactions after storing contents on samsung wallet, server interfaces are needed which is defined on the chapter server interaction update wallet cards if the wallet card contents should be updated by partners, they must call samsung server api path parameter 'cc2' must be set to the value brought from callback named 'send card state' api which includes 'added' event see a chapter samsung server api for more details update notification is for single content cancel notification is for calling off every user's wallet card contents related to a specific event get card data payload has the same format of card information as the one of 'add to wallet' send card state can also have an event 'deleted' to notify a wallet card deletion on samsung wallet by users card states wallet cards have several states for each content provider’s notifications and user actions the state diagram below describes wallet card states from beginning to end state diagram
Develop Samsung Wallet
docwallet card specs data transmit link the most common and straightforward method is the data transmit link approach, which securely includes tokenized data in the atw link the atw link format for this method is as follows the name data transmit link has been changed from typical flow type value description url https //a swallet link/atw/v3/{cardid}#clip?cdata={cdata} path parameters cardid string required wallet card identifier issued from partner portal when the partner managersigns up for partner services and registers the wallet card they want to service hash path parameters #clip string required parameters for the hash link* the first letter is capitalized query parameters cdata string required actual payload data in basic json format to communicate between partnersand samsung wallet this must be secured in jwt json web token format * see security [example] https //a swallet link/atw/v3/1656147182764415319#clip?cdata=eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0zwqgdgltzsisinbhcnruzxjjrci6inbhcnruzxigsuqifq … … … … dn0_oz3xcr0juq3mlszliutxfotewnz0mqj7kinjysnm5xfwqt5vcn20peebelgux8vjxly4_9g4bhq-hd4o9poyutuawew yzdlmtfho -nycel3t0yznzad2kck_hrtwigeerhlgn6ydaq_fpfdslxsa3zjtnpg3wcuqew5cidpbpfswbqlropqepnawg5nlm3dkaa4a1dzazmbsr1bgzhrh_viknx3cy5mo0jnbexl_yiz5_wb379uyswumqipitzvg2ijyvfht17i4 data fetch link in cases involving sensitive data or when providing static links, data fetch link method is highly recommended links using this approach include only a unique reference id, and wallet cards are added by querying data through get card data path as specified in partner portal the name data fetch link has been changed from slim data flow please be aware that if the link is exposed to unintended users, it can be exploited please prepare the integration with this in mind it is crucial to ensure that the refid, used for a reference value, is generated in a manner that is not easily deducible by potential attackers type value escription url https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateid string 4 conditional certificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardid string 32 required wallet card identifier * it must be generated from partners portal hash path parameters #clip string 5 required parameters for the hash link query parameter pdata string 2048 required unique id defined by content providers this has identification for each user's wallet card contents * for secure transactions, a reference id refid must be in a form that cannot be inferred [example] example web link https //a swallet link/atw/v3/ymtt/1656147182764415319#clip?pdata=sighcziwm9g updating wallet card specs the added users’ cards allow updating its data using server interactions find the card details to configure api on partner portal if partners want to manage the added cards samsung server will notify the result of 'add to wallet' via send card state partners get the callback url for samsung server api from send card state payload using the callback url, partners can make actions for the added cards via samsung server api depending on the interfaces, samsung server triggers specific operations for example, when update notification is called, samsung server calls partners' server to look up the updated contents partner server api samsung server can call the following api by using endpoint on the registered card information if the partner server manages an inbound allow list, contact us to register samsung server ip address get card data returns the current information of the card [request] type value description method get url {partner server url}/cards/{cardid}/{refid}?fields={fields} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * see the "add to wallet" interfaces refid string 32 required a unique content identifier defined by the content provider query parameter fields string 128 optional attributes which intended to retrieve can be specified using commas , as separators e g balance,barcode value payload n/a example get /cards/12584806754/ref-20230304-0003 [response] type value description http status 200 ok 204 no content payload option1 cdata string 4096 conditional card object json * this field needs to be encrypted * see security payload option2 card object conditional card information * card object as an alternative to cdata * if the card includes sensitive data, it is highly recommended to use cdata card type string 16 required wallet card 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 timestamp of data epoch timestamp in milliseconds data[] updatedat long 13 required timestamp of data epoch timestamp in milliseconds data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, canceled, pending, suspended * see card states for details data[] language string 8 required default content language code e g , en, ko data[] attributes object required card data attributes data[] attributes {fields} attribute fields by card type *see wallet cards data[] localization[] array of object optional information for multilingual support 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 [example option1 ] { "cdata" "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 eyjzdwiioiixmjm0nty3odkwiiwibmftzsi6ikpvag4grg9liiwiawf0ijoxnte2mjm5mdiyfq sflkxwrjsmekkf2qt4fwpmejf36pok6yjv_adqssw5c" } [example option2 ] { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet" *see wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성월렛" } }] }] } } [example filtered using select parameter ] get /cards/12584806754/ref-20230304-0003?select=idphoto { "card" { "type" "ticket", "subtype" "entrances", "data" [{ "refid" "ref-20230304-0003", "createdat" 1612660039000, "language" "en", "attributes" { "idphoto" "{idphoto data}" } }] } } /** or **/ { "cdata" tokenize{data} } [result] http status code description 200 ok success 204 no content card doesn't exist 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 server encountered an unexpected condition that prevented it fromfulfilling the request 503 service unavailable server is not ready to handle the request send card state partners can manage the state or history of the card using this api if the card state is changed on the samsung device, samsung calls this api using a refid [request] type value description method post url {partner server url}/cards/{cardid}/{refid} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token /wallet/api_new/references/security html x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * see the ["add to wallet" interfaces]["add to wallet" interfaces_] refid string 32 required a unique content identifier defined by the content provider query parameters cc2 string 2 required country code cc2 for samsung server api event string 16 required events on wallet carde g , added, updated, deleted, provisioned* see card states for details payload callback string 1024 optional callback url for samsung server api [example] post /cards/12584806754/ref-20230304-001?cc2=us&event=added { "callback" "https //us-tsapi walletsvc samsung com" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request samsung server api partners can notify their contents changes with the following api service domain environment domain public domain https //tsapi-card walletsvc samsung com private domain ‘callback’ field from send card state api request payload the domains can be selectively used depending on your service requirement if the service needs to register static ips on your system, we recommend using private domain in this case, use the domain received in the request 'callback' field from send card state api if the service does not require ip registration, public domain can be a good choice in this case, country code cc2 is required as a path parameter to configure integration for each environment, register a new card service and get new card id to guarantee safe communication, servers should configure token-based authentication see authorization token for the details update notification if wallet card data content is updated, send a notification to the samsung server [request] type value description method post url {cc2}/wltex/cards/{cardid}/updates headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required unique content identifier defined by the content provider data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, suspended * see card states for details data[] fields string 128 optional wallet cards attributes which has been updated can be specified using commas , as separators it is used when 'data[] state' is updated e g balance,barcode value* supported wallet card types generic [example] post /wltex/cards/12584806754/notification /** header **/ authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /** payload **/ /** case 1 in general cases **/ { "card" { "type" "ticket", "data" [ { "refid" "ref-ticket-0001", "state" "updated" } ] } } /** case 2 in case of deletion **/ { "card" { "type" "boardingpass", "data" [ { "refid" "ref-boardingpass-0001", "state" "deleted" } ] } } /** case 3 when a specific field is updated **/ { "card" { "type" "idcard", "data" [ { "refid" "ref-idcard-0001", "state" "updated", "fields" "balance" } ] } } [response] type value description http status 200 ok 204 no content payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to somethingthat is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it fromfulfilling the request 503 service unavailable server is not ready to handle the request cancel notification if a cancelation happens for events such as performances, sports, movies, and journeys, partners can send a notification about it and set all of the related cards to expire this api does not support updates for specific attributes on the card [request] type value description method post url {cc2}/wltex/cards/{cardid}/cancels headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> *see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from the partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] eventid string 32 conditional required if card type has been set as ‘ticket’ data[] vehicle number string 32 conditional required if "card type" has been set as "boardingpass" data[] estimated oractualstartdate long 13 data[] state string 16 required wallet card state for example canceled* see card states for details [example] post /wltex/cards/12584806754/cancelation /** header **/ authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140004 /** payload **/ /** a movie ticket has been canceled **/ { "card" { "type" "ticket", "data" [ { "eventid" "event-722164a1a7", "state" "canceled" } ] } } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to somethingthat is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it fromfulfilling the request 503 service unavailable server is not ready to handle the request
Develop Samsung Wallet
docwallet 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 cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id unique value for each template created by a partner this value is set to a number of 19 digits or less cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 required the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate cardtype string 100 required template card type for details, refer to wallet cards cardtemplate subtype string 100 required template card sub type for details, refer to wallet cards cardtemplate designtype string 100 optional the value that defines the design type of the wallet card for details, refer to wallet cards cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of the image is 1024*1024 e g http //www yourdomain com/banner_logo_image png cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate nonetworksupportyn string 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' cardtemplate sharebuttonexposureyn string 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' cardtemplate privacymodeyn string 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' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 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 cardtemplate prtnrcarddata string 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 cardtemplate prtnrcardstate string 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 cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 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' cardtemplate desc string 500 optional description [example] /** example card template object **/ { "prtnrid" "4083254626439156160", "templaterefid" "123456781864545365", "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 tmplates 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 cardtemplate object required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate cardid string 32 required the cardid response received when creating a card cardtemplate templaterefid string 19 required partner template id the unique value for each template created by a partner this value is set to a number with 19 digits or less cardtemplate title string 32 optional wallet card name cardtemplate countrycode string 2 optional the main headquarters location code refer to iso-3166-1 alpha-2 for the country code cardtemplate prtnrapppckgname string 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url the maximum size of that image is 1024*1024 cardtemplate saveinserveryn string 1 optional sets whether to save the card data this value can only be set for the ‘id card’ type cardtemplate nonetworksupportyn string 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' cardtemplate sharebuttonexposureyn string 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' cardtemplate privacymodeyn string 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' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate category string 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 cardtemplate prtnrcarddata string 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 cardtemplate prtnrcardstate string 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 cardtemplate prtnrmempoint string 1000 optional [get membership point] partner url cardtemplate cardmetacp string 1000 optional [get card meta cp] partner url cardtemplate getfulfillmentlist string 1000 optional [get fulfillment list] partner url cardtemplate prtnrbalance string 1000 optional [get card balance] partner url cardtemplate state string 15 optional if the card status is “draft”, you can only select “verifying” cardtemplate testingmodeoff string 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’ cardtemplate desc string 500 optional description [example] /* *example card template object **/ { "prtnrid" "4083254626439156160", "cardid" "3hdpejr6qi380", "templaterefid" "123456781864545365", "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 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
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.