API Guidelines
add to wallet functionality allows users to securely add cards such as loyalty cards, payment cards, or tickets to their samsung wallet app to ensure a smooth and successful integration, partners need to follow specific api guidelines for adding card specs here is an overview of the steps and key components you need to consider when integrating the api for adding wallet cards data transmit link the data transmit link is the api endpoint through which partners send the initial card data e g , card number, expiration date, issuer information, barcode, etc to samsung wallet 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 note-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 manager signs 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 partners and 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 the data fetch link allows partners to retrieve card details after the card has been added to the samsung wallet 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 note- 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 description url https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateidstring 4 conditional ertificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardidstring 32 required wallet card identifier * it must be generated from partners portal hash path parameters #clipstring 5 required parameters for the hash link query parameter pdatastring 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 - https //a swallet link/atw/v3/ymtt/1656147182764415319#clip?pdata=sighcziwm9g updating wallet card specs when users add cards to samsung wallet, their data can be updated through server interactions to manage these updates, partners need to configure their api settings via the partner portal follow the steps below to manage and update the cards added to samsung wallet 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 ![] https //d3 unf4s5rp9dfh cloudfront net/samsungwallet_doc/updating-wallet-card-specs png 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 the get card data allows partners to retrieve the most up-to-date information about a card that has already been added to samsung wallet this api is crucial for ensuring that the partner’s system has accurate and current details about a user's card, whether for display, transaction validation, or other purposes [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 * refer to 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 cards includes sensitive data, it is highly recommended using 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-0002", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet" /* refer to 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 from fulfilling the request 503 service unavailable server is not ready to handle the request send card state the send card state is used to 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 x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * refer to the '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 the samsung server api allows partners to notify their content changes to samsung wallet depending on your service requirements, you can choose from private domain or public domain to send notifications the domain selection depends on your system's needs and security preferences service domain environment domain public domain https //tsapi-card walletsvc samsung com private domain ‘callback’ field from send card state api request payload key components private domain recommended for ip registration - if your service requires registering static ip addresses on your system, we recommend using the private domain when you use the private domain, you will receive a callback url in the send card state api response this url will direct your system to the correct endpoint to send content updates or changes public domain recommended for no ip registration - if your service does not require ip registration or has more flexible network access, you can use the public domain the public domain api endpoint allows easier integration without requiring specific ip addresses to be registered however, it does require a country code cc2 as a path parameter for each request this ensures that content is correctly routed based on the user's region or country to configure the api integration for different environments e g , testing, production , you must first register a new card service with samsung this process will assign you a new card id for use in your api calls the card id is crucial for identifying and tracking the specific card you are interacting with to ensure safe and secure communication, servers should configure token-based authentication for information, refer to the authorization token update notification allows partners to notify samsung wallet when there are changes or updates to the content of a wallet card this ensures that the card information within samsung wallet remains up-to-date and accurate [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 a 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 send card state 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 eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o 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 ok204 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 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 from fulfilling the request 503 service unavailable server is not ready to handle the request cancel notification allows partners to inform samsung wallet when a card such as for performances, sports, movies, or journeys needs to be cancelled when a cancellation occurs, this api enables partners to set the related card s to an expired status this ensures that users no longer have valid access to events or services that have been cancelled, such as a concert, flight, or movie screening [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 e g , canceled* see card states for details [example] post /wltex/cards/12584806754/notification [headers] authorization eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] * a movie ticket has been canceled { "card" { "type" "ticket", "data" [ { "refid" "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 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 from fulfilling the request 503 service unavailable server is not ready to handle the request