API Guidelines
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={jwe card data token}> 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 128 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 data action link this api is a link-based execution interface that triggers predefined user actions via the adata parameter when opened, the app/web screen collects user inputs as required on successful authentication, the flow continues into registration, and the partner must return the necessary card data or identifier to complete process this api is primarily used to invoke the request action api see the request acoion api section for further details type value description url https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?adata={adata} path parameters certificateidstring 4 conditional certificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal* required if using v3 path 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 16 required specified the predefined action to execute when the link is opened the app/web ui collects inputs as required by server configuration by default, once authentication succeeds, the process automatically continues into registration, with the partner returning the necessary card data or identifier for the authenticated user allowed values user_auth example - https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?adata=user_auth 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 general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet [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 128 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 request action handles card-related operations dynamically based on the specified actiontype the request must include an actiontype to specify the intended operation, along with a corresponding actionpayload that contains the relevant data for that action the response may include data required for the next step in the process this api is designed to handle sequential or conditional workflows, allowing both the server and client to coordinate securely across multiple steps [request] type value description method post url {partner server url}/cards/{cardid}/{refid}/requestaction headers authorization string 1024 required authentication token composed of jwt headers and payloads may include items that require verification such as timestamp, otp, certificate info the token can have prefix "bearer" as an authorization type e g , bearer * 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 128 conditional a unique content identifier defined by the content provider query parameter payload actiontypestring 32 required a string that specifies the current action to be performed in the card operation flow this value determines how the server interprets the 'actionpayload' and responds * refer to actions actionpayloadobject required an object containing the data required to process the given actiontype its structure varies depending on the action being performed* refer to actions actionpayload signedatwlinkstring optional a base64 encoded secure atw link containing a timestamp ts and an rsa signature sig used for validating the request this field is only applicable when actiontype is check_eligibility actionpayload actiondetailsobject optional provides metadata about the action actiondetails timestampstring optional the time when the action was initiated, represented as a unix timestamp e g , "1748410130000" actiondetails eventstring optional the type of event associated with the action actiondetails reasonstring optional the reason for the action actiondetails levelstring optional the severity level of the event e g , info, error actiondetails sourcestring optional the source of the action actionpayload {fields}string/object optional the key-value pairs of data that the client will transmit, depending on the integration method [example transfer_card ] { "actiontype" "transfer_card", "actionpayload" { "receivername" "leesamsung", "phonenumber" "01012345678", "actiondetails" { "timestamp" "1748410130000" } } } [example retrieve_card ] { "actiontype" "retrieve_card", "actionpayload" { "actiondetails" { "timestamp" "1748410130000" }, "transferreservationnumber" "trasfer-1234" } } [example get_refund_fee ] { "actiontype" "get_refund_fee", "actionpayload" { "actiondetails" { "timestamp" "1748410130000" } } } [example refund_card ] { "actiontype" "refund_card", "actionpayload" { "fee" "1000", "actiondetails" { "timestamp" "1748410130000" } } } [example user_validation ] { "actiontype" "user_validation", "actionpayload" { "actiondetails" { "timestamp" "1748411130000", "event" "issue_by_user", "source" "wallet_app" }, "domainid" "ds8f7g2gh", "certificatenumber" "109375" } } [example req_reissuance ] { "actiontype" "req_reissuance", "actionpayload" { "actiondetails" { "timestamp" "1748410130000", "event" "reissue_request", "source" "wallet_app" }, "refid" "dg76s8dfewr" } } [example check_reissue_state ] { "actiontype" "check_reissue_state", "actionpayload" { "actiondetails" { "timestamp" "1748450130000", "event" "reissue_by_user", "source" "wallet_app" }, "refid" "dg76s8dfewr" } } [response] type value description http status 200 ok 204 no content payload actiontypestring 32 optional a string that specifies the current action to be performed in the card operation flow this value determines how the server interprets the actionpayload and responds * refer to actions actionpayloadobject optional an object containing the data required to process the given actiontype its structure varies depending on the acbtion being performed* refer to actions actionpayload actiondetailsobject optional provides metadata about the action actiondetails timestampstring optional the time when the action was performed, represented as a unix timestamp e g , "1748410130000" actiondetails eventstring optional the type of event associated with the action actiondetails reasonstring optional the reason for the action actiondetails levelstring optional the severity level of the event e g , info, error actiondetails sourcestring optional the source of the action actiondetails codestring optional a unique code identifying the action result actiondetails messagestring optional a descriptive message explaining the action result actionpayload {fields}string/object optional the key-value pairs of data that the client will transmit, depending on the integration method [example] success 200 ok | 204 no content successful case { "actiontype" "action_type", "refid" "reference_id", "actionpayload" { "actiondetails" { "timestamp" "1748410130000" } } } successful case - transfer_card { "actiontype" "transfer_card", "refid" "reference_id", "actionpayload" { "actiondetails" { "timestamp" "1748410130000" }, "transferreservationnumber" " trasfer-1234" } } successful case - get_refund_fee { "actiontype" "get_refund_fee", "refid" "reference_id", "actionpayload" { "fee" "1000", "actiondetails" { "timestamp" "1748410130000" } } } failed case { "actiontype" "action_type", "refid" "reference_id", "actionpayload" { "actiondetails" { "timestamp" "1748410130000" "errorcode" "code", "errormessage" "messasge" } } } [result] http status code description 200 ok success 204 no content card doesn’t exist additionally, this indicates the completion of the processing sequence for the action corresponding to the specified actiontype 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 404 not found the requested resource could not be found on the server 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 note- actionpayload is included in both request and response to carry dynamic provisioning artifacts signedatwlink should be validated server-side using the certificate which has been exchanged action-specific validations should be enforced based on actiontype 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[] atwlinkstring 4096 conditional this "add to samsung wallet" link is used when additional card registration associated with this wallet card is provided * this is a required field, especially when the state is "migrated" data[] oldrefidstring 128 conditional if a new refid is provided, it specifies the value of the associated previous refid * this is a required field, especially when the state is "migrated" 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 {jwt auth token} 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" } ] } } [case 4 the card is migrated] { "card" { "type" "idcard", "data" [ { "refid" "bjd8w6reda", "state" "migrated", "oldrefid" "dg76s8dfewr", "atwlink" "{atw link with the new refid}" } ] } } [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 batch update notification updating multiple contents by sending batch update to samsung server [request] type value description method post url {cc2}/wltex/cards/{cardid}/batch/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 cardid string 2 required wallet card identifier granted from partner portal payload cardobject required wallet card object card typestring 16 required wallet card type *see wallet cards card data[]array of object required wallet card data container data[] eventidstring 32 required a unique event identifier defined by the content provider data[] statestring 16 optional wallet card statee g , active, updated, expired, redeemed, held, deleted, suspended * see card states for details [example] post /wltex/cards/12584806754/batch/notification [headers] authorization {jwt auth token} x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] case 1 in general cases { "card" { "type" "ticket", "data" [ { "eventid" "event-0001", "state" "updated" } ] } } case 2 in case of deletion { "card" { "type" "boardingpass", "data" [ { " eventid " " event-0001", "state" "deleted" } ] } } [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 get reference ids partners can call this api to get basic information regarding card refids based on the eventid this api will require the eventid attribute in each card type also, the filter option must be enabled for the eventid attribute in order for this api to work [request] type value description method post url wltex/cards/{cardid}?eventid={eventid}&type={type} headers authorizationstring 1024 required credential token the token can have prefix "bearer" as an authorization type e g , bearer * see authorization token x-smcs-cc2string 2 required country code cc2 x-request-idstring 32 required request identifier randomly generated uuid string path parameters cardidstring 32 required wallet card identifier granted from partner portal query parameter eventidstring 32 required event id typestring 32 required type of card boardingpass, ticket, coupon, etc payload n/a [example] get /wltex/cards/12584806754?eventid=testing&type=boardingpass [headers] authorization {jwt auth token} x-request-id req-202303140004 x-smcs-cc2 us [response] type value description http status 200 ok payload countstring required number of refids refidsstring array required list of reference ids [example] "count" “1”, “refids” [“12345”] [result] http status code description 200 ok success 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