Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
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 type sub-type giftcard others others wallet card data fields attributes type value description payload object cardtemplateobject required wallet card template object cardtemplate prtnrid string 32 required partner id cardtemplate templaterefid string 19 required partner template id cardtemplate title string 32 required wallet card name cardtemplate countrycode string 2 conditional the main headquarters location * required when creating a template cardtemplate cardtype string 100 conditional this value is set to “giftcard” * required when creating a template cardtemplate subtype string 100 conditional this value is set to “others” * required when creating a template cardtemplate prtnrapppckgnamestring 128 optional the application package name cardtemplate applogoimg string 200 optional the banner logo image url cardtemplate nonetworksupportyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureyn string 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeyn string 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureyn string 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate statestring 15 optional wallet card's state* default 'draft' cardtemplate testingmodeoffstring 1 optional testmode off either 'y' or 'n'* default ‘n’available only when updating templates cardtemplate descstring 500 optional description { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551315", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "gift", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } }
Develop Samsung Pay
doc3 3 web checkout sdk 3 3 1 overview samsung pay web checkout enables seamless, secure payments on your website using cards stored in the samsung wallet app this javascript-based sdk makes it easy to integrate samsung pay into your desktop or mobile web checkout experience key features cross-device supportusers can complete purchases on both desktop and mobile browsers samsung wallet integrationpayments are authorized using cards saved in the samsung wallet mobile app secure credential transmissionpayment credentials are securely generated on the mobile device and transmitted to your website multiple authentication optionsusers can bind their device by either entering their samsung account email scanning a qr code displayed on your checkout page user scenario with the service flow the following figures describe the user scenario for making a purchase through samsung pay web checkout payment initiation & device binding the user selects samsung pay as the payment method at checkout a web checkout ui launches, prompting the user to link their device by either enter samsung account email scan a qr code using their mobile device a push notification is sent to their samsung wallet app for mobile devices the user selects samsung pay as the payment method at checkout a payment request pop-up is displayed and prompts the user to select the “pay” button the samsung wallet app automatically opens on the current device user confirmation on mobile device the user taps the notification on their device the samsung wallet app opens a payment sheet showing order details the user selects a payment card and authorizes the purchase payment completion a "verified" screen is shown in the browser as the transaction is confirmed your website receives a secure payment credential from samsung pay you forward this credential to your payment processor to complete the purchase 3 3 2 web checkout integration samsung pay web checkout enables seamless online payments using samsung wallet on supported mobile devices let’s us look how to integrate the web checkout sdk into your website and process secure, tokenized transactions prerequisites before integrating samsung pay web checkout, ensure the following samsung pay merchant id you must complete the partner onboarding process to obtain a valid merchant id tokenization support your acquirer and issuer must support tokenized in-app transactions per card network standards web checkout integration steps to integrate the samsung pay web checkout solution to your website include the samsung pay sdk add the sdk to your website's frontend <script src="https //img mpay samsung com/gsmpi/sdk/samsungpay_web_sdk js"></script> configure payment methods define the supported card brands, protocol, api version, and your service merchant id const paymentmethods = { "version" "2", "serviceid" "dcc1cbb25d6a470bb42926", "protocol" "protocol_3ds", "allowedbrands" ["visa","mastercard"] } initialize the samsung pay client set the environment "stage" – testing with device "stage_without_apk" – testing without device simulated "production" – live environment const samsungpayclient = new samsungpay paymentclient {environment "stage"} ; note if your project has a content-security-policy csp applied, please ensure that you add a nonce to the css to maintain compliance this can be done by updating your sdk configuration as follows const samsungpayclient = new samsungpay paymentclient {environment "stage", nonce "your-nonce"} ; check availability verify samsung pay availability in the user’s browser/device samsungpayclient isreadytopay paymentmethods then function response { if response result { // add a payment button } } catch function err { console error err ; } ; add samsung pay button use the official samsung pay button asset and adhere to branding guidelines <div id="samsungpay-container"> <button id="samsung-pay-btn"> <img src="/your/path /samsung-pay-button png" alt="samsung pay" style="{follow the samsung's official branding guideline}" /> </button> </div> note download the official samsung pay button image and branding guideline from download page and use it directly in your html as shown here download attach click handler add your event handler to the button document getelementbyid "samsung-pay-btn" addeventlistener "click", onsamsungpaybuttonclicked ; create the transaction detail define transaction metadata such as order info, merchant details, and total amount const transactiondetail = { "ordernumber" "dstrf345789dsgty", "merchant" { "name" "virtual shop", "url" "virtualshop com", "id" "xn7qfnd", "countrycode" "us" }, "amount" { "option" "format_total_estimated_amount", "currency" "usd", "total" 300 } } launch payment flow trigger the web checkout interface when the user clicks the payment button when the onclick event is triggered, your event handler must call the loadpaymentsheet method, which initiates the web checkout ui flow when the user confirms the payment from their mobile device, you receive the paymentcredential object generated by the device note extract the payment credential information from the 3ds data key within the paymentcredential object and process it through your payment provider inform the samsung server of the payment result using the notify method within the paymentresult object samsungpayclient loadpaymentsheet paymentmethods, transactiondetail then paymentcredential => { // forward paymentcredential to your payment provider const paymentresult = { const paymentresult = { "status" "charged", "provider" "pg name" } samsungpayclient notify paymentresult ; } catch error => { payment credential sample the paymentcredential is the resulting output of the loadpaymentsheet method sample paymentcredential json output using jwe-only { "method" "3ds", "recurring_payment" false, "card_brand" "visa", "card_last4digits" "8226", "3ds" { "type" "s", "version" "100", "data" "eyjhbgcioijsu0exxzuilcjrawqioiixzhlsbkfvrvjttk53z0j0mmvzcevwu1poswrzzghqbvi3bzhqcdvkagvbpsisinr5cci6ikppu0uilcjjagfubmvsu2vjdxjpdhldb250zxh0ijoiulnbx1blssisimvuyyi6ikexmjhhq00ifq jykxn2h9pk1uj-4knpuij1r49ykw7-3aelznhadzsztclvjlhoyjomujfl1h21yq_5rmdwz9lj6o67j8m6kn_1dnkvnqaugi203ol5tegf-j15n_pcinj1nycfyivohazidbg9fq2nzts_muu9cvykiz-ifsuz6rfl9aiuoakjpctzpn8lwlddzxzme3j86sd45i-ahxwbujfvy9d2zrt1sddgoxgorjrzy3o5s29pybkaytjmcpc_jicu-sdsx3s1snm_cvhaqiccoxyidih6hfwo35fsswysvxu8yfpgtwbcdai9ujkptvr7npnp1ch85ja3dvw3mi87v-pwiqmw hdzesnbxu0d0t68e pcv1csibw7jgtlgfoovmebm-wggpw9rhonbkdb_qwwfl_cuf7_0nj_knuozq4pudk0_vzktbhi3kv0gt2ybmqs6zfpnxd3cdpgk_lyio8z8xciasoz5vltamjg7n5maadxxpvqwtcpk_tbksve2ke8w7r3u4kapfjl2ene06j3e4rkae367x8_aoxy2l3lhoeqzl4lfsntfs71xfc-s9h5-bgi2clkba-9hlrtpbxtumwa830rwywm7m fs5-tfbxq73l7icrrwkbla" } } the decrypted output will be similar to this { "amount" "100", "currency_code" "usd", "utc" "1719388643614", "eci_indicator" "5", "tokenpan" "5185731679991253", "tokenpanexpiration" "0127", "cryptogram" "akkeavcvwhfmammud6r3aoacfa==" } note for information about the content of the paymentmethods, transactiondetail, and paymentcredential data structures, see the api reference 3 3 3 decrypting payment credentials for security, samsung pay encrypts the payment credential using json web encryption jwe you must decrypt this payload to extract the payment token and process the transaction to decrypt the payment credentials, generate a der file from your private key $ openssl pkcs8 -topk8 -in merchant key -outform der -nocrypt -out rsapriv der decrypt the jwe encrypted data sample implementation in java import java nio file files; import java nio file paths; import java security keyfactory; import java security interfaces rsaprivatekey; import java security spec pkcs8encodedkeyspec; import java util base64; import javax crypto cipher; import javax crypto spec gcmparameterspec; import javax crypto spec secretkeyspec; import com fasterxml jackson databind jsonnode; import com fasterxml jackson databind objectmapper; public class developerportalsample { public static void main string[] args throws exception { // example jwe string replace with your actual jwe and private key path string encryptedtext = {{encryptedpayload}}; string privatekeypath = " /rsapriv der"; string private_key = base64 getencoder encodetostring files readallbytes paths get privatekeypath ; string result = decryptjwe encryptedtext, private_key ; system out println result ; } public static string decryptjwe string encryptedtext, string privatekeytext throws exception { // split jwe parts by ' ' string delims = "[ ]"; string[] tokens = encryptedtext split delims ; if tokens length < 5 { throw new illegalargumentexception "invalid jwe format" ; } // decode and parse jwe header byte[] headerbytes = base64 geturldecoder decode tokens[0] ; string headerjson = new string headerbytes ; objectmapper mapper = new objectmapper ; jsonnode header = mapper readtree headerjson ; // extract algorithm information from header string alg = header has "alg" ? header get "alg" astext "rsa1_5"; string enc = header has "enc" ? header get "enc" astext "a128gcm"; // convert private key byte[] privatekeybytes = base64 getdecoder decode privatekeytext ; pkcs8encodedkeyspec privatekeyspec = new pkcs8encodedkeyspec privatekeybytes ; keyfactory keyfactory = keyfactory getinstance "rsa" ; rsaprivatekey privatekey = rsaprivatekey keyfactory generateprivate privatekeyspec ; // decode encrypted key, iv, ciphertext, and authentication tag byte[] enckey = base64 geturldecoder decode tokens[1] ; byte[] iv = base64 geturldecoder decode tokens[2] ; byte[] ciphertext = base64 geturldecoder decode tokens[3] ; byte[] tag = base64 geturldecoder decode tokens[4] ; // create cipher instance based on key management algorithm string keymanagementalgorithm; boolean useaad = false; if "rsa-oaep" equals alg { keymanagementalgorithm = "rsa/ecb/oaeppadding"; // at samsung, oaep uses aad additional authenticated data useaad = true; } else if "rsa1_5" equals alg { keymanagementalgorithm = "rsa/ecb/pkcs1padding"; // while rsa1_5 does not use aad useaad = false; } else { throw new illegalargumentexception "unsupported key management algorithm " + alg ; } // decrypt the cek content encryption key cipher decryptcipher = cipher getinstance keymanagementalgorithm ; decryptcipher init cipher decrypt_mode, privatekey ; byte[] plainenckey = decryptcipher dofinal enckey ; // create cipher instance based on content encryption algorithm string contentencryptionalgorithm; int gcmtaglength; if "a128gcm" equals enc || "a256gcm" equals enc { contentencryptionalgorithm = "aes/gcm/nopadding"; gcmtaglength = 128; } else { throw new illegalargumentexception "unsupported content encryption algorithm " + enc ; } // decrypt the content cipher contentcipher = cipher getinstance contentencryptionalgorithm ; gcmparameterspec gcmparameterspec = new gcmparameterspec gcmtaglength, iv ; secretkeyspec keyspec = new secretkeyspec plainenckey, "aes" ; contentcipher init cipher decrypt_mode, keyspec, gcmparameterspec ; // aad handling use base64url-encoded header bytes as aad if useaad { byte[] encodedheader = base64 geturlencoder withoutpadding encode headerbytes ; contentcipher updateaad encodedheader ; } // concatenate ciphertext and tag, then pass to dofinal byte[] cipherdata = new byte[ciphertext length + tag length]; system arraycopy ciphertext, 0, cipherdata, 0, ciphertext length ; system arraycopy tag, 0, cipherdata, ciphertext length, tag length ; byte[] plaintext = contentcipher dofinal cipherdata ; return new string plaintext, java nio charset standardcharsets utf_8 ; } sample implementation in c# using system; using system io; using system text; using system text json nodes; using system security cryptography; public static void main string[] args { // example jwe string replace with your actual jwe and private key path string encryptedtext = {{encryptedpayload}}; string privatekeypath = /rsapriv der"; // read the private key file der format byte[] privatekeybytes = file readallbytes privatekeypath ; // decrypt the jwe string result = decryptjwe encryptedtext, privatekeybytes ; // print the result console writeline result ; } public static string decryptjwe string encryptedtext, byte[] privatekeybytes { // split jwe parts by ' ' var parts = encryptedtext split ' ' ; if parts length < 5 throw new argumentexception "invalid jwe format" ; // decode and parse jwe header var headerbytes = base64urldecode parts[0] ; var headerjson = encoding utf8 getstring headerbytes ; var header = jsonnode parse headerjson ; // extract algorithm information from header string alg = header?["alg"]? tostring ?? "rsa1_5"; string enc = header?["enc"]? tostring ?? "a128gcm"; // convert private key assume pkcs8 der using var rsa = rsa create ; rsa importpkcs8privatekey privatekeybytes, out _ ; // decode encrypted key, iv, ciphertext, and authentication tag var enckey = base64urldecode parts[1] ; var iv = base64urldecode parts[2] ; var ciphertext = base64urldecode parts[3] ; var tag = base64urldecode parts[4] ; // create cipher instance based on key management algorithm bool useaad = false; if alg == "rsa-oaep" { // at samsung, oaep uses aad additional authenticated data useaad = true; } else if alg == "rsa1_5" { // while rsa1_5 does not use aad useaad = false; } else { throw new argumentexception $"unsupported key management algorithm {alg}" ; } // decrypt the cek content encryption key byte[] plainenckey = alg == "rsa-oaep" ? rsa decrypt enckey, rsaencryptionpadding oaepsha1 rsa decrypt enckey, rsaencryptionpadding pkcs1 ; // decrypt the content using var aes = new aesgcm plainenckey, 16 ; var plaintext = new byte[ciphertext length]; if useaad { // aad handling use base64url-encoded header bytes as aad var encodedheader = encoding ascii getbytes base64urlencode headerbytes ; aes decrypt iv, ciphertext, tag, plaintext, encodedheader ; } else { aes decrypt iv, ciphertext, tag, plaintext ; } return encoding utf8 getstring plaintext trimend '\0' ; } private static byte[] base64urldecode string input { string s = input replace '-', '+' replace '_', '/' ; switch s length % 4 { case 2 s += "=="; break; case 3 s += "="; break; } return convert frombase64string s ; } private static string base64urlencode byte[] input { return convert tobase64string input trimend '=' replace '+', '-' replace '/', '_' ; } 3 3 4 integration on webview configure webview enablements to invoke samsung pay application in webview, you should override the shouldoverrideurlloading method javascript and dom storage are disabled in a webview by default you can enable through the websettings attached to your webview websettings allows any website to use javascript and dom storage for more information, visit websettings sample code kotlin import android webkit webview import android webkit webviewclient import android content intent import android content activitynotfoundexception companion object { private const val samsung_pay_url_prefix string = "samsungpay" private const val samsung_app_store_url string = "samsungapps //productdetail/com samsung android spay" } private lateinit var webview webview webview settings run { javascriptenabled = true domstorageenabled = true } webview webviewclient = object webviewclient { override fun shouldoverrideurlloading view webview, request webresourcerequest boolean { // get url from webresourcerequest val url = request url tostring // add below if statement to check if url is samsung pay or samsung app store deep link if url startswith samsung_pay_url_prefix || url startswith samsung_app_store_url , ignorecase = false { try { val intent = intent parseuri url, intent uri_intent_scheme startactivity intent } catch e activitynotfoundexception { // exception would be occured if the samsung wallet app is not installed // go to install samsung wallet app from market val installintent = intent parseuri "samsungapps //productdetail/com samsung android spay", intent uri_intent_scheme installintent addflags intent flag_activity_new_task startactivity installintent } // return true will cause that the url will not be loaded in webview return true } // the remaining part of the shouldoverrideurlloading method code // return false when you want to load url automatically by webview return false } } 3 3 5 sample implementation the following sample code implements the samsung pay web checkout button on a merchant site the implementation steps are described in web checkout integration for information about the content of the paymentmethods, transactiondetail, and paymentcredential data structures, see the api reference <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <script src="https //img mpay samsung com/gsmpi/sdk/samsungpay_web_sdk js"></script> </head> <body> <div id="samsungpay-container"></div> <script> const samsungpayclient = new samsungpay paymentclient {environment "stage"} ; let paymentmethods = { version "2", serviceid "dcc1cbb25d6a470bb42926", protocol "protocol_3ds", allowedbrands ["visa","mastercard"] } samsungpayclient isreadytopay paymentmethods then function response { if response result { createandaddbutton ; } } catch function err { console error err ; } ; function createandaddbutton { const samsungpaybutton = samsungpayclient createbutton { onclick onsamsungpaybuttonclicked, buttonstyle "black", type "buy" } ; document getelementbyid "samsungpay-container" appendchild samsungpaybutton ; } function onsamsungpaybuttonclicked { let transactiondetail = { ordernumber "dstrf345789dsgty", merchant { name "virtual shop", url "virtualshop com", id "xn7qfnd", countrycode "us" }, amount { option "format_total_estimated_amount", currency "usd", total 300 } } samsungpayclient loadpaymentsheet paymentmethods, transactiondetail then function paymentcredential { console log "paymentcredential ", paymentcredential ; const paymentresult = { "status" "charged", "provider" "pg name" } samsungpayclient notify paymentresult ; } catch function error { console log "error ", error ; } ; } </script> </body> </html> 3 3 6 api reference let us learn the description of data structures used in the samsung pay web checkout api integration paymentmethods the paymentmethods object defines the payment methods that the merchant supports "paymentmethods" data structure elements key type required description version string required samsung pay api versionthe supported value is 2 serviceid string required merchant id that is assigned after onboarding protocol string required payment protocol typethe supported value is protocol_3ds allowedbrands list<string> required list of supported card brandsthe possible values are visamastercardamexdiscoverelomadacbjaywan tbd isrecurring boolean optional value if payment is recurringthe default value is false isbillingaddressrequired boolean optional value if billing address must be included in the payment credentials the default value is false iscardholdernamerequired boolean optional value if cardholder name must be included in the payment credentials the default value is false iscpfcardrequired boolean optional value if cpf must be included in the payment credentials the default value is false merchantchoicebrands object optional data structure containing configuration information for a co-badged card merchantchoicebrands type string required co-badged card display option for the payment sheetthe possible values are mandatory = only the brand defined in merchantchoicebrands brands is enabledpreference = the brand defined in merchantchoicebrands brands is selected by default but the user can change it merchantchoicebrands brands list<string> required list of supported brands for the co-badged cardthe possible values are madacb extrapaymentinfo object optional data structure containing additional supported features extrapaymentinfo id string required feature id for the additional featurethe possible values are combocard = combo carddsrp = digital secure remote payment extrapaymentinfo type string optional feature type, if the value of extrapaymentinfo id is dsrpthe possible values are ucaf = universal cardholder authentication fieldicc = integrated circuit cardthe default value is ucaf transactiondetail the transactiondetail object contains the transaction information for the user's purchase "transactiondetail" data structure elements key type required description ordernumber string required order number of the transactionthe following characters are allowed [a-z][a-z][0-9,-] merchant object required data structure containing merchant information merchant name string required merchant name merchant url string required merchant domain urlthe maximum length is 100 characters merchant id string conditional a unique identifier, known as the merchant unique id, is assigned by either merchant or the payment gateway pg or payment orchestrator po when a merchant is onboarded into their system this id is required in specific scenarios, namely when onboarding as a pg or po with samsung, or if the token brand is "mada" or the merchantchoicebrands brands includes "mada" the character limit for this id varies 15 characters for "mada" token brands and 45 characters for all other cases merchant countrycode string required merchant country codeiso-3166-1 alpha-2 amount object required data structure containing the payment amount amount option string required display format for the total amount on the payment sheetthe possible values are format_total_estimated_amount = display "total estimated amount " and total amountformat_total_price_only = display the total amount only amount currency string required currency codethe maximum length is 3 characters amount total string required total payment amount in the currency specified by amount currencythe amount must be an integer for example, 300 or in a format valid for the currency such as 2 decimal places after a separator, for example, 300 50 type string optional transaction typethis value is specifically supported for mada tokens and will not apply to other token types the possible values are purchasepreauthorizationthe default value is purchase paymentcredential the paymentcredential object contains the payment credential information generated by the samsung wallet application on the user's mobile device paymentcredential data structure elements key type required description card_brand string required brand of the payment card card_last4digit object required last 4 digits of the card number 3ds object required data structure containing the generated 3ds data 3ds type string optional 3ds typethe value is s for samsung pay 3ds version string required 3ds versionthe value for the current version is 100 3ds data string required encrypted payment credential data recurring_payment boolean required value if credential is enabled for recurringthe default value is false encryptedmessage string conditional encrypted string jwe that contains billing address, cardholder name and cpf when required by partner it can be decrypted in the same way as payment credentials encryptedmessage the decrypted encryptedmessage object in paymentcredential object contains billing address, cardholder name and cpf when required by partner "encryptedmessage" data structure elements key type required description billingaddress object conditional billing address billingaddress addressline1 string required address line 1 billingaddress addressline2 string optional address line 2 billingaddress city string required city billingaddress state string conditional state billingaddress countrycode string required country code iso 3166-1 alpha-3 billingaddress postalcode string required postal code cardholdername string conditional cardholder name cpf object conditional brazilian cpf cpf name string required the full name of the individual associated with the cpf cpf number string required the brazilian taxpayer number cpf , consisting of exactly 11 digits, without hyphens or dots paymentresult the paymentresult object contains the payment result information during transaction processing, and after the payment is processed with pg network paymentresult data structure elements key type required description status string required payment statusthe possible values are charged = payment was charge successfullycanceled = payment was canceled by either user, merchant, or acquirerrejected = payment was rejected by acquirererred = an error occurred during the payment process provider string optional payment provider pg name 3 3 7 partner checklist checklist for samsung pay web checkout on the merchant website, verify if the following functions works as expected samsung pay is available in the payment options section of the website samsung pay logo is displayed correctly in the payment options section after the samsung pay payment option is selected, the account/scan qr and email input options are displayed, and redirects the user to the samsung wallet app on their mobile device for the account option, “request to pay” and “cancel” buttons are displayed for the email option, “next” and “cancel” buttons, and a way to reset id are displayed for the scan qr option, the request automatically times out if you wait for more than 5 minutes, and you are redirected to the checkout screen once redirected to the samsung wallet app, “pay” and “cancel” buttons are displayed on a mobile browser, after the samsung pay payment option is selected, “continue with samsung pay” button is displayed samsung checkout screen is displayed the merchant domain name is displayed the order summary which contains the amount due, and product name is displayed the payment method selected is “samsung wallet” the contact information displays the customer’s name, phone, and email you should be able to modify this information, if needed “continue” and “cancel” buttons are displayed note these are relevant if you are executing an end-to-end test you can skip these tests if you are using a test transaction setup on the samsung wallet app via your test device, verify if the following functions works as expected a default card is displayed on the payment sheet the card name and last 4 digits of the card is displayed on the payment sheet you are able to change the card when multiple cards are enrolled in samsung pay if you requested for the transaction using billingaddress parameter, the billing address is displayed on the payment sheet the billing address can be filled and modified depending on the amount option parameter, the payment amount is displayed as “total” or “total estimated amount ” the merchant name is displayed on the payment sheet the pin/biometric authentication option is displayed to proceed with payment confirmation the “verified” checkmark is displayed in blue upon payment confirmation if you are testing with actual cards, and samsung wallet is in production environment, confirm the transaction notification on the mobile phone is displayed once the purchase is made on transaction completion, verify the following on the merchant website the payment completion screen is displayed on the mobile or non-mobile device, depending where the transaction is initiated you are able to initiate a payment using samsung pay with a card already added for the merchant’s website basic card
Develop Samsung Wallet
doccommon overview the structure for configuring wallet cards follows the defined specification configuring the card data in the specified formatted json structure is required type value description card object cardobject required card information card typestring 16 required wallet card type card subtypestring 16 required wallet card sub type card data[]array of object required wallet card data container allows up to 6 objects at once data[] refidstring 128 required a unique content identifier defined by 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 attributes of card data * refer to the following chapters for each type data[] attributes {fields} attribute fields by card type data[] localization[]array of object optional information for multilingual support localization[] languagestring 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 * refer to the following chapters for each type security components confirmationvaluestring 256 optional reference values for authenticating card registration requests * see secure atw option from partner portal [example card object] { example card object { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-001", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet", "mainimg" "https // /main png" *refer to the following chapters for each type }, "localization" [{ "language" "ko", "attributes" { "title" "삼성 월렛" } }] }] } } to ensure secure transmission of card data, it must be tokenized in jwt format for this purpose, you will require the certificate obtained using the partner's email account when signing up for the partner portal for detailed information on secure data tokenization, please 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
doc3 4 save to pay 3 4 1 overview save to pay s2p is a secure integration service by samsung pay that enables partners to store and access user payment credentials for future transactions the communication between the partner’s backend and the save to pay server is protected by mutual ssl two-way ssl authentication, ensuring that both the client and server validate each other's identities key highlights uses a custom certificate authority ca managed by samsung pay techops requires ip allowlisting for both staging and production environments communication is secured over tls 1 2 involves both inbound partner → s2p and outbound s2p → partner api communications, secured via ssl and authenticated with client certificates and headers 3 4 2 endpoints there are 2 endpoints available - staging & production staging will be used for development and integration testing access to these endpoints is restricted to allowlisted ip addresses partner should provide the external ip addresses during the onboarding process supported protocols - tlsv1 2 staging https //s2p-api stg mpay samsung com production https //s2p-api mpay samsung com 3 4 3 onboarding steps to begin integration, follow these onboarding steps step 1 submit a certificate signing request csr partners must generate and send a csr to samsung, along with the following details common name cn for the client certificate partner server base url for receiving outbound notifications from the s2p server external ip address to be added to the access allowlist step 2 receive certificate and partner id samsung will sign the csr using its internal ca and return the client certificate a unique partner id will be issued for each environment this partner id must be included in the headers of every request made to the s2p server 3 4 4 authentication overview mutual ssl is used for both inbound and outbound communication between the partner and the save to pay system inbound partner → save to pay server all requests must be secured with mutual ssl partners connect using the client certificate issued by samsung every request must include the partner id in the header partner ids are environment-specific different for staging and production outbound save to pay server → partner s2p communicates with partner servers over mutual ssl samsung will use a client certificate signed by the partner’s ca partner must be able to validate s2p’s certificate for inbound requests 3 4 5 security protocols protocol tls v1 2 authentication mutual ssl two-way tls certificates partner-to-s2p samsung issues the client certificate s2p-to-partner partner issues the client certificate to samsung 3 4 6 best practices the best practices are keep your client certificate secure and monitor expiration dates log and monitor all inbound/outbound requests for verification and debugging maintain a staging environment for ongoing testing 3 4 7 external api specification the external api specification in the context of samsung's save to pay s2p service refers to the structured guidelines and protocols that define how external partner systems can securely interact with the s2p platform this specification encompasses authentication methods, data formats, api endpoints, and integration workflows to ensure seamless and secure provisioning of payment cards into the samsung wallet app 3 4 8 integration workflow the integration involves several key steps initialization & ui setup step 1–2 register session the partner server initiates the flow by registering with the s2p server on success, it receives regid a unique session identifier must be cached for session tracking welcomeurl a hosted ui url that guides the user through the card addition process step 3 display welcome ui the partner's frontend embeds the welcomeurl ui typically in an <iframe> the ui shows a qr code and clear instructions for the user to continue user interaction step 4 user launches samsung wallet spay wa the user opens the samsung wallet app and scans the qr code shown on the welcome ui if the app is not installed, the ui directs the user to download the samsung wallet app sign in with their samsung account session linking & device validation step 5–6 initiate request & device association spay wa scans the qr code and triggers an initiate request to the s2p server s2p validates the payload and links the device info with the regid the server also forwards the device metadata to the partner server device id wallet id user id the welcome ui updates to show that linking was successful card pre-provisioning step 7–8 partner pre-provisions card the partner server contacts the issuer to pre-provision the card retrieve the encrypted issuerblob which contains secure card/token information step 9 return issuerblob the partner server includes the issuerblob in its notify response back to the s2p server this blob is encrypted only the issuer can decrypt it is device- and wallet-specific only usable by the original device format depends on the issuer step 10 deliver to device the s2p server includes the issuerblob and any other metadata in the initiate response back to the spay wa tokenization steps 11–16 add token in samsung pay spay wa initiates the standard tokenization process using the issuerblob the token is securely added to the samsung wallet for use in nfc or online transactions completion & confirmation step 17 notify s2p server after successful provisioning, spay wa notifies the s2p server that the card/token was added successfully for the given regid step 18 notify partner the s2p server sends a final callback to the partner server confirming the process is completed for the regid 3 4 9 data types type json type format description string string size 2048 boolean boolean object object enum string pattern [a-za-z0-9_]{1,256 values from a limited set are only allowed each field of type enum will define the values allowed phonenumber string pattern [0-9+ -]+ uuid string pattern [a-za-z0-9-_]{26,128} unique identifier url string size 2048 must be an absolute url defined by rfc 2396 uniform resource identifiers uri generic syntax supported schemes - http, https timestamp number int64 - signed 64 bits unix epoch time in milliseconds countrycode string size 2 unique identifier 3 4 10 inbound api specification – save2pay the inbound api specification for save2pay defines the protocols and requirements for partner servers to interact with the save2pay system this specification ensures secure and standardized communication during the push provisioning process general contract base url https //s2p-api mpay samsung com/ext/v1 security mutual ssl is required common headers header name type validation description request-id uuid required unique identifier for the request partner-id uuid required unique identifier that is provided to partner during onboarding partner-id uuid required request-id echoed back in the response headers common http error codes http code description application code message 400 bad request 400 1 invalid data 500 internal server error 500 1 internal server error 503 service not available 503 1 service temporarily unavailable retry-after header is required 503 service not available 503 2 api temporarily unavailable retry-after header is required 3 4 11 registration partner server registers a session for the user as a result, a unique registration id will be generated partner server should make sure that this is called only once for one card a welcomeurl will also be returned partner server can display the welcomeurl in browser or email upon rendering, a qr code will be displayed and users can use their spay wa to scan the qr code welcomeurl has an expiration date, partner server should check if it's still valid before rendering if it's expired, a get call will return the new url request post /registrations body key type validation description example registration email string optional user email address registration enforceemailmatching boolean default is false optional enforce only spay wa with the same email address can provision enforcement is only against the email address that's provided by the partner true registration hideemail boolean default is false optional hide email field registration phone phonenumber optional user phone number registration enforcephonematching boolean optional default is false enforce only spay wa with the same phone number can provision enforcement is only against the phone number that's provided by the partner true registration hidephone boolean optional default is false hide phone field registration welcomecallbackurl url optional callback url that the welcome ui will redirect to once the user successfully linked a spay wa account registration allowofflinecommunication boolean optional default is false if true, s2p will communicate to the user via email and/or phone number to facilitate the provisioning process registration data object optional arbitrary data blob that'll be passed to the device when an account is linked registration custom cardname string required card name that'll show on the welcome page registration custom cardarturl url required cardart url that'll show on the welcome page registration custom partnername string required partner name that'll show on the welcome page registration custom partnerlogourl url required partner logo url that'll show on the welcome page registration custom partnertncurl url optional partner tnc url that'll show on the welcome page registration id uuid required registration id that identifies this session registration status enum - pending, linked required registration status pending registration welcomeurlexpiration timestamp required welcomeurl expiration timestamp in milliseconds response status http/1 1 201 created header name value content-type application/json example post /ext/v1/registrations { "email" "user@gmail com", "enforceemailmatching" true, "phone" "14089998888", "enforcephonematching" true, "custom" { "cardname" "xyz bank credit card", "cardarturl" "https //xyz com/cardart png", "partnername" "xyz bank", "partnerlogourl" "https //xyz com/logo png" } } http/1 1 201 created { "id" "395ce2e29485442cbd9bacdc77105126", "welcomeurl" "https //s2p stg mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiw iywxnijoizglyin0 s0dnxrskdkjw8sbh kg4uqhfwkkdnqrviihkaqshq_jayb99ct tizdzrwrn-qlhuzj4imuyv1sagehavyxluamarwa tlekqcerr0jklc-fnqkcva", "status" "pending", "welcomeurlexpiration" 1505953396844 } get registration check existing registration status and/or get new welcomeurl request get /registrations/{regid} headers name value validation partner-id partner id value assigned by samsung wallet required response status http/1 1 200 ok status name value content-type application/json body key type validation description example registration id uuid required registration id that identify this session registration status enum - pending, linked required registration status pending registration welcomeurl url required this is the url that partner can show to the user as an iframe a separate page it shows the qrcode and optionally user can enter email and phone number registration welcomeurlexpiration timestamp required welcomeurl expiration timestamp in milliseconds example http/1 1 200 ok { "id" "395ce2e29485442cbd9bacdc77105126", "welcomeurl" "https //s2p stg mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiw iywxnijoizglyin0 s0dnxrskdkjw8sbh kg4uqhfwkkdnqrviihkaqshq_jayb99ct tizdzrwrn-qlhuzj4imuyv1sagehavyxluamarwa tlekqcerr0jklc-fnqkcva", "status" "pending", "welcomeurlexpiration" 1505953396844 } errors common http error codes http code description application code message 400 bad request 400 1 invalid data 500 internal server error 500 1 internal server error 503 service not available 503 1 service temporarily unavailable retry-after header is required 503 service not available 503 2 api temporarily unavailable retry-after header is required 3 4 12 outbound to partner the outbound api specification for save2pay defines how the save2pay server communicates with partner servers during the push provisioning process this specification ensures secure and standardized communication between save2pay and its partners general contract base url base url for outbound apis to be provided by the partner during the onboarding process security mutual ssl is required common headers header name type validation description request-id uuid required unique identifier for the request partner-id uuid required unique identifier that is provided to partner during onboarding response-id uuid required request-id echoed back in the response headers 3 4 13 event notification notify partner for events request post /notifications body key description type validation example event regid registration id uuid required event type event type enum refer to event types and errors for details required event error more information about the failure enum refer to event types and errors for details event desc additional description of the event string optional user container for user information object conditional will be present for payment cards user id samsung account id string required emailmatches is true if the email provided in the registration request matches with samsung account email boolean conditional it is present only if an email was provided in the registration request phonematches is true if the phone number provided in the registration request matches with device phone number boolean conditional it is present only if a phone number was provided in the registration request device container for device information object conditional will be present for payment cards device id device id string required device imeilast4 last 4 of device imei string size 4 optional device seriallast4 last 4 of device serial number string size 4 optional device locale country device country code countrycode optional wallet container for wallet information object conditional will be present for payment cards wallet id wallet id string required event types and errors type error description wa_ready wallet app is ready for provisioning wa_provisioned indicates card was successfully provisioned into the wallet wa_provision_failure indicates provisioning failed for some unknown reason wa_provision_failure card_already_present indicates card is already present response status http/1 1 200 ok header name value content-type application/json body card data encrypteddata description encrypted pan data that will be returned to the device to provision the card type string size 65536 validation conditional required if card data was not provided in the registration request example example post /notifications { "event" { "regid" "395ce2e29485442cbd9bacdc77105126", "type" "wa_ready" }, "emailmatches" true, "phonematches" true, "user" { "id" "rcsm3gwjt9mxgfwy5sg123" }, "wallet" { "id" "gpccugejs9giih8zch1111" }, "device" { "id" "mtuxmte5mdawmjawmdm1n999", "imeilast4" "6166", "locale" { "country" "us" }, "seriallast4" "4934" } } http/1 1 200 ok { "card" { "data" { "encrypteddata" "*****" } } } 3 4 14 save to pay javascript library javascript library interface savetopayui { /** * shows the welcome ui redirects to welcomecallbackurl if it was provided in the registration request when the page reaches one of the final states */ static void showwelcomemodal s2prequest r ; /** * shows the welcome ui resolves the promise with the status and optionally details after the welcome ui is closed */ static promise <s2presponse> showwelcomemodalpromise s2prequest r ; /** * api to close the modal */ static void closewelcomemodal ; }; dictionary s2prequest { /** * welcomeurl provided by save2pay server in the registration response */ required domstring welcomeurl; }; dictionary s2presponse { required status status, /** * true if triggered by iframe closing by user or parent page * false if the status is one of the final statuses, not triggered by iframe closing this can only happen in mobile android case */ required boolean isiframeclosed, /** * optional error information if the status is 'failure' */ details details }; dictionary details { required errorcode errorcode; domstring message; }; enum status { "success", "failure", "device_not_supported", "default_pending" }; enum errorcode { "invalid_input", "provision_failure", "network_error", "unknown_error", "card_already_present", "canceled" }; usage code block -1 html <script src="https //spay samsung com/s2p/libs/js/0 0 4/s2p min js"></script> code block -2 javascript - redirect var input = { "welcomeurl" 'https //s2p mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiwiywx nijoizglyin0 eltgw8qp56ciezo2 mh34gjebgyp_m7- gw0sbdl3ckaplp7rtvmc8fe-tmq2ipmp2rcc1a39qodbvw2schiarbooahbe77lpvl8nhkkapi6mhynl-yz6gqx0sjw xfrtyjpdzxrnmlq8ffe6pg' } window spay savetopayui showwelcomemodal input code block- 3 javascript - promise var request = { "welcomeurl" 'https //s2p mpay samsung com/v1/welcome/eyjlbmmioijbmju2r0nniiwiywx nijoizglyin0 eltgw8qp56ciezo2 mh34gjebgyp_m7- gw0sbdl3ckaplp7rtvmc8fe-tmq2ipmp2rcc1a39qodbvw2schiarbooahbe77lpvl8nhkkapi6mhynl-yz6gqx0sjw xfrtyjpdzxrnmlq8ffe6pg' } function successcallback response { console log response status } function failurecallback error { console log error } window spay savetopayui showwelcomemodalpromise request then succes scallback, failurecallback promise resolution device type description desktop, tablet & mobile - ios js library will resolve the promise - 1 when the iframe is closed by the user 2 closewelcomemodal function is invoked mobile - android js library will resolve the promise as soon as the provisioning session ends or closewelcomemodal function is invoked provisioning session ends when one of the following has happened - 1 the card was successfully added 2 there was some failure and card provisioning flow cannot continue further 3 timeout has happened 4 user canceled the provisioning process mobile flows
Develop Samsung Wallet
docbarcode & qr code presentation this section describes how to define and configure barcode and qr code data for samsung wallet cards developers can use this guide to understand the supported formats, data structures, and usage examples when integrating barcode or qr-based cards card data format overview barcode and qr code data are defined using a set of barcode * fields these fields determine what is displayed, how it is displayed, and which barcode or qr format is used the configuration consists of the following components presentation type barcode serialtype presentation format barcode ptformat barcode / qr format barcode ptsubformat note the barcode json object must be delivered as an escaped json string to enable dynamic qr, the corresponding option must be enabled in the samsung wallet partner portal barcode data structure [example] { "barcode value" "www samsung com", "barcode serialtype" "barcode", "barcode ptformat" "barcodeserial", "barcode ptsubformat" "upc_a" } field description artifact required description barcode value yes actual value to be encoded in the barcode or qr code barcode serialtype yes type of data to be displayed barcode, qr code, serial number, etc barcode ptformat yes display format barcode only, barcode with serial, qr only, etc barcode ptsubformat optional barcode or qr code specification barcode interval optional validity period in seconds for dynamic qr presentation types barcode serialtype defines what kind of data is presented code name description serialnumber displays a serial number barcode displays a 1d barcode qrcode displays a qr code shipping shipping information online use only callorder call order information online use only url url serial online use only presentation formats barcode ptformat defines how the data is visually displayed code name description barcode barcode only barcodeserial barcode with serial number serial serial number only dualserial dual serial numbers dualbarcode dual barcodes dualbarcodeserial dual barcodes for each serial number barcodepin barcode with pin qrcode qr code only qrcodeserial qr code with serial number barcode barcode only barcodeserial barcode with serial number barcode / qr formats barcode ptsubformat defines the actual barcode or qr encoding format all formats are supported by the zxing barcode scanning library [1d barcode / qr formats] code name description codabar codabar 1d format code_39 code 39 1d format code_93 code 93 1d format code_128 code 128 1d format ean_8 ean-8 1d format ean_13 ean-13 1d format itf interleaved two of five rss_14 rss-14 rss_expanded rss expanded upc_a upc-a 1d format upc_e upc-e 1d format upc_ean_extension upc/ean extension not stand-alone [2d barcode / qr formats] code name description qr_code qr code 2d format aztec aztec 2d barcode format data_matrix data matrix 2d format maxicode maxicode 2d format pdf_417 pdf417 format data sample 1d barcode with serial upc-a [example] { "barcode value" "www samsung com", "barcode serialtype" "barcode", "barcode ptformat" "barcodeserial", "barcode ptsubformat" "upc_a" } 2d barcode as qr code [example] { "barcode value" "www samsung com", "barcode serialtype" "qrcode", "barcode ptformat" "qrcode", "barcode ptsubformat" "qr_code" } dynamic qr code aztec, 300 seconds validity [example] { "barcode value" "www samsung com", "barcode serialtype" "qrcode", "barcode ptformat" "qrcode", "barcode ptsubformat" "aztec", "barcode interval" "300" } serial number only [example] { "barcode value" "1234567890", "barcode serialtype" "serialnumber", "barcode ptformat" "serial" } developer notes ensure that serialtype, ptformat, and ptsubformat are logically compatible use barcode interval only for dynamic qr scenarios always validate supported formats based on zxing specifications all barcode data must be transmitted as an escaped json string
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 4096 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
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 guidehttps //developer samsung com/wallet/api_new/verifywith/button html#data-transmit-link onresponselistener a listener to receive each events or request [sample code] https //developer samsung com/wallet/api_new/references/coderesources html#rpclient-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 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 code explanation based on the sample code jwt jws + jwe decryption between the wallet backed server and partner server 1 verify by generating 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 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 preventcaptureyn string 1 optional flag whether this wallet card view prevents screen capture either 'y' or 'n' * default '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 card can be used * see location format noticedesc string 5000 optional text of notice *html supported extendedfields string 1024 optional a flexible list of key-value pairs* see extended fields csinfo string 4096 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 level string 16 optional it represents the name or title of the loyalty level e g , bronze, silver, gold, etc user string 64 optional name of person who holds the loyalty card idphoto string 20k optional holder’s photo image data encoded base64 idphoto format string 32 optional image file formate g , jpeg, png* unsupported image formats may exist idphoto status string 16 optional status of the data allowed value unchanged provision data string 512 optional elements to complete provisioning* see provisioning for details provision interval string 16 optional update interval if support for dynamic updates epoch timestamp in milliseconds 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 Blockchain
apipackage class tree deprecated index help com samsung android sdk coldwallet class scwservice java lang object com samsung android sdk coldwallet scwservice public class scwservice extends java lang object class for the proxy to use the samsung blockchain keystore service the keystore's hd wallet seed is bip-39 compatible see also https //github com/bitcoin/bips/blob/master/bip-0039 mediawiki nested class summary nested classes modifier and type class and description static class scwservice scwcheckformandatoryappupdatecallback callback for checkformandatoryappupdate api static class scwservice scwgetaddresslistcallback callback for getaddresslist api static class scwservice scwgetextendedpublickeylistcallback callback for getextendedpublickeylist api static class scwservice scwsignbtctransactioncallback callback for signbtctransaction api static class scwservice scwsignethpersonalmessagecallback callback for signethpersonalmessage api static class scwservice scwsignethtransactioncallback callback for signethtransaction api static class scwservice scwsignklaytransactioncallback callback for signklaytransaction api method summary all methods static methods instance methods concrete methods modifier and type method and description void checkformandatoryappupdate scwservice scwcheckformandatoryappupdatecallback callback checks whether a mandatory update of samsung blockchain keystore is needed or not void getaddresslist scwservice scwgetaddresslistcallback callback, java util arraylist<java lang string> hdpath request to get a list of addresses that corresponds to a list of hd paths void getextendedpublickeylist scwservice scwgetextendedpublickeylistcallback callback, java util arraylist<java lang string> hdpath request to get a list of extended public keys that corresponds to a list of hd paths static scwservice getinstance return the instance of the keystore proxy object int getkeystoreapilevel get api level which the keystore in the device supports java lang string getseedhash get the pseudo seed hash which is randomly generated when the hd wallet created whenever the seed for the wallet is changed, this key shall be changed int[] getsupportedcoins get coin types supported by samsung blockchain keystore void signbtctransaction scwservice scwsignbtctransactioncallback callback, byte[] transaction, java util list<java lang string> hdpathlist, java util list<byte[]> utxotxlist, java lang string changehdpath request to sign bitcoin transaction void signethpersonalmessage scwservice scwsignethpersonalmessagecallback callback, byte[] msg, java lang string hdpath request to sign ethereum typed structured data void signethtransaction scwservice scwsignethtransactioncallback callback, byte[] transaction, java lang string hdpath request to sign ethereum transaction void signklaytransaction scwservice scwsignklaytransactioncallback callback, byte[] transaction, java lang string hdpath, int networkid request to sign klay transaction methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait method detail getinstance public static scwservice getinstance return the instance of the keystore proxy object returns the instance, or null if samsung blockchain keystore is not available on the device getkeystoreapilevel public int getkeystoreapilevel get api level which the keystore in the device supports caution you should check the api level before invoking any apis otherwise, it will return scwapilevelexception if keystore api level is lower than the required level, update the keystore app first via scwdeeplink galaxy_store returns api level since api level 1 getseedhash public java lang string getseedhash get the pseudo seed hash which is randomly generated when the hd wallet created whenever the seed for the wallet is changed, this key shall be changed returns null if keystore does not support wallet key, zero-length string if the wallet is not created otherwise, wallet is created since api level 1 getsupportedcoins public int[] getsupportedcoins get coin types supported by samsung blockchain keystore returns array of coin types, scwcointype throws scwapilevelexception - api level exception since api level 1 see also https //github com/satoshilabs/slips/blob/master/slip-0044 md checkformandatoryappupdate public void checkformandatoryappupdate @nonnull scwservice scwcheckformandatoryappupdatecallback callback checks whether a mandatory update of samsung blockchain keystore is needed or not do not call this method in the background thread if there is a mandatory update, you need to open the app update link, scwdeeplink galaxy_store parameters callback - result callback since api level 1 getextendedpublickeylist public void getextendedpublickeylist @nonnull scwservice scwgetextendedpublickeylistcallback callback, @nonnull java util arraylist<java lang string> hdpath request to get a list of extended public keys that corresponds to a list of hd paths parameters callback - result callback hdpath - the hd path list to bring the public keys the depth of a path should be between 3 and 6 for example, "m/44'/60'", "m/44'/60'/0'/0/0" since api level 1 see also https //github com/bitcoin/bips/blob/master/bip-0032 mediawiki getaddresslist public void getaddresslist @nonnull scwservice scwgetaddresslistcallback callback, @nonnull java util arraylist<java lang string> hdpath request to get a list of addresses that corresponds to a list of hd paths parameters callback - result callback hdpath - the hd path list to bring the addresses the depth of a path should be between 3 and 6 for example, "m/44'/60'", "m/44'/60'/0'/0/0" since api level 1 see also https //github com/bitcoin/bips/blob/master/bip-0032 mediawiki signethtransaction public void signethtransaction @nonnull scwservice scwsignethtransactioncallback callback, @nonnull byte[] transaction, @nonnull java lang string hdpath request to sign ethereum transaction parameters callback - result callback transaction - a byte array of a rlp-encoded unsigned ethereum transaction hdpath - hd path that corresponds to public key needed for signing since api level 1 signethpersonalmessage public void signethpersonalmessage @nonnull scwservice scwsignethpersonalmessagecallback callback, @nonnull byte[] msg, @nonnull java lang string hdpath request to sign ethereum typed structured data parameters callback - result callback msg - a byte array of raw message to be signed the keystore will add "ethereum signed message \n" prefix, so it should not be included in msg hdpath - hd path that corresponds to public key needed for signing since api level 1 see also https //github com/ethereum/eips/blob/master/eips/eip-712 md signklaytransaction public void signklaytransaction @nonnull scwservice scwsignklaytransactioncallback callback, @nonnull byte[] transaction, @nonnull java lang string hdpath, @nonnull int networkid request to sign klay transaction parameters callback - result callback transaction - a byte array of a raw transaction to be signed by samsung blockchain keystore the transaction is same as the sigrlp value mentioned in klaytn's official document hdpath - hd path that corresponds to public key needed for signing networkid - the klaytn network id, or the integer to identify the network "8217" is klaytn cypress mainnet and "1001" is klaytn baobab testnet since api level 2 see also https //docs klaytn com/node/en/installation/config signbtctransaction public void signbtctransaction @nonnull scwservice scwsignbtctransactioncallback callback, @nonnull byte[] transaction, @nonnull java util list<java lang string> hdpathlist, @nonnull java util list<byte[]> utxotxlist, @nonnull java lang string changehdpath request to sign bitcoin transaction parameters callback - result callback transaction - a byte array of a serialized unsigned bitcoin transaction to be signed by samsung blockchain keystore hdpathlist - a list of hd paths that corresponds to utxo's public key utxotxlist - a list of byte array of the serialized transaction which contain the utxo used in this transaction changehdpath - hd path that corresponds to the change address since api level 2 see also https //github com/bitcoin/bips/blob/master/bip-0044 mediawiki, https //github com/bitcoin/bips/blob/master/bip-0049 mediawiki, https //github com/bitcoin/bips/blob/master/bip-0084 mediawiki
Develop Samsung Wallet
docdata structure and format extended fields a list of customizable data fields used for rendering dynamic content in the card ui or printed representation each field consists of a label, value, and an optional order to define display sequence if the card type is generic, a type field is also included to map each field to a predefined layout position note the type values must align with the layout definitions provided by the service do not define or use custom fields without prior agreement to ensure consistent rendering and data integrity type description label required the display name of the field value required the actual content shown alongside the label type conditional a predefined identifier used to map the field to a specific position in the layout this field is used only for generic card type and must align with layout defined from partner portal order optional defines the display order of the fields lower numbers appear first [example] { "extendedfields" [ { "label" "name", "value" "bahadur bhai", "type" "text1", "order" 1 }, { "label" "role", "value" "graphic designer", "type" "text2", "order" 2 }, { "label" "contact", "value" "+0012349012", "type" "text3", "order" 3 }, { "label" "email", "value" "into@email space", "type" "text4", "order" 4 }, { "label" "address", "value" "123 dunny, lorem ipsum", "type" "text5", "order" 5 } ] } 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 type description info[]object arrays required container of information info[] titlestring required title * need either content or chart info[] content[]string arrays optional content text info[] more[]object arrays optional the addtional information that needs to be checked by pressing the ⓘ button in the contents of the info[] title info[] more[] titlestring optional title * need either content or chart info[] more[] content[]string arrays optional content text info[] chartobject 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" ] } ] } * 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 case of more information included reservation-rentalcars { "count" 2, "info" [ { "title" "included", "content" [ "car rental rates ldw-loss damage waiver tax & surcharge" ], "more" [ { "title" "what's included", "content" [ "options which is checked --- ", "please note that additional insurance ---" ] } ] }, { "title" "options", "content" [ "n/a" ] } ] } * 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" } }] } * example usage of html { "count" 2, "info" [ { "title" "<b>this is bold text</b> <font color='red'>this is red text</font> <a href='https //www example com'>this is a link</a>", "content" [ "1 wear a mask", "2 temperature check before entering the theater", "3 electronic entry registration for all customers using the performance", "please cooperate even if it takes some time before entering ", "we kindly ask for your cooperation " ] }, { "title" "[parking information]", "content" [ "<b>this is bold text</b> <font color='red'>this is red text</font> <a href='https //www example com'>this is a link</a>" ] } ] } 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 classification classification defines different kinds of people who can use the cards vlaue description person[]array of object required container of person list who can use the card person[] categorystring required category name person[] countstring required number of persons example 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 vlaue description [] datestring required transaction date [] amountstring optional amount value [] descriptionstring 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" } ] links links is a standard data structure that represents a list of actionable links provided by a content provider json format value description orderinteger 1~5 optional display order of the link smaller values are displayed first if omitted, the array order is used titlestring 32 required primary text shown to the user subtitlestring 32 optional secondary descriptive text shown below the title linkstring 2000 required url to access the provider’s additional information max 2000 characters de-facto limit example { "links" [ { "order" 1, "title" "medical consultation", "subtitle" "see more information", "link" "https //samsung external info link" } ] } 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 note map services are only available in certain countries json format vlaue description [] latdouble optional latitude [] lngdouble optional longitude [] addressstring required string containing the full address [] namestring 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" } ] itinerary information json format vlaue description itineraryinformation[] idstring 32 optional unique id assigned to each segment of the journey itineraryinformation[] orderstring 4 optional order of each segment within the overall itinerary itineraryinformation[] providernamestring 32 conditional provider name * required if subtype is etickets itineraryinformation[] providerlogostring 256 conditional url of the logo image * required if subtype is etickets itineraryinformation[] providerlogo darkurlstring 256 conditional url of the logo image in dark mode * required if subtype is etickets itineraryinformation[] providerlogo lighturlstring 256 conditional url of the logo image in light mode * required if subtype is etickets itineraryinformation[] departureobject conditional information about the place of departure itineraryinformation[] departure namestring 32 conditional name of the departure point * required if subtype is etickets itineraryinformation[] departure codestring 32 conditional iata code for the departure point * required if subtype is etickets itineraryinformation[] departure airportstring 100 conditional airport name of the departure point * required if subtype is etickets itineraryinformation[] departure terminalstring 100 conditional terminal name of the departure point * required if subtype is etickets itineraryinformation[] departure platformstring 100 optional platform name of the departure point itineraryinformation[] departure time xtimestamplong 13 conditional departure time epoch timestamp in milliseconds i e , the estimated time the aircraft plans to pull from the gate, or the actual time the aircraft already pulled from the gate * required if subtype is etickets itineraryinformation[] departure utcoffsetstring 8 conditional utc offset of time at the departure point * required if subtype is etickets itineraryinformation[] departure zoneidstring 64 optional unique identifier for a timezone as defined by the iana time zone database it represents a specific region's timezone, including rules for daylight saving time dst and historical changes ex "america/new_york", "europe/london" itineraryinformation[] departure literalvaluestring 32 optional the departure time that should be indicated on the screen is formatted valueformat yyyy-mm-ddthh mm ssex 2025-10-30t14 35 00 itineraryinformation[] departure latitudedouble optional the latitude of where the event is start* input when timestamp and zoneid information is not known itineraryinformation[] departure longitudedouble optional the longitude of where the event is start* input when timestamp and zoneid information is not known itineraryinformation[] departure addressstring 256 optional the address of where the event is start* input when timestamp and zoneid information is not known itineraryinformation[] arrivalobject conditional information about the place of arrival itineraryinformation[] arrival namestring 32 conditional name of the arrival point * required if subtype is etickets itineraryinformation[] arrival codestring 32 conditional iata code for the arrival point * required if subtype is etickets itineraryinformation[] arrival airportstring 100 conditional airport name of the arrival point * required if subtype is etickets itineraryinformation[] arrival terminalstring 100 conditional terminal name of the arrival point * required if subtype is etickets itineraryinformation[] arrival platformstring 100 optional platform name of the arrival point itineraryinformation[] arrival timelong 13 conditional arrival time epoch timestamp in milliseconds i e , the estimated time the aircraft plans to pull from the gate, or the actual time the aircraft already pulled from the gate * required if subtype is etickets itineraryinformation[] arrival utcoffsetstring 8 conditional utc offset of time at the arrival point * required if subtype is etickets itineraryinformation[] arrival zoneidstring 64 optional unique identifier for a timezone as defined by the iana time zone database it represents a specific region's timezone, including rules for daylight saving time dst and historical changes ex "america/new_york", "europe/london" itineraryinformation[] arrival literalvaluestring 32 optional the departure time that should be indicated on the screen is formatted value format yyyy-mm-ddthh mm ssex 2025-10-30t14 35 00 itineraryinformation[] arrival latitudedouble optional the latitude of where the event is start* input when timestamp and zoneid information is not known itineraryinformation[] arrival longitudedouble optional the longitude of where the event is start * input when timestamp and zoneid information is not known itineraryinformation[] arrival addressstring 256 optional the address of where the event is start * input when timestamp and zoneid information is not known itineraryinformation[] boardingtimelong 13 optional boarding time epoch timestamp in milliseconds itineraryinformation[] vehiclenumberstring 32 conditional transit or route numberi e , flight number on airlines * required if subtype is etickets itineraryinformation[] coachnumberstring 16 optional identifier assigned to each individual carriage e g , b4 itineraryinformation[] seatclassstring 32 conditional seat class * required if subtype is etickets itineraryinformation[] seatnumberstring 16 optional individual number of the passenger seat e g , a-9, free itineraryinformation[] seatfacingstring 16 optional direction in which the seat is oriented within a carriage it indicates whether the seat is positioned to face the direction of travel or face the opposite direction e g , forward, backward itineraryinformation[] baggageallowancestring 20 optional baggage allowance itineraryinformation[] flighttimestring 8 optional the time required for a flight itineraryinformation[] checkinlinkstring 256 optional link to check in itineraryinformation[] usertypestring 32 optional passenger typei e , classification of passengers like child, adult example { "itineraryinformation" [ { "id" "itineraryid", "order" 1, "departure" { "name" "departurename", "code" "departurecode", "platform" "departureplatform", "time" 1749624040000, "utcoffset" "utc+09 00" }, "arrival" { "name" "arrivalname", "code" "arrivalcode", "platform" "arrivalplatform", "time" 1749624040000, "utcoffset" "utc+09 00" }, "vehiclenumber" "vehiclenumber", "coachnumber" "coachnumber", "seatclass" "seatclass", "seatnumber" "seatnumber", "seatfacing" "seatfacing", "usertype" "usertype" } ] } 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
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.
You have successfully updated your cookie preferences.