Web Checkout SDK
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