API Guidelines
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 [headers] 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 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 [headers] 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 implementing button for wallet integration, you need to insert ‘add to wallet’ script into your system we usually follow the procedures below to implement the ‘add to wallet’ button first, proceed with script composition with the sample script on the partners portal or see the integration sample code second, create tokenized card data cdata and insert the data token into the script above card data is the actual content data of wallet cards and has several formats based on card type please see generate_cdata sample code for detail importantcdata token should expire in 30 seconds after creation, so cdata token needs to be created right after users actually click “add to wallet” button to implement ‘add to wallet’ button, you may need some base data you can find the base data and other necessary information on partner portal’s wallet card page samsung wallet on the web this section explains how to implement an "add to wallet" button using javascript in a web view web button reference with importing api javascript if you implement the "add to wallet" button using this script, the button is shown only on the devices that support samsung wallet to automatically parse <samsung wallet> html tags when the page is loaded, include the following standard javascript <script src="https //us-cdn-gpp mcsvc samsung com/lib/wallet-card js" type="text/javascript"></script> you can use these tags or javascript functions for the web button if you're rendering html and you have proper partner permissions you can also use the script by referring to the various attributes samsung wallet html tag the ‘samsung wallet’ namespace tag defines the placement and various attributes of the "add to wallet" web button for samsung wallet <samsung wallet cardid="card_id" cdata="cdata" partnercode="partner_code" buttonid="button_id" rdclickurl="rd_click_url" rdimpressionurl="rd_impression_url" ></samsung wallet> button attributes attribute type required description cardid string y wallet card identifier * value granted from the partners portal cdata string y encrypted card object json * this field needs to be encrypted * see security partnercode string y partner code * value granted from the partners portal buttonid string y dom element id for the "add to wallet" web button for samsung wallet buttontype string n "add to wallet" button type [ "btnsw" / "btnatsw", default btnsw ] * see image resources inline string n flag to display the "add to wallet" image button in one-line format default true one-line locale string n locale of the "add to wallet" image button * see image resources rdclickurl string y url for logging a button click event * value granted from the partners portal rdimpressionurl string y url for logging a button impression event * value granted from the partners portal showforced string n flag to force the "add to wallet" button to be displayed default false mediatheme string n load the button’s resources from the media theme policy there are 4 themes default, inversion, lightonly, and darkonly default default *default load the button’s theme according to the prefers-color-scheme policy *inversion load the inverse of the default button’s theme *lightonly load the light theme of the default button *darkonly load the dark theme of the default button style string cssstyledeclaration n load the button with custom style target string n option to choose button’s target name * default “wallet” onshowbutton function n callback handler function for the button’s on-show event onclickbutton function n callback handler function for the button’s on-click event if you register the handler function, you must return a callback or promise value * see usage of onclickbutton handler samsungwallet addbutton function this function allows you to explicitly render the samsung wallet api for the "add to wallet" web button samsungwallet addbutton { cardid "card_id", cdata "cdata", partnercode "partner_code", targetid "target_id", buttonid "button_id", rdclickurl "rd_click_url", rdimpressionurl "rd_impression_url", } button attributes unlike the samsung wallet html tag, you must use camelcase in the button attributes in function case attributes type required description cardid string y wallet card identifier * value granted from the partners portal cdata string y encrypted card object json * this field needs to be encrypted * see security partnercode string y partner code * value granted from the partners portal targetid string y dom document object model element id to place the "add to wallet" web button for samsung wallet buttonid string y dom element id for the "add to wallet" web button for samsung wallet buttontype string n "add to wallet" button type "btnsw" and "btnatsw" default btnsw * see image resources inline string n flag to display the "add to wallet" image button in one-line format default true one-line locale string n locale of the "add to wallet" image button * see image resources rdclickurl string y url of logging a button click event * value granted from the partners portal rdimpressionurl string y url of logging a button impression event *value granted from the partners portal showforced string n flag to force the "add to wallet" button to be displayed default false mediatheme string n load the button’s resources from the media theme policy there are 4 themes default, inversion, lightonly, and darkonly default default *default load the button’s theme according to the prefers-color-scheme policy *inversion load the inverse of the default button’s theme *lightonly load the light theme of the default button *darkonly load the dark theme of the default button style object cssstyledeclaration n load the button with a custom style target string n option to choose button’s target name * default “wallet” onshowbutton function n callback handler function for the button’s on-show event onclickbutton function n callback handler function for the button’s on-click event if you register the handler function, you must return a callback or promise value * see usage of onclickbutton handler usage of onclickbutton handler you can choose whether to proceed with the next "add to wallet" step using a promise or a callback function, if you register a callback handler in onclickbutton we recommend that you add the process of generating jwt cdata add cdata to options cdata to this handler, because of the cdata expiration time the function parameters are defined as follows attributes type required description options button attributes n attributes of the current button callback function n callback function to pass the flag to proceed default false promise resolve function n promise-resolved value to pass the flag to proceed default false callback to web button process from callback attributes for es5 by executing a callback function with a flag, you can proceed to the next 'add to wallet' process onclickbutton function options, callback { // todo partner's process callback flag } callback to web button process from returning promise for es6 by returning a promise with a resolving flag, you can proceed to the next ‘add to wallet’ process onclickbutton async options => { return new promise async resolve, reject => { // todo partner's process await resolve flag } } importantthe card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “add to wallet” button samsung wallet on the app the following outline explains how to implement the "add to wallet" button on a native application get button graphic resources from a repository depending on your service environment for more information, see image resources check availability by calling the "check service available devices" apo, then determine whether to show up the "add to wallet" button on the user device a if "available" on response has "true" -> support b if has "false" -> not support implement a jwt web link on the button triggered action app button reference app button on android sample code implementation public class walletcodesample { protected final static string tag = "samsungwalletsample"; protected static final string host = "https //api-us3 mpay samsung com"; protected static final string path = "wallet/cmn/v2 0/device/available"; /** * sample entry point of the usage */ public static void main { executors newsinglethreadexecutor submit -> { final string modelname = build model; final string countrycode = null; // optional country code iso_3166-2 final string servicetype = "wallet"; // required, fixed for samsung wallet final string partnercode = null; // required try { walletcodesample sample = new walletcodesample ; boolean iswalletsupported = sample checkwalletsupported modelname, countrycode, servicetype, partnercode ; string msg = string format "query for model %s , countrycode %s , servicetype %s , partnercode %s / wallet supported? %s ", modelname, countrycode, servicetype, partnercode, iswalletsupported ; log d tag, msg ; } catch exception e { // failed to check due to some reasons log e tag, e getmessage , e ; } } ; } /** * please see the wallet api spec document > '6 6 check service available devices' for more details * * @return true if wallet supported, otherwise false * @throws exception throws exception when it's not possible to get status due to any reasons */ public boolean checkwalletsupported @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype, @nonnull string partnercode throws exception { if modelname == null || modelname isempty { log e tag, "model name is required parameter" ; throw new exception "something went wrong failed to get device model name " ; } if servicetype == null || servicetype isempty { log e tag, "servicetype is required parameter" ; throw new exception "something went wrong failed to get device servicetype " ; } if partnercode == null || partnercode isempty { log e tag, "partnercode is required parameter" ; throw new exception "something went wrong failed to get device partnercode " ; } string urlstring = makeurl modelname, countrycode, servicetype ; log i tag, "urlstring " + urlstring ; try { url url = new url urlstring ; httpurlconnection connection = httpurlconnection url openconnection ; connection setrequestproperty "partnercode", partnercode ; connection setrequestmethod "get" ; int responsecode = connection getresponsecode ; log i tag, "responsecode " + responsecode ; bufferedreader bufferedreader; if responsecode == 200 { bufferedreader = new bufferedreader new inputstreamreader connection getinputstream ; } else { bufferedreader = new bufferedreader new inputstreamreader connection geterrorstream ; } stringbuilder sb = new stringbuilder ; string inputline; while inputline = bufferedreader readline != null { log i tag, inputline ; sb append inputline ; } connection disconnect ; bufferedreader close ; // parse result jsonobject jsonobject = new jsonobject sb tostring ; string resultcode = jsonobject getstring "resultcode" ; string resultmessage = jsonobject getstring "resultmessage" ; if "0" equals resultcode && "success" equals resultmessage { return jsonobject getboolean "available" ; } else { throw new exception "something went wrong, resultcode " + resultcode + " , resultmessage " + resultmessage + " " ; } } catch ioexception e { log e tag, e getmessage , e ; throw new exception "something went wrong ioexception , " + e getmessage ; } catch jsonexception e { log e tag, e getmessage , e ; throw new exception "something went wrong, receive wrong formatted response, " + e getmessage ; } } protected string makeurl @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype { stringbuilder sb = new stringbuilder ; sb append host append '/' ; sb append path ; sb append '?' append "servicetype" append '=' append servicetype ; sb append '&' append "modelname" append '=' append modelname ; if countrycode != null && !countrycode isempty { sb append '&' append "countrycode" append '=' append countrycode ; } return sb tostring ; } } importantthe card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “add to wallet” button samsung wallet on an mms/email the following guides how to configure wallet code on email and mms messages implement the data fetch link process, including server apis you need to create a unique "reference id" for security reasons, make sure the "reference id" is complex enough that no important information can be inferred deliver a message including the web link through the chosen message platform for mms, the designed link shows up as a "smart suggestion" on samsung devices you can find a sample web link on the wallet cards guide on the partners portal for card data, samsung wallet asks the partner system to provide card details through the server api duplicate requests are prohibited on the same device link to “add to wallet” on an mms/email you can add an “add to wallet” web button even in environments where the javascript api cannot be loaded, such as sms or email these methods do not support controlling “add to wallet” button visibility mms link url link url attributes type required description url string y “add to wallet” link url * see [data transmit link][data transmit link] * see [data fetch link][data transmit link] email on web button link <a href="url"> <img src="image_url"> <img src="rd_impression_url" style="width 1px; height 1px;"> </a> attributes type required description url string y “add to wallet” link url * see [data transmit link][data transmit link] * see [data fetch link] [data transmit link] image_url string y button’s image resource url * see image resources rd_impression_url string y impressions logging url * value granted from the partners portal statistics service samsung wallet serves useful statistics data of the integrated service on the partners portal the data configured by making simple api calls for each event such as button impression and click these are necessary to provide better services as well notestatistics api sample code you can find actual code sample at wallet script guide section in [‘wallet cards’ menu on the partner portal ][wallet cards] event notification api https //us-rd mcsvc samsung com/statistics/{event}/addtowlt?{parameters}&utm_source=partner&utm_medium={channel} {event} for each event in the following situations - impression when the “add to wallet” button has been shown - click when the “add to wallet” button has been clicked {parameters} includes key factors to figure out the service {channel} - app "samsung wallet" button in a native application - web "samsung wallet" button on the web - email "samsung wallet" button in an email for details, please visit 'wallet cards' menu on the partner portal