Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
Develop Samsung Wallet
doccommon this chapter defines wallet card data fields for the attributes object of each wallet card type the structure for configuring wallet cards follows the defined specification configuring the card data in the specified formatted json structure is required see the details for each card type type value description card object card object required card information card type string 16 required wallet card type card subtype string 16 required wallet card sub type card data[] array of object required wallet card data containerallows up to 6 objects at once data[] refid string 32 required a unique content identifier definedby the content provider data[] createdat long 13 required data creation timestamp epoch timestamp in milliseconds * utc±00 00 data[] updatedat long 13 required data creation timestamp epoch timestamp in milliseconds * utc±00 00 data[] language string 8 required default content language code e g , en, ko data[] attributes object required card data attributes * refer to the following chapters for each type data[] attributes {fields} attribute fields by card type data[] localization[] array of object conditional information for multilingual support localization[] language string 8 required multilingual content language code e g , en, ko, etc localization[] attributes {fields} for displaying a given language,‘data[] attributes’ can be replaced bylocalized versions * refer to the following chapters for each type [example] example card object { "card" { "type" "relyingparty", "subtype" "others", "data" [ { "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" //** please refer to the details of the following each card ** }, "localization" [ { "language" "ko", "attributes" { "title" "삼성 월렛" } } ] } ] } } to ensure secure card data transmission, it must be tokenized in jwt format for this purpose, partner will need the certificate obtained using the partner's email account when signing up for the partner portal for detailed information on secure data tokenization, partners can refer to the security chapter *image resources provided by urls can be cached therefore, for the image resource to be replaced immediately, the corresponding url path must be changed
Develop Samsung Pay
docoverview developers of merchant/issuer apps familiar with the android or javascript programming environment are the target audience for this guidance in accordance with the applicable samsung partner agreements, it covers the setup and use of the samsung pay sdk and services for purposes of integrating the samsung wallet app with partner apps developed by both merchants and payment card issuers for samsung devices and is intended for no other purpose the accompanying use cases and related code samples are simply meant to serve as representative examples and not as recommendations or requirements please be aware that certain samsung pay apk behavior may not be exactly the same in different countries due to regulatory restrictions in each one use the samsung and samsung pay documentation specific to the market you are working in and test your integrated project in accordance with the instructions given for that market/country samsung pay sdk the android sdk offers an easy-to-use api application programming interface that you may use to integrate payment functionality into your apps push provisioning, processing payment requests, obtaining payment data, and managing payment transactions are all services available through the api web checkout sdk online applications can use the straightforward and user-friendly interface provided by the samsung web checkout sdk to accept payments the sdk's adaptability enables web application developers to modify the checkout procedure to meet their own requirements save to pay provides integration interface for end users to provision payment cards from website into the samsung wallet app using desktop computer, tablet device or mobile minimal partner effort and a very straightforward integration interface are two design objectives of save to pay overall, the samsung pay offers developers strong and adaptable platforms to integrate payment functionality into their apps the samsung pay is a great option for developers who want to provide their users with a smooth payment experience inside of their apps because it supports a broad variety of payment methods, has a secure payment processing system, and is simple to use samsung pay integration life cycle integrating samsung pay to your application has following five steps step-1 register as a member to develop a samsung pay sdk service, merchants and issuers need to register for an account with samsung pay developers in order to create the appropriate service type for their applications here is the guide on becoming a member become a member step-2 configure your project configure your project by creating services and registering application in the samsung pay developers portal according to your chosen sdk create services https //pay samsung com/developers/tour/memberguide register apps https //pay samsung com/developers/tour/appsguide manage services and apps https //pay samsung com/developers/tour/svcnappsguide step-3 integrate with samsung pay follow the below guidelines for specific sdk integration process android sdk https //developer samsung com/pay/native/common-api html web checkout sdk https //developer samsung com/pay/web/overview html save to pay https //developer samsung com/pay/save2pay/overview html step -4 test and validate testing your application is critical to validating samsung pay push provisioning performance or samsung pay transaction performance this will ensure a positive user experience for your users and an effective business channel for your company in fact, the goal of testing is not merely to find errors but to fully understand the quality of the samsung pay integration step-5 release you need to get release version approval from samsung via samsung pay developers portal once you are approved, you can proceed to make your application live and monitor user satisfaction
Develop Samsung Wallet
docapi guidelines adding wallet 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
docsecurity the following contents describe how to generate jwt json web token it follows rfc 7519 specification for more details, refer to https //jwt io json web token jwt card data token for secure data inter-communication, the token must be encrypted and signed using security factors see the chapter security factors factors for details jwe format [jwe header] jwe header requirement description alg required cryptographic algorithm used to encrypt the content encryption key cek , e g , rsa1_5 enc required content encryption algorithm used to perform authenticated encryption on the plaintext to produce the ciphertext [jwe payload] jwe payload requirement description encrypted_key required contains the base64url jwe encrypted key value the content encryption key is encrypted with the public key iv required contains the base64url jwe initialization vector value initialization vector used in the encryption algorithm ciphertext required ciphertext value resulting from authenticated encryption of the "cdata" object, which is encrypted using "encrypted_key" and "iv" authentication tag required contains the base64url jwe authentication tag value, used for verifying the integrity of the ciphertext [jwe example] base64url utf8 jwe header + ' ' + base64url jwe encrypted_key + ' ' + base64url jwe iv + ' ' + base64url jwe ciphertext + ' ' + base64url jwe authentication tag [jwe header] {"enc" "a128gcm","alg" "rsa1_5"} [jwe payload ciphertext] refer to the tables in "add to wallet" interfaces, and wallet cards [result] eyjrawqioijxtfquufvcs0vziiwizw5jijoiqteyoeddtsisimfszyi6iljtqtffnsj9 abo_ci81btj2d1a8tcgkfwbx9wpri4tkhhzwms8swct_2nnzhasi_nklmj3wnkm5gwaouny14zx_6eozhj6tdiicuq-rairs6woesu8xa2dt1sc5l17wu9wdsgok4anj0kiunii4pler3d-4fox1hx1fok9siwwqqfql4vnqg3he-i4j6cywoybphznybmkyynkiqfczl6lbttehc4tdaorpkwra3vmb0bbz5nyzf1axzfk-17tz0gfhs82a7gl9rej1k5b10_2qfgmhttffvcyytmkv3inmahq0b48l3sk1oppmfcuqigymvludbg_qwdnbl9eilinojjt8ar2nua zviyghusi5fb2rl2 gm5ivizrqqdr8npk1n2qreyai4md-fisfwtbbbgebhnhjmnu-c_o1yuyrvdhcm0ki_rvcdnzkdlcp_g7shskmroyin3bi92qgtkfh2v4y-kcug2dvgv9uiv3oxawvlikfcntmzizj3thv_fue7jrnrbwf2xmviwsqo5b0lmouskbhuhasqilre0rtc1fgn03qfe_e-b87vht5en2pnbydjv-6_8g3aessyodvhyzyayonlxw_kwqif-i5auwfiigk5lgvmuz9dsl6-qkgyiz5pl9nyydjjjpilibtualyvzb1ch-gskweuhiml62zr-chz2ado8vn0sroccjhcax6pbsp3x6fhyxhr65bjzan4lmdfsskn92bcfyclx8j_pgrlm4vui_-kx1lwparkwrtyxmebkmj-2w8numrnnpgt2erlo_hvtz8xh1kopvqjldjdg_qqfu_oewo3hvunkgqeu3qhi6eywvarb7ozsisz-f95o7k-kqtjhfbwz_yra2nxd2bcgc9ua966_9uq4ombwa-8fccawpxyyu4vzbz_ycv25j8grdqhhtw6n9tkzy4nu07jit4ccofvu5n_gsyn1qowd11-_lmk8amf-l5ddipvrun7dealjd8me4nsaakeslqfkz_sddsu0-05icfkm33quqp6fzn5ocy6dmn5kzbvqxzhghcg_a_k1xqqlx_kupl4jsaxcnciuyptdqbc0hxxwuiyrm3tcde6picymgcbpkc205niyld-6en43di4ykc029yqx8rsldoaa6rwvp-zehdkxynyilja-_8fw4ioqp6vk98ajz5t-ajqdk1h6n_opt-zcjkjzz-7r2x07bsa_5ng7iwambrsv1defxhiyv-esce1meif-na_411hgpja-gwczp_wsswlqra0rpdq208ly70xppu4h_3eh_6q8cy5yhhns93vfuo0nsqfniker25zwnid39zoiyj_de9gzjawxa3k0tprpn5mfdpxvtd0-ro4oqi34ab62-rubcdydsmtggihzy3shlgtyafrbzhmpmdkauoj9buirasqpnr4nahfq_s1m1uy5peeq3j0bozmcc4uasnqqnrrelqm8bkfqi41ggjrjm9uvkcr-pmfonsheoqjmce6zkua1qtoefxycdfoejbjqdbcycnoqgugodlqn2-3mkggrpvqvyaolomykc_sl8kpdvjxntkggzqb9vnlnlq9_fy3hmyor0zeexytajfua-4ilsfkg3crqkx3sccsp-w6rf7vfzx5vdhqbhfzbhbuxypfj1bdmis_w-xqdvr1kgblzmsw9grbwm2mk8rt9qpzinhcaqfv2dqagqth4vyuccq0mjcs5qgnbkwdiggvxfk7bhwhk2jrw3k4egjqna9lssnhcjhqz69m16ivbffktnz5ot0l-npkcqeifia-rjmwyy6beodzi8s7s4l4yvlmvjjidujxkb7zsqusvrvizpljmk1rsbvgww7rfojlci9ed-mhpsmxvepj2uxezxu95z_vx7i8xgszxmlwrmsi0eepa5tl7gqfxfimtv4v_o8rjiipqtdjmkenkflnvkn8wio7nosfyak1gplxkpr2scieltcirpweu_4y56yq3wxbvnwcax7yyjytubirk30znw84omyyljc67wntybeqi3ty1vz6wxraenn_dnwiku-ry_bvc9bjwzpgdnpzdtdqndhijleyk9zhzcwvjhvom7vms4cljs6ndqvm9yeilk55h-ejn22-1n1u6pmjeyfbvty0zfrf57sidtcitseejmhbm1uqdsk3rpfxv2hc0dyy9ok7uasdsifwhkczmue4qyurd3y4wvzhjjaprxqeqojfavz-vt-331jvajgkziifmpuyfck-kyrqbq193uya9sy6e-7ereid3cy7gylp9-tfsugobpulnydieamtqi1zaepwjkjqs9ljofdoojhxbqzy0-spitglnbmtuxpxqh6phh34vdb2fcgjttc8h1vp3_a0lvxxzumdu3jypc9ltqmxxg7xz4h4uqrvis2qm3xqwub1uto9syhfnpf16h0-u8bqdofg-yyba-qn_awn4ufs2ftfy-7yd1isp0g31lifmorplehz0pcgefo-mayacxsvgioptn67enmwe_grdwkzv27deocztmcn_fb7qvtdsle881rfz7lrhmitiuitdo4e0fkwuaz1cohrbpbhzmg30tljbxydb-lfq74rxfdc1eobj0vpcdaxomya9eoxcnt70tti16fr3lxjdysgqv_ihtfkdaummfyojjh_w9zagiwb2uxmhng0a3mpt8r80hzbppvh3hsb2uezww8aqtlmkalqf0g6nzqm181z46gnkz7w3h8a29-yci0ypz_m0pofihnwjrendjkew6azodehwyupsno7y93qdc8khhpzb84bkahbc2sye8wgvgmrhfiwsigfht_g3m8nlt3vfasqe98two0tzu3k72kmod8khdw6xq6oalxoba1m9wfi51wmjji8yr4ty-7pqdc51ombxsqurao0-6puja5dufuioq3yzm0iwr1yjciqaofp-xwn9crh287vjzhw2s4ges8s-wuda9yu61u3b1pwr0fyseouzquay_t3qkziaghvz0a2nefdy2wktmaonidqtsku8rhpknqalrc_ydnvyqooxnrdwjrxxilutvlaaqmygtl0zessrvpkh4inkiu0ikbdceqvnlcjqnuymc5u_dtic-pb7e9h4zwxm3talmlzoc-v1u0shzaqok3tvixa9uy9i3qvpz1realwg7w1yqquhpd-6pgolbddfqwxekb43jtry3wnxjizcgzoqwiuvpdhpzm0cyfzlx71cbcpyc3lkg_pduwkb2qjv2hjodusvstv8 bv9p-aoait1mfijswzevsg jws format [jws header] jws header requirement description alg required cryptographic algorithm used to generate signature e g , rs256 cty required payload content type set as "card" ver required token version set as 3 certificateid required certificate identifier based on a csr during onboarding 4 digits alphanumeric partnerid required partner identifier utc required creation time to prevent repeated use, the token expires after a certain period of time unix timestamp in milliseconds * time offset from utc of +00 00 [jws payload] jws payload requirement description jwe compact serialization required contains base64url jwe value [jws signature] jws signature requirement description jws signature required base64url signature of base64url utf8 jws header + ' ' + base64url jws payload [jws example] base64url utf8 jws header +' ' + base64url jws payload + ' ' + base64url jws signature [jws header] {"cty" "card","ver" 3,”certificateid” ”ymtt”,"partnerid" "1234567890","utc" 1631776245876,"alg" "rs256"} [jws payload] jwe result [result] eyjjdhkioijqqvntiiwidmvyijoxlcjwyxj0bmvyswqioiixmjm0nty3odkwiiwidxrjijoxnjm1odq1odu2mjq0lcjhbgcioijsuzi1niisimtpzci6ilbuti5qukllrvkifq zxlkcmfxuwlpaupyvezrdvvgvkntmfzaswl3avpxnwpjam9puvrfeu9fzeruu0lzsw1gc1p5stzjbepuuvrgzk5tsjkuqujpx0npodfcdeoyzdfhofrdz0tmv0j4ovdwukk0vgtosfp3bvm4c3djdf8ybk5asefzsv9us0xtajn3bktnnwd3yw9vbnkxnfpyxzzfb1posjzuzelpy1vrlxjhsvjznndvrvn1ofhbmmrumxndnwwxn3d1ovdkc2dpszrhbkows0lvtkljnfbmzvizzc00zm9ymuh4mwzvazlzsxdxcxfgcww0dm5xzznors1pneo2y3lxt1lccgh6tllctut5eu5rsxfgy3psnmxivfrfagm0verbt3jqs1dyytnwtuiwqkj6nu55ekyxyxh6rmstmtd0wjbhzmhtodjbn0dmovjfajflnuixmf8ycwzhbwhudgzgvmn5wvrns3yzsw5nyuhrmgi0oewzu0sxb1bqbuzddxfpz1lnvkxvrgjnx1fxzg5cbdllswxjbk9qanq4qxiytlvbllp2axlhsfvtatvgyjjsbdiuz201axzpenjruwrsoe5qszfomnfsrxlbstrnrc1gsvnmv1rcqkjnrwjotmhqtw51lwnfbzfzvvlsdmroq20ws2lfcnzjre5as0rmy1bfzzdzafnrtvjvwwlum2jjotjxz3rrrmgyvjrzlwtdducyrhzhvjlvsvyzb3hhv3zssutmy050bvppwmozvghwx0zvrtdkck5yyndmmlhnvkl3c1fvnwiwbg1vvxnlykh1sgfzculsukuwunrdmwznbjazcuzfx0utqjg3dmh0nuvumlbuqllesnytnl84zznhzxntew9kdkh5ellhww9uthhxx0txcwlglwk1qvv3rmljz0s1tgdwbvv6ourtbdytuutnwwl6nxbsow55ewrkampwswxpynr1yuxzdnpcmunilwdza3dfvwhptww2mlpslunoejjbzg84vm4wu1jvq2nksgnhwdzqqlnqm3g2rmh5wehynjvcslpbbjrsturmu3nltjkyymngewnmwdhkx3bnukxnnfzvsv8ts3gxbfdwqxjrd1j0wxhtrwjltuotmnc4tlvnuk5uced0mkvstg9fafz0wjhyadfrb3b2cwpmzgpkr19rcwzvx09fv08zshz1tkthuwv1m1fostzfevd2yxjin09ac0lzei1gotvpn0sts1f0smhmqld6x1lyqtjoeeqyqmnnyzl1qtk2nl85dve0b01cd0etoezjy0fxuhhzwvu0dlpcel95y1yynwo4r3jkcuhivhc2bjlus1p5ne51mddqsvq0y0nvrlz1nu5fr3n5bjfxb1demtetx2xnazhhtuyttdvkrglwdnj1bjderwfsskq4twu0tnnbqwtfu0xrzkt6x3nkzfn1mc0wnwljzkttmznxvvfqnmz6bjvpy1k2rg1unwtaqlzrwfpiz0hdr19bx0sxeffrbfhfa3vqtdrku0f4q05davvzufrecwjjmeh4whdvavlyttn0q0rlnnbpq3ltr0niuetdmja1tml5beqtnmvondnkstr5s0mwmjlzuxg4clnmre9bqtzsv3zwlvpfsgrlehloeulssketxzhgdzrpt3fwnnzlothbalo1vc1halfeszfonm5fb3b0lvpdsmtkwnotn3iyeda3qlnhxzvuzzdpd2ftqljtdjfkzuz4ael5vi1fc0nlmu1fawytbmffndexaedwsketr3ddenbfd3ntv2xxcmewulbectiwogxznzbyufb1nehfm0vixzzxogn5nvlosg5totnwzlvpme5tuwzoautluji1endosuqzoxpvaxlqx2rlowdaamfxwgezazbuuhjqbjvnzmrwwfzurdatcm80b3fjmzrhyjyylxjvqknkwwrzbvrhz0liwlkzc0hmr3r5qwzyqnpitvbnretbvu9koujvsvjhu3fwbni0tmfiznffuzftmvv5nxbfrvezajbit3pty2m0vufztlfrbnjyzuxxbthis0zrstqxr2dkukptovv2a0nslvbnrk9uu0hlt3fqbwnlnlpldwexcvrpruzywwnkrk9lakjqcurcy3ldtm9xr3vhb0rscw4yltnna0dhcnbwuvzzqw9st015s0nfu2w4a3bedmpytnrlz2d6uui5vm5sbmxrov9mwtnobxlvcjbaruv4evrhamz1ys00swxzrkthm2nyuwt4m3njq1nwlvc2cmy3dmz6wdv2rghxykhgwmjiynvywxbgajfirg1jc193lxhrrfzymutnymx6txnxowdsqndnmk1lohj0ovfqemlosgnhuwzwmmrryudrdgg0vnlvq2nxmg1kq1m1uwduqkt3zglhr1z4zms3qmh3sesyanjxm0s0zwdquu5houxtu05oq2pouvo2ou0xnmlwqmzma3ruejvvvdbmlw5qs2nrrulmauetcmptd1l5nkjfb2raathtn1m0bdrzdkxtdmpqaur1snhlqjdac1fvu1zyvml6ugxqtwsxunnidmd3vzdyzk9ktgnjowvklw1ichnnehzlcgoyvxhfwlhvotvax3zyn2k4eedtwnhtbfdybvnjmevfuee1vew3r1fmegzjtxrwnfzftzhsakljuff0repna0vos0zstlzrbjhxaw83bm9zzllbazfncgx4a1bsmlndsuvsvenjulb3zxvfnhk1nllxm3d4ylzud0nbwdd5ewp5vhvcsvjrmzb6tlc4ng9nwvlsskm2n3dudhlcrxfpm1rzmxz6nld4cmflbm5fze53swt1lvjzx2j2qzlcsldaugdetnbazfrkcw5eaglktev5szl6afpjd3zqsfzvbtdwtvm0q0xkczzozhfwbtl5zwlsazu1sc1fsm4ymi0xbjf1nnbnamv5rkj2dfkwekzyzju3c2lkvgnjdhnfrupnagjnmvvxzfnlm1jwrnh2mkhdmerzwtlpazd1qxnec0lgv2hlq1pndwu0uxlvcmqzwtrxdlpiampbufjycuvrb0pmyvzalvz0ltmzmwpwyupha3pjawznuhvzrmnrlwtzunfiute5m1vzytltwtzfltdfcmvjzdndetdhwwxqos1urlnvz29cufvmtnleauvbbxrrstf6ywvwd0planftouxkb0zkt09qafhicvp5mc1zcel0z0xuqk10dxhweffinnbosdm0dmrimmzdz2p0vem4adf2cdnfqtbmdnh4envnzfuzsllwyzlsdhfnwhhhn1hangg0vvfydkltmnftm1hrd1vcmxvutzltewhmtlbmmtzomc1voejrze9gry1zwwjblvfox0fxtjrvrlmyrlrgws03euqxaxnwmeczmuxjrm1punbmzuh6mhbjz0vmty1nyxlhy3hzvkdjt3b0bjy3rw5nd2vfr3jkd0t6vji3rgvvy3pubunux0zin1fwverzteu4odfsrno3thjotwlusvvjvgrvneuwrmtxvwfamunvshjccejowm1hmzb0tgpieflkqi1srne3nhjyzmrdmwvpqkowdlbjzef4b215qtlft1hdtnq3mhr0ste2rlizbhhqzfltr1f2x2lidgzrzgf1tu1gwu9kakhfvzlaywdjv2iydxhnae5hmeeztxbuofi4mehaqlbwdkgzsfnimnvleld3oefxvgxta0fscuywzzzuwnfnmtgxejq2z05lwjd3m2g4yti5lxldatb5uhpfbtbqt0zjag5xanjfbmrqs2v3nmfab0rfshd5vvbzbk83etkzuurjogtiafb6yjg0ymtbaejdmlnzzth3r3zntxjorkl3u2lnzmh0x0cztthobhqzdmzbc1floth0d28wvhp1m0s3mkttb0q4a2hkdzzyctzpywxyb2jbmu05d2zpntfxbwpqath5cjruws03chfeyzuxt21iefnrvxjbtzatnlb1ame1rfvgvulputn5wk0wavdsmvlky2lxqw9gcc1yv045q3jimjg3dkpaafcyczrhzxm4uy1xdwrhoxl1njf1m2ixchdsmgzzc0vpvxprdwfzx3qzcwtaawfhahzameeybkvgzfkyd2tubwfvbmlkcxrza3u4cmhqs25xyuxsq195zg52evfpt3huckr3sljyeelmdvrwbgfhuw1zz1rsmhplc1nsdnbrsdrjbmtjvtbpa0jeq2vrvm5mq0pxtnvztwm1dv9eveljlxbin0u5sdr6v3htm1rbbe1mem9dlxyxdtbzshphcw9rm3r2svhboxv5owkzcxzqejfyzufmv2c3dzf5cvfvafbkltzqr29symrkrnfxwevryjqzsnrsetn3bnhksvpdr1pvcxdpvxzqzehwem0wq3lmekx4nzfjqmnweumztgtnx3bevvdlqjjxslyysgpvzfvtdln0djguyny5cc1hb0fjddftzklkc1dazxztzw bwqnq5n8apkes9fbb4htdqbterdklaztmphx6r_h7k7og4lx3gmgds3fep6o4cs6jttutost6gdmudwzozztptwetj64p4of1wlzkf6tx8alrkaiqr2nptxh_ah87bkw69myzakb4d9obngp7qdk7izgkpq180olmbtpxiv-wkin92f6n2fpoi5bt1ws_hh8wxgla6nkm0s-roayl7gtvgbs6gohkhvgaxnhesqy7kzgqte9orcc_fliqyyrabhtpgybwb7wp0hpodzq0dpadumkkprs05vidfzjufxduyc7zbze-g_tixrjk3linf4rnzxyi0gohbw5grphu3wltg authorization token the restful api needs to include an authentication token jwt samsung and partners can use the token to authenticate api calls jwt format [jws header] jws header requirement description alg required cryptographic algorithm used to sign the payload e g , rs256 cty required payload content type, such as "auth" ver required token version set as 3 certificateid required certificate identifier based on a csr during onboarding 4 digits alphanumeric partnerid required partner id same as partnercode utc required creation time to prevent repeated use, the token expires after a certain period of time unix timestamp in milliseconds * time offset from utc of +00 00 [jws payload] jwe payload requirement description api required current api information api method required api method api path required api path refid optional a unique content identifier defined by the content provider authentication optional authentication value to be used in accordance with the pre-configured authentication method on wallet card * see the chapter authentication for more details updatedat optional data update timestamp epoch timestamp in milliseconds [jws header] {"cty" "auth","ver" 3,”certificateid” ”ymtt”,"partnerid" "1234567890","utc" 1631775948348,"alg" "rs256"} [jws payload] /** samsung server api > update notification **/ { "api" { "method" "post", "path" "/wltex/cards/12584806754/notification" }, "refid" " ref-20230304-0003" } /** partner server api > get card data **/ { "api" { "method" "get", "path" "/cards/12584806754/ref-20230304-0003" }, "refid" "ref-20230304-0003" } [jws result] eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjm0nty3odkwiiwidxrjijoxnjmxnzc1otq4mzq4lcjhbgcioijsuzi1niisimtpzci6ildmvc5qukllrvkifq ewogicagikfqssi6ihskicagicagicaibwv0ag9kijogikdfvcisciagicagicaginbhdggioiail2nhcmqvq1mxnjezodm1mzixmju4ndgwnjc1ncikicagih0sciagicaicmvmswqioiaiq1mxnjezodm1mzixmju4ndgwnjc1ncikfqo ascawii-ambjkoly_auzagxrwuumkfuhbznrlk0ykvbyog2dsljs-_xyq9tooh4cwsfpkej0vqkwbyrokabkhwmrdbkjrajeaq-87s-bqp1rcbelnzmfq66gcmbg9xpd6dmwwlnrazyszjrcyzkllu9si5qykrkyuoz34mcwzwdneos3z3gl1xft42m2-cduxkqwi0wfryanxiedwboiyu12sdnpsrbwlb7liw4omm6fg01dirtbk6ayumbf7zqjl_oygelv9jfdyoze0tqyklttshgdws7imyamha5nhagplhqivzaqoosa14gbcm1u0zdqw4jqa4-1vgjr_i5xea [authorization token] bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjm0nty3odkwiiwidxrjijoxnjmxnzc1otq4mzq4lcjhbgcioijsuzi1niisimtpzci6ildmvc5qukllrvkifq ewogicagikfqssi6ihskicagicagicaibwv0ag9kijogikdfvcisciagicagicaginbhdggioiail2nhcmqvq1mxnjezodm1mzixmju4ndgwnjc1ncikicagih0sciagicaicmvmswqioiaiq1mxnjezodm1mzixmju4ndgwnjc1ncikfqo ascawii-ambjkoly_auzagxrwuumkfuhbznrlk0ykvbyog2dsljs-_xyq9tooh4cwsfpkej0vqkwbyrokabkhwmrdbkjrajeaq-87s-bqp1rcbelnzmfq66gcmbg9xpd6dmwwlnrazyszjrcyzkllu9si5qykrkyuoz34mcwzwdneos3z3gl1xft42m2-cduxkqwi0wfryanxiedwboiyu12sdnpsrbwlb7liw4omm6fg01dirtbk6ayumbf7zqjl_oygelv9jfdyoze0tqyklttshgdws7imyamha5nhagplhqivzaqoosa14gbcm1u0zdqw4jqa4-1vgjr_i5xea secure add to samsung wallet authentication defines the data format to authenticate the user registering/updating the card if need a custom user verification process, please get in touch with us via tech support [authentication data set] case type value description connecting information ci user’s ci value identifier of identity verification agency samsung account sa user’s samsung account verifying that the signed-in samsung account on the user's galaxy device matches subscriber identity module sim sim card information on mobile telephone devices verify the sim information being used on the user's mobile phone one-time password otp dynamic password the temporary password provided by the partner to the user is verified by receiving user input during the add to samsung wallet process access token token token to verify data retrieval request token data included in card data is used as a key accessed when querying a partner server this tokenized key can be reissued when the partner delivers updated card data [example] type sample data ci {"ci" "hsd0iuf9bew8ugb7wqeu6i"} sa {"account" "samsungwallet@samsung com"} sim [{"uiccid" "abcderwyt","telno" "821012345678","isprimary" true},{"uiccid" "abcderwys","telno" "01012345679","isprimary" false}] otp {"otp" "947253"} token {"x-access-token" "7c8d38690d0e3b6aa077198abd2554a3a7940b52cf86bd690c1"}
Develop Samsung Wallet
docgift card 'gift card' cards support enrolling prepaid cards also known as gift certificate, gift voucher or gift token links urls to get balance and transactions history in real time is provided in the partners portal if a partner needs to integrate communication between samsung wallet server and the partner’s server to support the feature, the partner has to set the links in partners portal wallet card type wallet card type wallet card subtype giftcard others others wallet card data fields attributes type value description attributes {fields} title string 32 required main title e g , samsung gift card eventid string 36 optional if full cancelation of the event occurs, find and process all gift cards with this id orderid string 36 optional a unique identifier for an order subtitle1 string 32 optional the auxiliary field which displays supporting information logoimage string 256 optional logo image url to be displayed in the card item the file size should not exceed 256 kb logoimage darkurl string 256 optional logo image url in dark mode the file size should not exceed 256 kb logoimage lighturl string 256 optional logo image url in light mode the file size should not exceed 256 kb providernamestring 32 required gift card provider name user string 64 optional name of person who holds the gift card preventcaptureyn string 1 optional flag whether this wallet card view prevents screen capture either 'y' or 'n', the default value is 'n' startdate long 13 optional start date display start date epoch timestamp in milliseconds enddate long 13 optional end date display end date epoch timestamp in milliseconds locations string 1024 optional list of locations where the gift card can be used * see location format noticedesc string 5000 optional text of the notice * long content is allowed * see additional information format csinfo string 512 optional providers’ customer service informationusing data in json format converted to escape string * allowed items call, email, or website* see the example below applinklogo string 256 required app link image url the file size should not exceed 256 kb applinkname string 32 required app link name applinkdata string 256 required information about the partner app link bgimagestring 256 optional url for card art background image the recommended size for image resources is 888 x 555 px mainimg string 256 optional url for gift card image the file size should not exceed 512 kb bgcolor string 8 optional color of the card art e g ,#00ffff fontcolor string 8 optional color of the font on the card art acceptable values dark, light blinkcolor string 8 optional color of the blinking effect which indicates that a card cannot be captured in the indicator area e g , #00ffff barcode value string 4096 optional actual data that is delivered when the barcode/qr code is scanned barcode serialtype string 32 optional presentation type e g , serialnumber, barcode *see barcode format barcode ptformat string 32 optional presentation format e g , barcode, qrcode, serial *see barcode format barcode ptsubformat string 32 optional presentation sub-format e g , code_128, qr_code * see barcode format barcode pin string 16 optional pin to show with a barcode barcode errorcorrectionlevel string 4 optional amount of redundancy or error correction data included in the code there are four error correction levels available in qr codes * code options l/m/q/h merchantid string 36 optional merchant identifier merchantname string 32 optional merchant name to display amount string 32 optional initial balance this is going to be shown as received e g , $1,000 balance string 32 optional remaining balance this is going to be shown as received e g , $1,000 summaryurl string 256 optional web url that show details, such as balance or transactions history example { "card" { "type" "giftcard", "subtype" "others", "data" [ { "refid" "b3fdc982-28c9-47a3-b02f-d484779698a7", "createdat" 1672574400000, "updatedat" 1672574400000, "language" "en", "attributes" { "title" "samsung gift card", "eventid" "event-001", "logoimage" "https //gpp walletsvc samsung com/mcs/images/contents/wallet_intro_logo png", "logoimage darkurl" "https //gpp walletsvc samsung com/mcs/images/contents/wallet_intro_logo png", "providername" "samsung gift card provider", "user" "ms jane doe", "csinfo" "{\"call\" \"0000-0000\",\"email\" \"samsungwallet@samsungwallet com\",\"website\" \"https //www samsungwallet com/cs/\" }", "applinklogo" "https //play-lh googleusercontent com/znfa1roz7hpv9j-jiacbjmjudl2x-fnuwte0oyvbbcwvf5vpzoqqikbxgk7d-aptvag=w240-h480-rw", "applinkname" "gift card link", "applinkdata" "https //www samsung com/", "bgcolor" "#0a1a4f", "fontcolor" "light", "blinkcolor" "#00ffff", "barcode value" "cs16138353212584806754fg1802", "barcode serialtype" "qrcode", "barcode ptformat" "qrcodeserial", "barcode ptsubformat" "qr_code" } } ] } }
Develop Samsung Wallet
docloyalty 'loyalty' cards support enrolling loyalty cards also known as membership links urls to get points in real time can be provided in the partners portal if a partner needs to integrate communication between samsung wallet server and the partner’s server to support the feature, the partner has to set the links in the partners portal wallet card type wallet card type wallet card subtype loyalty others others wallet card data fields attributes type value description attributes {fields} title string 32 required main title e g ,samsung loyalty card eventid string 36 optional if full cancelation of the event occurs, find and process all loyalty cards with this id groupingid string 36 optional identifier used to group related cards orderid string 36 optional a unique identifier for an order subtitle1 string 32 optional the auxiliary field which displays supporting information logoimage string 256 optional logo image url to be displayed in the card item the file size should not exceed 256 kb logoimage darkurl string 256 optional logo image url in dark mode the file size should not exceed 256 kb logoimage lighturl string 256 optional logo image url in light mode the file size should not exceed 256 kb providername string 32 required loyalty card provider name startdate long 13 optional start date display start date epoch timestamp in milliseconds enddate long 13 optional end date display end date epoch timestamp in milliseconds locations string 1024 optional list of locations where the card can be used * see location format noticedesc string 5000 optional text of notice *html supported csinfo string 512 optional providers’ customer service information using data in json format converted to escape string * allowed items call, email, website, facebook, pinterest, x, or instagram * see the example below applinklogo string 256 required app link image url the file size should not exceed 256 kb applinkname string 32 required app link name applinkdata string 256 required information about the partner app link bgimage string 256 optional background image for a card art the recommended size for image resources is 888 x 555 px bgcolor string 8 optional color of the card art e g , #00ffff fontcolor string 8 optional color of the font on the card art acceptable values dark, light blinkcolor string 8 optional color of the blinking effect which indicates that a card cannot be captured in the indicator area e g , #00ffff barcode value string 4096 optional actual data that is delivered when the barcode/qr code is scanned barcode serialtype string 32 optional presentation type e g , serialnumber, barcode * see barcode format barcode ptformat string 32 optional presentation format e g , barcode, qrcode, serial * see barcode format barcode ptsubformat string 32 optional presentation sub-format e g , code_128, qr_code *see barcode format barcode errorcorrectionlevel string 4 optional amount of redundancy or error correction data included in the code there are four error correction levels available in qr codes * code options l/m/q/h merchantid string 36 optional merchant identifier merchantname string 32 optional merchant name to display amount string 32 optional total amount of points or initial balance this is going to be shown as received it is recommended to use a one letter currency symbol e g , $ 1,000, 1,000p balance string 32 optional available points or remaining balance this is going to be shown as received it is recommended to use a one letter currency symbol e g , $ 1,000, 1,000p summaryurl string 256 optional webpage url that shows details, such as balance or transactions history example { "card" { "type" "loyalty", "subtype" "others", "data" [ { "refid" "b3fdc982-28c9-47a3-b02f-d484779698a8", "createdat" 1672574400000, "updatedat" 1672574400000, "language" "en", "attributes" { "title" "samsung loyalty card", "eventid" "event-001", "logoimage" "https //gpp walletsvc samsung com/mcs/images/contents/wallet_intro_logo png", "logoimage darkurl" "https //gpp walletsvc samsung com/mcs/images/contents/wallet_intro_logo png", "providername" "samsung loyalty card provider", "noticedesc" "<ul><li>loyalty card test</li></ul>", "csinfo" " {\"call\" \"0000-0000\",\"email\" \"samsungwallet@samsungwallet com\",\"website\" \"https //www samsungwallet com/cs/\",\"instagram\" \"https //www instagram com/samsungwallet\",\"pinterest\" \"https //www pinterest com/samsungwallet\",\"x\" \"https //www twitter com/samsungwallet\",\"facebook\" \"https //www facebook com/samsungwallet\" }", "applinklogo" "https //play-lh googleusercontent com/znfa1roz7hpv9j-jiacbjmjudl2x-fnuwte0oyvbbcwvf5vpzoqqikbxgk7d-aptvag=w240-h480-rw", "applinkname" "loyalty card link", "applinkdata" "https //www samsung com/", "bgcolor" "#0a1a4f", "barcode value" "cs16138353212584806754fg1802", "barcode serialtype" "qrcode", "barcode ptformat" "qrcodeserial", "barcode ptsubformat" "qr_code", "amount" "1,000p", "balance" "500p" } } ] } }
Develop Samsung Wallet
docnotifications for partners partners can use pre-approved templates to send notifications to users who have their wallet cards importantonly authorized partners can use the notification feature the notification tab is not displayed to unauthorized partners register notification template partners can create a template for sending notifications on each of their wallet cards either through the partner portal or by using a separate api type partners can only choose the merchant push type message type you can choose a message type from marketing or others rejected comment if the merchant push notification is rejected after request approval, you can modify the message template the administrator registers the reason for rejection when rejecting the merchant push notification it is sent to the partner by email from the system, including the reason for rejection partners can request for approval again by checking the reason for rejection and modifying the message template approved date displays the date and time when the push message is approved by the administrator message template you can create the contents of the push, and it is also possible to put the available variables in '{{}}' after configuring the content, click harmfulness verification to verify whether there is a harmful expression in the content the verified result is displayed as pass or fail, and if it is fail, it shows the filtered harmful expression together even if the verified result is fail, an approval request can be made, but it can be rejected by the administrator if a different language is added to the default language in general information, the message template must also be entered for each added language request approval button after completing the message template, click this button to send an e-mail requesting approval to the administrator notification with a reference id this api allows partners to push notification to users who have their own wallet cards this request must include a reference id to receive the message and a template id this template id is issued when a partner creates a template through the portal only templates pre-approved by the administrator can be used this reference id is a unique identifier generated by the partner during add to wallet process [request] type value description method post url /{cc2}/wltex/cards/{card id}/notifications/{template id}/send header authorizationstring 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-idstring 32 required partner id x-request-idstring 32 required request identifier randomly generated uuid string path parameters cc2string 2 required country code cc2 from send card state card idstring 32 required wallet card identifier granted from partners portal template idstring 32 required approved notification template identifier from partners portal payload ndatastring required notification object json * this field needs to be encrypted * refer to security for more details * the value of "cty" must be set to "notification" notification object refidsarray of string 100 required unique content identifier defined by the content provider data object required name-value pair for use in notification template [example] post /wltex/cards/12584806754/notifications/12353465344/send /*[headers]*/ authorization bearer eyjjdhkioijbvvriiiwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 /*[payload]*/ { “ndata” “eyjjdhkioijbvvriiiwidmvyi…” } /*[notification object]*/ { "refids" [ "ref-20230304-0003", "ref-20230304-0004" ], "data" { "name" "logan", "place" "samsung wallet" } } [response] type value description http status 200 ok payload n/a [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 the server encountered an unexpected condition that prevented it from fulfilling the request
Develop Samsung Wallet
dochelpful resources data structure and format additional information additional information to be delivered to customers can be defined in the following format be careful of the content string length if an attribute does not allow long content, it is not displayed on the device json format key type requirement description count integer required size of information info[] object arrays required container of information info[] title string required title * need either content or chart info[] content[] string arrays optional content text info[] chart object optional chart data info[] chart headers[] string arrays optional header of chart info[] chart body[] array required body of chart info[] chart metadata[] string arrays optional metadata of chart * units or additional information of chart example * extra information for a boarding pass { "count" 3, "info" [ { "title" "baggage allowance", "content" [ "15 kg" ] }, { "title" "boarding priority", "content" [ "yes" ] }, { "title" "seat class", "content" [ "economy plus" ] } ] } * an example case of long content being allowed movie ticket policy { "count" 2, "info" [ { "title" "refunds and exchanges", "content" [ "refunds and exchanges of movie ticket s are available in certain limited circumstances ", "movie tickets purchased through the services include a non-refundable convenience fee before purchasing your movie ticket s we urge you to confirm the title, time, location and quantity of tickets for the movie you wish to see " ] }, { "title" "changes to ticket policy", "content" [ "from time to time, we may revise this ticket policy you can determine when this ticket policy was last revised by referring to the top of this page any changes to this ticket policy will become effective upon posting of the revised ticket policy on the internet, accessible through the services " ] } ] } * example usage of charts { "count" 1, "info" [{ "title" "paygo price guide for usage", "chart" { "headers" ["grade", "round", "one-way"], "body" [ ["platinum", "$25", "$10"], ["gold", "$30", "$15"], ["silver", "$40", "$20"] ], "metadata" "unit /h" } }] } paygo price guide for usage members grade round one-way platinum $25 $10 gold $30 $15 silver $40 $20 unit /h the above example may differ from what is actually displayed links linkable data which provides additional information in the following format json format key type requirement description count integer required size of links info[] array of objects required container of links info[] link string required link url info[] type string required view type that will run the link* allowed values web, app, browser info[] text string optional text of the link example { "count" 1, "info" [{ "link" "https //samsung external info link", "type" "web", "text" "see more information" }] } classification classification defines different kinds of people who can use the cards json format key type requirement description person[] array of object required container of person list who can use the card person[] category string required category name person[] count string required number of person example * 3 persons with a ticket { "person" [ { "category" "adult", "count" 2 }, { "category" "child", "count" 1 } ] } * 1 person with a ticket { "person" [ { "category" "adult", "count" 1 } ] } transactions transactions to be delivered to customers can be defined in the following format be careful of the content string length if an attribute does not allow long content, it will not be displayed on the device json format key type requirement description [] date string required transaction date [] amount string optional amount value [] description string optional description example * an example for payasyougo-evcharge-transactions [ { "date" "2023-09-10 12 00 00", "amount" "50,000 won", "description" "suwon station branch" }, { "date" "2023-09-20 18 00 00", "amount" "70,000 won", "description" "gangnam central branch" } ] locations locations refer to place information that denotes where a card can be used using this information, samsung wallet can show a map, place name, and address additionally, location information can be used to provide location-based services lbs location information can be represented by a json array and up to 10 locations can be specified notice map services are only available in certain countries json format key type requirement description [] lat double optional latitude [] lng double optional longitude [] address string required string containing the full address [] name string required branch name example * location information for the entrance to oracle park [ { "lat" 37 779337, "lng" -122 388755, "address" "24 willie mays plaza, san francisco, ca 94107", "name" "willie mays plaza" }, { "lat" 37 77814, "lng" -122 390836, "address" "king st, san francisco, ca 94107", "name" "king st" } ] card art guide loyalty description type bgimage + bgcolor bgimage only description display the bgimage and the bgcolor in a predefined ratio display bgimage fully description
Develop Samsung Wallet
docapi guidelines app2app sdk integration specs description & use rp sdk is an app2app sdk for samsung wallet driver's license service online scenarios this sdk provides an implementation for direct communication between the samsung wallet and partner applications build the settings rpsdk requires additional dependencies with dependencies { implementation "rp-sdk-1 0-release aar" implementation "androidx core core-ktx 1 3 2" implementation "androidx lifecycle lifecycle-runtime-ktx 2 7 0" implementation "androidx lifecycle lifecycle-livedata-core-ktx 2 7 0" implementation "io reactivex rxjava2 rxjava 2 2 21" implementation "io reactivex rxjava2 rxkotlin 2 4 0" implementation "io reactivex rxjava2 rxandroid 2 1 1" implementation "com squareup okhttp3 okhttp 4 11 0" implementation "com google code gson gson 2 10 1" implementation "org bouncycastle bcprov-jdk15to18 1 66" implementation "com nimbusds nimbus-jose-jwt 9 37 3" } androidmanifest xml <manifest xmlns android="http //schemas android com/apk/res/android"> <uses-permission android name="android permission internet" /> <queries> <package android name="com samsung android spay" /> </queries> </manifest> r8 / proguard the specific rules are already bundled into the aar which can be interpreted by r8 automatically sdk method app2app sdk supports one method request signature & parameters of the request method fun request targetpackagename string, requestid string, applink string, onresponselistener onresponselistener? = null parameter name description targetpackagename the pakcage name to connect to requestid a random string to identify each request applink the applink built by samsung mcs server guide onresponselistener a listener to receive each events or requests [sample code] binding button setonclicklistener { rpclientapis request "com samsung android spay", uuid randomuuid tostring , applink, object rpclientapis onresponselistener { override fun ongetmdocrequestdata deviceengagementbytes bytearray bytearray? { log i tag, "ongetmdocrequestdata $deviceengagementbytes " /** * 1 prepare mdoc request data iso-18013-5 * 2 build sessionestablishmentbytes iso-18013-5 * 3 encrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations **/ return "encryptedsessionestablishmentbytes" } override fun onmdocresponse encryptedresponse bytearray { log i tag, "onmdocresponse $encryptedresponse " /** * 1 decrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations * 2 cbor decode it **/ } override fun onmdocresponsefailed exception exception { log i tag, "onmdocresponsefailed $exception " } } } error code explanation the below exceptions might occur through the onmdocresponsefailed callback exceptions name description rpcommunicationexception this error occurs when the data requested by the listener is incorrect rpconnectionfailedexception this occurs when the app 2 app communication between apps is not working this usually occurs when the target package name is written incorrectly web2app api integration specs the api specifications that need to be implemented by the rp partner are described below called by samsung to the rp partner send key send the wallet application key info and return the data field types requested to the client for authentication of the mdl [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/key headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details path parameters cardidstring 32 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 refid string 32 required unique content identifier defined by the content provider query parameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, and it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "relyingparty", "subtype" "others", "designtype" "us-01" }} [example] post {partner server url}/rp/v1 0/{cardid}/{refid}/key content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyymdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtfoddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxscxltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdbyny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nuedrvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmjnq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0zvenbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzddevfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnplekwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgfmodhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvxvketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nxm46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvuqncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuqhtjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbwycvx8wa” } [response] type value description http status code 200 ok payload data string 3000 required jwt data encrypted with the data field types requested to the client for authentication of the mdl [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request send authentication data the data is encrypted according to the requested data and then transmitted along with the data card information [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/auth headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details pathparameters cardid string 32 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 refid string 32 required unique content identifier defined by the content provider queryparameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "idcard","subtype" "drivers","designtype" "us-01" }} [example] post {partner server url}/rp/v1 0/{cardid}/{refid}/auth content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyymdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtfoddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxscxltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdbyny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nuedrvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmjnq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0zvenbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzddevfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnplekwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgfmodhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvxvketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nxm46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvuqncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuqhtjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbwycvx8wa” } [response] type value description http status code 200 ok400 bad request [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to somethingthat is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request code explanation based on the sample code jwt jws + jwe decryption between the wallet backed server and partner server 1 verify by generateing a jws using the body data // generate jws by the body data private static signedjwt parsejwt final string data { try { return signedjwt parse data ; } catch parseexception e { log error "parserjwt error class {}, error message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "parserjwt error" ; } } // verify jws using samsung public key public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } 2 decrypt the jwe using the jws jweobject parse signedjwt getpayload tostring public static string getdecryptedpayloadfrom final key privatekey, final jweobject data { try { data decrypt new rsadecrypter privatekey privatekey ; // decryption jwe using partner private key return data getpayload tostring ; } catch joseexception e { log error "joseexception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "getdecryptedpayloadfrom error" ; } } 3 convert to the format send by the client public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } generate mdocestablishment 1 generate rsa key per refid public class transactioncontext { private final keypair keypair; // rsa key private final byte[] clientengagement; // body data received through key api, base64url decoded value @equalsandhashcode exclude private int encryptmessagecounter = 0; // count value when encrypted @equalsandhashcode exclude private int decryptmessagecounter = 0; // count value when decrypted } private cache<string, transactioncontext> contextcache; // rsa key management per refid with memory cache // generate and store rsa key per refid only once upon first request public transactioncontext settransactioncontext final string key, final string base64encodedclientengagement { log info "base64encodedclientpublickey {}", base64encodedclientengagement ; this contextcache put key, new transactioncontext keyutils generatekeypair , base64utils decode base64encodedclientengagement getbytes ; return this gettransactioncontextby key ; } // part of retrieving ras key based on refid public transactioncontext gettransactioncontextby final string key { return optional ofnullable this contextcache getifpresent key orelsethrow -> { log info "{} is empty", key ; return new customexception httpstatus bad_request, "no key matching the refid" ; } ; } 2 create request field values @override public mono<list<string>> createrequest final partnerinputdto inputdto { final string mockdata = "{ \"doctype\" \"org iso 18013 5 1 mdl\", \"namespaces\" { \"org iso 18013 5 1\" { \"sex\" false, \"portrait\" false, \"given_name\" false, \"issue_date\" false, \"expiry_date\" false, \"family_name\" false, \"document_number\" false, \"issuing_authority\" false }, \"org iso 18013 5 1 aamva\" { \"dhs_compliance\" false, \"edl_credential\" false } } }"; return mono just collections singletonlist mockdata ; } 3 generate establishment @allargsconstructor public class establishment { private final transactioncontext context; // info of client public key , partner private key, public key private final list<string> strreqs; // data field information required for authentication to the client private final keyring keyring; // rsa key information for jwt jws + jwe encryption and decryption between wallet backed server and partner server } protected cborobject generate { final cborobject sessionestablishment = cborobject newmap ; sessionestablishment set e_reader_key, cborobject fromobjectandtag keyutils getereaderkey context , tag_size ; // generate onekey by public key in transactioncontext sessionestablishment set data, cborobject fromobject cipherutils encrypt context, generaterequestformat getrequestcborobjectsfrom strreqs ; // add request data field information for authentication return sessionestablishment; } generate the response value jwt jws + jwe 1 generate establishment with jwe public static string encryptedstringjwe final key publickey, final string data { // please enter samsung public key and establishment data final jweobject jwe = new jweobject new jweheader builder jwealgorithm rsa_oaep_256, encryptionmethod a128gcm build , new payload data ; try { jwe encrypt new rsaencrypter rsapublickey publickey ; return jwe serialize ; } catch joseexception e { log error "encryptedstringjwe exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "encryptedstringjwe error" ; } } 2 generate jws by jwe public static string generatesignedstringjws final key privatekey, final key publickey, final string payload { // enter your partner’s public key, private key, and jwe data try { final jwsobject jwsobj = new jwsobject getdefaultjwsheader , new payload payload ; jwssigner signer = new rsassasigner new rsakey builder rsapublickey publickey privatekey rsaprivatekey privatekey build ; jwsobj sign signer ; return jwsobj serialize ; } catch joseexception e { log error "encryptedstringjws exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "generatesignedstringjws error" ; } } 3 generate jwt jws + jwe public partneroutputdto topartneroutputdto { final cborobject generate = this generate ; final string establishment = base64 geturlencoder encodetostring generate encodetobytes ; final string strjwe = jwtutils encryptedstringjwe keyring gettargetpublickey , establishment ; final jwsheader jwsheader = jwtutils getdefaultjwsheader keyring getversion , keyring getcertificateid , "partnerid" ; return new partneroutputdto jwtutils generatesignedstringjws jwsheader, keyring getsourceprivatekey , keyring getsourcepublickey ,strjwe ; } authentication processing for values in data fields requested for authentication 1 retrieve transactioncontext value stored in cache using refid value @override public mono<transactioncontext> getcontext final partnerinputdto inputdto { return mono just this transactioncontextmanager gettransactioncontextby inputdto getrefid ; } 2 processes the decryption process of the request body data like jwt jws + jwe decryption between wallet backed server and partner server 3 generate mdocresponse public class mdocresponse { private final transactioncontext context; // managed tranactioncontext by refid private final byte[] data; // base64url decoded data after decrypting jwt jws + jwe data public mdocresponse final transactioncontext context, final string inputdto { this context = context; this data = base64utils decode inputdto getbytes standardcharsets utf_8 ; } } 4 get the field values requested for authentication from the data in mdocresponse public string getdata { // sessiondata = { // ? "data" bstr ; encrypted mdoc response or mdoc request // ? "status" uint ; status code // } final cborobject response = cborobject decodefrombytes data ; checktype response, cbortype map ; final cborobject data = response get data ; checktype data, cbortype bytestring ; return cborobject decodefrombytes isencryptedmode ? cipherutils decrypt this context, data getbytestring data getbytestring tojsonstring ; } 5 create a session value using the transactioncontext value managed by refid and then decrypt it private static byte[] processcipher final ciphermode ciphermode, final transactioncontext context, final byte[] bytes { // ciphermode encrypt or decrypt, bytes data passed by the client try { cipher cipher = cipher getinstance "aes/gcm/nopadding" ; final int counter = ciphermode encrypt == ciphermode ? context getencryptmessagecounter context getdecryptmessagecounter ; gcmparameterspec parameterspec = new gcmparameterspec 128, getsessionkeyiv ciphermode identifier, counter ; cipher init ciphermode ciphermode , getsecretkeyspec context, ciphermode info , parameterspec ; return cipher dofinal bytes ; } catch invalidalgorithmparameterexception | nosuchpaddingexception | illegalblocksizeexception | nosuchalgorithmexception | badpaddingexception | invalidkeyexception e { log error "error type {}, message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "processcipher error" ; } } 6 examining data received from the client @override public mono<void> authentication final string response { log info "response info {}", response ; return mono empty ; }
Develop Samsung Pay
docsample applications sample apps, use cases, and ux strategies are included here to aid you in understanding the sdk and implementing it in your application sample source code and apks can be downloaded from download section sample merchant app included with the samsung pay sdk to demonstrate its features, the sample merchant app shows you how to implement the payment sheet’s dynamic controls to leverage additional customer order and payment data and/or create a more custom ui look and feel the following payment sheet controls are available addresscontrol plaintextcontrol amountboxcontrol spinnercontrol controls are applied to suit a particular purpose or need for example, displaying a promotion notice in the payment sheet using the plaintextcontrol applying an addresscontrol this control is used to display the billing or shipping address on the payment sheet based on samsung pay’s my info user profile or addresses provided by your merchant app during the transaction request when creating the control, controlid and sheetitemtype are needed to distinguish the billing address from the shipping address otherwise, your merchant app sets the following properties address title – displays a merchant-defined title on the payment sheet if empty, the default title such as “billing address” is displayed address – provides various methods to retrieve address details the merchant app can retrieve the phone number using the 'getphonenumber' method of 'customsheetpaymentinfo' address starting from api level 1 5, the addressee’s email address has also been added retrieve the email address using 'getemail' you can also set a display option for the shipping address with 'setdisplayoption' for more information, see the samsung pay sdk-api reference javadoc and the sample code included with the samsung pay sdk sheetupdatedlistener – used to capture the response from the samsung wallet app; merchant app must deliver to the samsung wallet app an amountboxcontrol to display payment information on a custom payment sheet when the onresult callback is called, the updatesheet method must also be called to update the current payment sheet errorcode – used for containing error codes directly related to the address the workflows for billingaddresscontrol and shippingaddresscontrol are shown below the following sample code demonstrates use of addresscontrol on the payment sheet fun makebillingaddresscontrol addresscontrol { val billingaddresscontrol = if !iszipcodeonly { // for billing address addresscontrol billing_address_id, sheetitemtype billing_address billingaddresscontrol addresstitle = "billing address" } else { /* * for billing address with zip code only * since api level 2 19, sheetitemtype zip_only_address * for us country only */ addresscontrol billing_address_id, sheetitemtype zip_only_address billingaddresscontrol addresstitle = "zip code" } //this callback is received when controls are updated billingaddresscontrol sheetupdatedlistener = sheetupdatedlistener return billingaddresscontrol } //listener for billing or zip code only billing address fun sheetupdatedlistener sheetupdatedlistener { return sheetupdatedlistener { updatedcontrolid string, customsheet customsheet -> log d tag, "onresult billingaddresscontrol updatedcontrolid $updatedcontrolid" val addresscontrol = customsheet getsheetcontrol updatedcontrolid as addresscontrol val billaddress = addresscontrol address //validate only zipcode or billing address and set errorcode if needed if addresscontrol sheetitem sheetitemtype == sheetitemtype zip_only_address { val errorcode int = validatezipcodebillingaddress billaddress log d tag, "onresult updatesheetbilling errorcode $errorcode" addresscontrol errorcode = errorcode customsheet updatecontrol addresscontrol } else { val errorcode = validatebillingaddress billaddress log d tag, "onresult updatesheetbilling errorcode $errorcode" addresscontrol errorcode = errorcode customsheet updatecontrol addresscontrol } // update transaction values val amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol amountboxcontrol updatevalue product_item_id, 1000 0 amountboxcontrol updatevalue product_tax_id, 50 0 amountboxcontrol updatevalue product_shipping_id, 10 0 amountboxcontrol updatevalue product_fuel_id, 0 0, "pending" amountboxcontrol setamounttotal 1060 0, amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol try { // call updatesheet for the full amountboxcontrol; mandatory paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } } // for shipping address fun makeshippingaddresscontrol addresscontrol { val shippingaddresscontrol = addresscontrol shipping_address_id, sheetitemtype shipping_address shippingaddresscontrol addresstitle = "shipping address" val shippingaddress = customsheetpaymentinfo address builde setaddressee "name" setaddressline1 "addline1" setaddressline2 "addline2" setcity "city" setstate "state" setcountrycode "usa" setpostalcode "zip" setphonenumber "555-123-1234" setemail "user@samsung com" build shippingaddresscontrol address = shippingaddress /* * set address display option on custom payment sheet * if displayoption is not set, then default addresscontrol is displayed on custom payment sheet * the possible values are combination of below constants * {display_option_addressee} * {display_option_address} * {display_option_phone_number} * {display_option_email} */ var displayoption_val = addressconstants display_option_addressee // addressee is mandatory displayoption_val += addressconstants display_option_address displayoption_val += addressconstants display_option_phone_number displayoption_val += addressconstants display_option_email shippingaddresscontrol displayoption = displayoption_val return shippingaddresscontrol } here’s how these controls display on a custom payment sheet applying a plaintextcontrol this control is used for displaying a title with a two lines of text or a single line of text without a title on the payment sheet when allocating this control, a controlid is needed the merchant app sets both the title, as applicable, and the text diagrammed below is the flow between your merchant app and samsung pay the merchant app code invoking this class would look something like the following fun makeplaintextcontrol plaintextcontrol { val plaintextcontrol = plaintextcontrol "exampleplaintextcontrolid" plaintextcontrol settext "plain text [example]", "this is example of plaintextcontrol" return plaintextcontrol } and this is how it displays on the custom payment sheet applying an amountboxcontrol amountboxcontrol is used for displaying purchase amount information on the payment sheet it requires a controlid and a currencycode, and consists of item s and amounttotal, defined as follows and diagrammed on the next page item – consists of id, title, price, and extraprice if there is an extraprice in amountboxcontrol, its text is displayed on the payment sheet even though there is an actual numerical price value if there is no extraprice, then currencycode with the price value is displayed amounttotal – consists of price and displayoption the displayoption allows predefined strings only your merchant app can set the text to “estimated amount”, “amount pending”, “pending”, “free”, and so forth the ui format for the string is different for each option notethe setamounttotal api may accept strings that are not predefined as an argument, but itgenerates an invalid parameter condition or returns an error code in such cases for details, see the javadoc samsung pay sdk-api reference, available in the documentation folder of your downloaded sdk package here’s a coding example to demonstrate the use of amountboxcontrol in a payment sheet fun makeamountcontrol amountboxcontrol { val amountboxcontrol = amountboxcontrol amount_control_id, "usd" amountboxcontrol additem product_item_id, "item", 1000 0, "" amountboxcontrol additem product_tax_id, "tax", 50 0, "" amountboxcontrol additem product_shipping_id, "shipping", 10 0, "" amountboxcontrol setamounttotal 1060 0, amountconstants format_total_price_only amountboxcontrol additem 3, product_fuel_id, "fuel", 0 0, "pending" return amountboxcontrol } the merchant app can also add new items using the 'additem' method of 'amountcontrolbox' during callback importantyour merchant app needs to call the updatevalue item_id method of amountboxcontrol to update each amount item then call customsheet updatecontrol to make the changes take effect in customsheet eventually, paymentmanager updatesheet 'customsheet' must be called to let samsung pay know that no further action is pending in the merchant app when the custom sheet is updated, the merchant can add new items to amountboxcontrol for example, if the user selects a specific card in the payment sheet which the merchant offers, a discount item can be added via the updatesheet // example for adding new item while updating values val amount = sheet getsheetcontroll "id_amount" amount updatevalue "itemid", 900 0 amount updatevalue "taxid", 50 0 amount updatevalue "shippingid", 10 0 amount updatevalue "fuelid", 0 0 // add “discount” item amount additem 4, "discountid", "discount", -60 0, "" amount setamounttotal 1000 0, amountconstants format_total_price_only sheet updatecontrol amount // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet sheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } applying the spinnercontrol this control is used for displaying spinner options on a payment sheet when creating the control, controlid, title, and sheetitemtype are needed to distinguish between the types of spinner to be displayed your merchant app sets the following properties with spinnercontrol title – the merchant-defined spinner title to appear the payment sheet sheetitemtype – provides various types of spinner a shipping_method_spinner and an installment_spinner are the two types of spinner available as of api level 1 6 noteshipping_method_spinner can be used when the shipping address comes from the samsung wallet app; i e , when the customsheetpaymentinfo addressinpaymentsheet option is set to need_billing_and_shipping or need_ shipping_spay when the shipping address is provided by the merchant app send_shipping or need_billing_ send_shipping , it is not changeable in the payment sheet the shipping fee if applied must be pre-calculated on the merchant app side here’s an example of constructing a spinnercontrol within your merchant app // construct spinnercontrol for shipping method val spinnercontrol = spinnercontrol shippingmethod_spinner_id, "shipping method ", sheetitemtype shipping_method_spinner // let the user can select one shipping method option on the payment sheet spinnercontrol additem "shipping_method_1", getstring android r string standard_shipping_free spinnercontrol additem "shipping_method_2", getstring android r string twoday_shipping spinnercontrol additem "shipping_method_3", getstring android r string oneday_shipping spinnercontrol selecteditemid = "shipping_method_1" // set default option // listen for sheetcontrol events spinnercontrol setsheetupdatedlistener sheetupdatedlistener { updatedcontrolid, customsheet -> val amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol val spinnercontrol = customsheet getsheetcontrol updatedcontrolid as spinnercontrol when spinnercontrol selecteditemid { "shipping_method_1" -> amountboxcontrol updatevalue product_shipping_id, 10 0 "shipping_method_2" -> amountboxcontrol updatevalue product_shipping_id, 10 + 0 1 "shipping_method_3" -> amountboxcontrol updatevalue product_shipping_id, 10 + 0 2 else -> amountboxcontrol updatevalue product_shipping_id, 10 0 } amountboxcontrol setamounttotal 1000 + amountboxcontrol getvalue product_shipping_id , amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } // construct spinnercontrol for installment plan val spinnercontrol = spinnercontrol installment_spinner_id, "installment", sheetitemtype installment_spinner spinnercontrol additem "installment_1", "1 month without interest" spinnercontrol additem "installment_2", "2 months with 2% monthly interest" spinnercontrol additem "installment_3", "3 months with 2 2% monthly interest" spinnercontrol selecteditemid = "installment_1" // set default option // listen for sheetcontrol events spinnercontrol setsheetupdatedlistener sheetupdatedlistener { updatedcontrolid, customsheet -> val amountboxcontrol amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol val spinnercontrol = customsheet getsheetcontrol updatedcontrolid as spinnercontrol val totalinterest = 0 0 when spinnercontrol selecteditemid { "installment1" -> amountboxcontrol updatevalue product_total_interest_id, totalinterest "installment2" -> // calculate total interest again and updatevalue amountboxcontrol updatevalue product_total_interest_id, totalinterest "installment3" -> // calculate total interest again and updatevalue amountboxcontrol updatevalue product_total_interest_id, totalinterest else -> amountboxcontrol updatevalue product_total_interest_id, totalinterest } amountboxcontrol setamounttotal 1000 + amountboxcontrol getvalue product_total_interest_id , amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } update sheet with custom error message to display a custom error message on the payment sheet, use updatesheet with customerrormessage fun updatesheet sheet customsheet, errorcode int, customerrormessage string this api method is an extended version of the existing updatesheet sheet method which gives the merchant the ability to display a custom error message in the payment sheet’s authentication area it can be used to inform the user of any foreseen error scenarios encountered // update sheet with custom_messsage error code paymentmanager updatesheet customsheet, paymentmanager custom_message,"phone number entered is not valid please change your phone number " sample issuer app the samsung pay sdk also provides a sample issuer app to showcase samsung pay sdk features issuer app can add card to samsung wallet by selecting specific token service provider tsp from the dropdown menu to add cobadge card you need to select primary and secondary token service providers tsp from the dropdown menus for more information, refer to the samsung pay sdk api reference and sample code
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.