server interaction adding users' cards to samsung wallet allows for the updating of their data using server interactions if partners want to manage the added cards, they need to find the card details to configure the api on the partners portal the samsung server sends a notification of the result of the 'add to wallet' operation with send card state partners get the callback url for samsung server api from the send card state payload using the callback url, partners can perform actions for the added cards with the samsung server api depending on the interfaces, the samsung server triggers specific operations for example, when update notification is called, the samsung server calls the partners' server to look up the updated contents partner server api the samsung server can call the following apis by using an endpoint in 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 detailed information of the requested card request type value description method get url {partner server url}/cards/{card id}/{refid}?fields={fields} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details x-request-id string 32 required request identifier randomly generated uuid string path parameters card id string 32 required wallet card identifier * refer to "add to wallet" interfaces for more details refid string 32 required 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 * refer to balance,barcode 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 conditional card object json * this field needs to be encrypted * refer to security for more details 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 * refer to wallet cards for more details 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 * refer to card states for more details data[] language string 8 required default content language code for example, en, ko data[] attributes object required card data attributes data[] attributes {fields} attribute fields by card type * refer to wallet cards for more details data[] localization[] array of object optional information for multilingual support localization[] language string 8 required multilingual content language code for example, en, ko localization[] attributes {fields} for displaying a given language, "data[] attributes" can be replaced by localized versions * refer to wallet cards for more details 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" *refer to wallet cards }, "localization" [{ "language" "ko", "attributes" { "title" "삼성월렛" } }] }] } } refer to wallet cards for more details 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 * the card will be removed from the wallet service 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 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/{card id}/{refid} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details x-request-id string 32 required request identifier randomly generated uuid string path parameters card id string 32 required wallet card identifier * refer to ‘add to wallet’ interfaces for more details refid string 32 required unique content identifier defined by the content provider query parameters cc2 string 2 required country code cc2 * must use this on samsung server api event string 16 required events on wallet card for example, added, updated, pending, deleted * refer to card states for more details payload callback string optional callback url for samsung server api example post /cards/12584806754/ref-20230304-001?cc2=kr&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 fromfulfilling 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 need to configure token-based authentication refer to authorization token for more 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/{card id}/notification headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details x-smcs-partner-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 card id 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 * refer to wallet cards for more details 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, pending * refer to card states for more details example post /wltex/cards/12584806754/notification [headers] authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] { "card" { "type" "ticket", "data" [ { "refid" "ref-20230304-0003", "state" "updated" } ] } } 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 * the card will be removed in the wallet service 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/{card id}/cancellation headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details x-smcs-partner-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 card id 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 * refer to wallet cards for more details 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, active, updated, expired, redeemed, held, deleted, suspended, pending* refer to card states for more 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 * the card will be removed in the wallet service 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