Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
tutorials digital payments
blogintegrating payments into a mobile app is a security-critical and ux-sensitive task. while flutter simplifies cross-platform development, platform-specific payment systems like samsung pay still require careful handling. samsung provides an official samsung pay sdk flutter plugin, which allows flutter applications to integrate samsung pay without writing custom platform channels. however, for production-grade integration, using the plugin correctly is essential, especially when it comes to checking samsung pay readiness. in this blog, you learn how to build a sample flutter application by using the official samsung pay sdk flutter plugin and following samsung-recommended best practices. you can download the complete sample project at the end of this blog. why use the official samsung pay sdk flutter plugin? integrating payment systems requires careful handling of platform constraints, security, and long-term maintainability. the samsung pay sdk flutter plugin addresses these concerns by providing an official abstraction over the native samsung pay sdk, enabling flutter applications to leverage samsung wallet features without direct interaction with platform-specific apis. by exposing supported dart apis and managing native sdk communication internally, the flutter plugin removes the need for custom methodchannel implementations and reduces integration risk. for flutter applications targeting samsung galaxy devices, this approach offers the most stable and maintainable path to samsung pay integration. the following diagram illustrates the high-level architecture of the samsung pay integration. figure 1: samsung pay integration architecture prerequisites before starting, ensure the following requirements are met: you are an approved samsung pay partner (approval typically takes a few days) a service is created in the samsung pay partner portal. find details from here. the latest version of android studio is installed the flutter sdk is installed and configured the samsung pay sdk flutter plugin is downloaded set up the integration code to start the integration process, add the samsung pay sdk flutter plugin to your project dependencies: dependencies: samsung_pay_sdk_flutter: path: ./samsungpaysdkflutter_v1.03.00/samsungpaysdkflutter next, configure the samsung pay sdk api level by setting a valid samsung pay sdk api version (latest version: 2.22) by opening android > app > src > main > androidmanifest.xml and adding the api level in the metadata inside the <application> tag. <meta-data android:name="spay_sdk_api_level" android:value="2.22" /> <!-- use the most recent sdk version to leverage the latest apis --> initialize samsung pay in flutter create an instance of samsungpaysdkflutter with valid partnerinfo (which contains the service id and service type). if you are a merchant, then the service type must be set to inapp_payment. the following code snippet initializes the samsung pay sdk using your service id and in-app payment configuration. import 'package:samsung_pay_sdk_flutter/samsung_pay_sdk_flutter.dart'; static final samsungpaysdkflutter sdk = samsungpaysdkflutter( partnerinfo( serviceid: service_id, data: { spaysdk.partner_service_type: servicetype.inapp_payment.name } ) ); check samsung pay availability samsung pay readiness must be checked before calling any api of the samsung pay sdk flutter plugin. there are several reasons why samsung pay might not be in the ready state, such as an unsupported device, unsupported region, or incomplete samsung wallet setup, so this check is mandatory. samsungpayconfig.sdk.getsamsungpaystatus( statuslistener( onsuccess: (status, bundle) { // status "2" means samsung pay is ready onresult(status == "2"); }, onfail: (errorcode, bundle) { // if status check fails, samsung pay is not ready onresult(false); } ) ); notedo not show the samsung pay button if the samsung pay status is not ready. create payment information with a custom payment sheet to initiate a transaction, you must create a payment request using a custom payment sheet. the amountboxcontrol object is mandatory for building a customsheet. it provides the monetary details of the transaction. amountboxcontrol amountcontrol = amountboxcontrol( strings.amount_control_id, strings.currency ); // add product item to the payment sheet amountcontrol.additem( product.productid, product.name, product.price, "" ); // set total amount (product price + additional fees) // you can add tax, shipping, or other fees here amountcontrol.setamounttotal( product.price + 5.00, // add $5 for shipping/fees as example spaysdk.format_total_price_only ); next, add the amountboxcontrol to the customsheet instance. customsheet customsheet = customsheet(); customsheet.addcontrol(amountcontrol); finally, create the payment information by populating the customsheetpaymentinfo instance // configure merchant information for the payment customsheetpaymentinfo paymentinfo = customsheetpaymentinfo( merchantname: "samsung pay flutter app", customsheet: customsheet ); // set merchant details paymentinfo.merchantid = "123456"; paymentinfo.setmerchantname("sample merchant"); paymentinfo.setmerchantcountrycode("us"); request payment to start the payment process, call the startinapppaywithcustomsheet() api. this api requires customsheetpaymentinfo and customsheettransactioninfolistener instances set up in the last step. when this api is called, a custom payment sheet is displayed on the merchant application screen. the user can select a registered card for the payment and change the billing and shipping addresses if needed. payment results are delivered to the customsheettransactioninfolistener. the oncardinfoupdated() callback is triggered when the user changes the payment card. in this callback, the updatesheet() method must be called to update current payment sheet. customsheettransactioninfolistener listener = customsheettransactioninfolistener( oncardinfoupdated: (paymentcardinfo cardinfo, customsheet sheet) { // called when user changes the selected card on payment sheet // you can update the sheet here if needed (e.g., change fees based on card) samsungpayconfig.sdk.updatesheet(sheet); }, onsuccess: (paymentinfo, paymentcredential, extradata) { // payment completed successfully // paymentcredential contains the encrypted card details to send to your backend print("payment successful!"); print("payment credential: $paymentcredential"); onsuccess(); }, onfail: (errorcode, bundle) { // payment failed or user cancelled print("payment failed: $errorcode"); onfail(errorcode); } ); lastly, call startinapppaywithcustomsheet() api to start the payment: samsungpayconfig.sdk.startinapppaywithcustomsheet(paymentinfo, listener); testing samsung pay integration follow the steps below to test samsung pay integration configure the stg environment: add tester accounts to your service and generate a debug expiration date for the test accounts. install samsung wallet test application: to test your application in the staging environment, the latest version of the samsung wallet test application is required. you can install it from the samsung pay partner portal. however, to test your app in production mode, you need to use a market released application. test cards: to thoroughly test your application, you must add at least one payment card to the samsung wallet application. samsung provides test cards for this purpose. keep in mind that the test cards only work in staging environments, not in production. run the application: after setting up the environment, build the application and test it on any supported galaxy device. figure 2: samsung pay flutter sample application release your application after successful testing, submit your application for release approval through the samsung pay developers portal. once approved, your app can be published for your users. conclusion using the official samsung pay sdk flutter plugin makes it simpler to create a secure and reliable payment integration for flutter applications on galaxy devices. by following samsung-recommended practices, such as checking samsung pay readiness and handling custom payment sheets correctly, you can build a production-ready and maintainable payment experience. additional resources samsung pay documentation provides an overview of the key features and highlights the benefits of using samsung pay. samsung pay partner onboarding is an end-to-end guide of becoming a partner to release your app. samsung pay – code lab is an interactive, hands-on tutorial that teaches you to how to integrate samsung pay sdk. samsung developer forums is an open community for developers where you can post your query and get support from other developers. samsung developer tech support channel is a 1-on-1 support channel where you can get assistance from the samsung engineers. download the complete sample project here.
Jakia Sultana
Develop Samsung Pay
doctroubleshoot integration issues the following instructions guide you in solving specific error situations related to your samsung pay integration issue 1 the `getallcards ` method returns the `onsuccess ` callback with an empty list, even though cards have been added in samsung wallet this issue is commonly caused by an issuer name mismatch make sure that the issuer name configured in your service matches the issuer name associated with the card to find the issuer name associated with the card open the samsung wallet app tap the card to view its details open the menu on the top right, and select customer services the issuer name is displayed under the page title issue 2 the `getsamsungpaystatus ` method returns the `onfail ` callback with the `spay_not_supported` status this error occurs if the device is incompatible with samsung pay or if the samsung wallet app is not installed use a compatible device and install the samsung wallet app if your app’s target api level is 30 or higher, you must also include a <queries> element in the androidmanifest xml file for more information, see add the samsung pay sdk for android to your project issue 3 i am getting the `error_partner_app_signature_mismatch` error this error occurs in the following circumstances the package name specified in the samsung pay portal does not match the app’s actual package name to check the package name log in to the samsung pay portal in the all services section of your dashboard, click the app name for the applicable service locate the package name in the service details section the signature of the apk you uploaded does not match that of the apk you are using fix the package name or apk, as needed issue 4 i am getting the `error_not_registered_user_for_debugging` error this error occurs when the samsung account used for testing is not registered as a test account for the service to add a test account log in to the samsung pay portal in the all services section of your dashboard, click the applicable service's name add the samsung account under test accounts and click save issue 5 i am getting the `error_inadequate_data_from_db` error check the following if you integrate through a payment gateway, ensure the certificate signing request csr uploaded during service creation is the payment gateway’s csr, not a self-generated one verify that the apk metadata complies with length limits package name 50 version 20 signature 100 issue 6 i am getting the `error_not_supported_country_code` error this error occurs when the region set on the customer’s device is not among the countries configured for the service to add the device's country to your service log in to the samsung pay portal in the all services section of your dashboard, click the applicable service's name click edit add the country in the service location field and click save if the service is in the requested or approved status, you must go through the approval process again for the updated service issue 7 i am getting the `error_service_not_exist` error this error occurs in the following circumstances the service has been deleted the service id is invalid to verify the service id log in to the samsung pay portal in the all services section of your dashboard, click the applicable service's name locate the service id in the service details section if the service has been deleted, create a new service issue 8 i am getting the `error_not_approved_service` error this error occurs when the service is not in the approved status to get your service approved, create a support ticket issue 9 i am getting the `error_spay_app_need_to_update` error this error indicates that the samsung wallet app needs an update update the app as instructed and try again issue 10 i am getting the `error_partner_sdk_version_not_allowed` error this error indicates that the samsung pay-related sdk version you are using is not allowed use a valid version of the sdk samsung recommends using the latest version available on the downloads and resources page issue 11 i am getting the `error_sdk_not_supported_for_this_region` error this error occurs when samsung pay is used in a region where it is not supported to confirm supported regions, see country and device availability issue 12 i am getting the `error_not_allowed` error this error indicates that the requested operation is not allowed; for example, your app verification has failed in the samsung pay server create a support ticket and include the device dump logs issue 13 i am getting the `error_invalid_payload` error this error is caused by an incorrectly constructed payload ensure the payload follows your card network’s specification issue 14 i am getting the `error_card_already_registered` error this error indicates the card is already registered delete the card from the samsung wallet app and try again issue 15 i am getting the `unknown_error_code` error create a support ticket and include the device dump logs issue 16 i am getting the `error_not_approved_service` error this error occurs when the service is not in the approved status to change the status of your service, request approval on the samsung pay portal
Develop Samsung Pay
docoverview the samsung pay web checkout service enables you to integrate samsung pay into your desktop or mobile website's payment experience for an overview of the service, see features and user experience and service flow with the web checkout sdk, you can implement a payment checkout in the following ways on your website, using a javascript-based web development kit in your android app, using an android webview to display the checkout inside the app as a web page the following sections provide all the information you need to integrate the web checkout sdk prerequisites defines the requirements for using web checkout implement a web checkout integration gives step-by-step instructions for adding web checkout to your website using javascript, and managing the decrypted payment details received from samsung pay implement a webview integration gives step-by-step instructions for using web checkout in your android app via an android webview sample code offers an end-to-end sample code demonstrating a complete implementation from readiness check to payment result notification for a more detailed step-by-step example, see samsung pay web checkout code lab api reference supplies the necessary method and object details for your coding features and user experience web checkout allows you to provide samsung pay as a checkout option on your website for customers making a purchase by using web checkout, customers can make secure, seamless payments on your website with cards they have previously stored in samsung wallet key features of web checkout include cross-platform compatibility supports web-based payments on both desktop and mobile browsers, allowing customers to complete purchases seamlessly across devices flexible device linking customer can link their device to a web session by entering their samsung account email or scanning a qr code displayed on the checkout page enhanced transaction security payment credentials are securely generated and encrypted on the customer's mobile device before being transmitted to your website desktop experience the following figure illustrates the user experience of paying with samsung pay on a desktop computer when the customer is ready to pay for their purchase, they click samsung pay on your website's checkout page in their desktop browser the web checkout ui opens, prompting the customer to link the transaction to their mobile device the customer can either enter their samsung account email or scan the displayed qr code with their device once linked, the customer receives a push notification on their samsung wallet app when they open the notification, the samsung wallet app’s payment sheet displays the order details the customer selects a payment card and authorizes the payment via pin or biometrics after authorization, back on the desktop browser, the web checkout ui displays the "verified" screen and your website receives the secure payment credentials from samsung pay you submit the payment to your payment provider and your website displays a "payment successful" screen to the customer mobile experience the following figure illustrates the user experience of paying with samsung pay on a mobile device when the customer is ready to pay for their purchase, they taps samsung pay on your website's checkout page on their mobile device in a payment request pop-up, the customer taps pay to open the samsung wallet app displaying the order details the customer selects a payment card and authorizes the payment via pin or biometrics after authorization, your website receives the secure payment credentials from samsung pay you submit the payment to your payment provider and your website displays a "payment successful" screen to the customer service flow the following diagram illustrates the overall web checkout flow from the service point of view the customer clicks the samsung pay button on your website's checkout page the merchant initializes the samsung pay client, checks the samsung pay availability for the customer, and launches the payment flow by defining the transaction details the web checkout sdk creates the transaction in the samsung server the samsung server returns a response after completing the transaction creation desktop flow starts the web checkout sdk displays the device binding screen the customer scans the qr code or enters their samsung account email the web checkout sdk sends the device binding request to the samsung server the samsung server sends a push notification to the samsung wallet app the samsung server returns a response to the web checkout sdk the web checkout sdk displays a timer screen the samsung wallet app shows a push notification desktop flow ends mobile flow starts the web checkout sdk displays the payment request and the samsung pay button on your checkout page the web checkout sdk sends the intent to show the payment screen in the samsung wallet app mobile flow ends the samsung wallet app displays a payment sheet and lets the customer select their card the customer verifies the payment samsung wallet generates a payment credential samsung wallet uploads the payment credential to the samsung server the samsung server delivers the payment credential to the web checkout sdk the web checkout sdk returns the payment credential to the merchant the merchant processes the payment credential with their payment provider the merchant notifies the customer that the transaction is complete the merchant reports the payment result to the samsung server
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 class samsungpay java lang object samsungpaybase com samsung android sdk samsungpay v2 samsungpay public final class samsungpay extends samsungpaybase this class provides apis to get the samsung pay status on the device also, this class provides apis to activate samsung pay on the device partner apps must check the samsung pay status on the device before performing any card management or payment operation since api level 1 1 constructor summary constructors constructor description samsungpay android content context context, partnerinfo partnerinfo constructor to get the samsungpay instance the caller should set the valid serviceid in partnerinfo method summary all methodsinstance methodsconcrete methods modifier and type method description void activatesamsungpay api to bring the samsung pay app to a state in which cards can be added samsung pay might be either in stub only state or samsung account is not signed in state partner app checks the samsung pay status with getsamsungpaystatus statuslistener api if the status is #spay_not_ready and #extra_error_reason is #error_spay_setup_not_completed, partner app can call this api to launch samsung pay and user can sign in to the app void getsamsungpaystatus statuslistener listener api to get the samsung pay status on the device partner issuers, merchants, and so on applications must call this api to check the current state of samsung pay before doing any operation void getwalletinfo list<string> keys, statuslistener listener api to get the requested wallet information from samsung pay partner app can use this information to uniquely identify the user and samsung pay app on a particular device void gotoupdatepage api to go to samsung pay update page partner app checks the samsung pay status with getsamsungpaystatus statuslistener api if the status is #spay_not_ready and #extra_error_reason is #error_spay_app_need_to_update, partner app can call this api to go to update samsung pay app if samsung pay app version is same or bigger than 2 1 00, it goes to "about samsungpay" menu if samsung pay app version is lower than 2 1 00 or kr device, it launches samsung pay app main screen methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait constructor details samsungpay public samsungpay android content context context, partnerinfo partnerinfo constructor to get the samsungpay instance the caller should set the valid serviceid in partnerinfo partnerinfo is passed to samsung pay for partner verification context ct = activity; // or context ct = service; // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; samsungpay samsungpay = new samsungpay ct, pinfo ; parameters context - activity context or service context partnerinfo - partner information throws nullpointerexception - thrown if parameters are null since api level 1 1 method details getsamsungpaystatus public void getsamsungpaystatus statuslistener listener api to get the samsung pay status on the device partner issuers, merchants, and so on applications must call this api to check the current state of samsung pay before doing any operation // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; samsungpay samsungpay = new samsungpay context, pinfo ; samsungpay getsamsungpaystatus new statuslistener { @override public void onsuccess int status, bundle data { // success case if status == spay_ready { log d tag, "samsung pay is ready on the device" ; // perform your operation } else if status == spay_not_ready { // samsung pay is supported but not fully ready // if extra_error_reason is error_spay_app_need_to_update, // call gotoupdatepage // if extra_error_reason is error_spay_setup_not_completed, // call activatesamsungpay } else if status == spay_not_allowed_temporally { log d tag, "samsung pay is not allowed temporally" ; // if extra_error_reason is error_spay_connected_with_external_display, // guide user to disconnect it } else { // samsung pay is not supported on this device log d tag, "device does not support samsung pay" ; } } @override public void onfail int errorcode, bundle errordata { log e tag, "onfail callback is called, errorcode " + errorcode ; // to get more reason of the failure, // check some extra error codes in the errordata bundle such as samsungpay extra_error_reason if provided } } ; parameters listener - callback through which the result is provided on success, samsung pay status code is provided via statuslistener onsuccess int status, bundle data if samsung pay is ready to be used, samsungpay#spay_ready will be returned otherwise, samsungpay#spay_not_ready or samsungpay#spay_not_supported or samsungpay#spay_not_allowed_temporally can be returned with samsungpay#extra_error_reason from bundle also, partner can get extra information from bundle data bundle keys if provided bundle values #extra_country_code device country code iso 3166-1 alpha-2 #extra_member_id string memberid for korean issuers only on any failure, the failure code is provided via statuslistener onfail int errorcode, bundle errordata note please refer spaysdk common_status_table in detail throws nullpointerexception - thrown if the callback passed is null since api level 1 1 gotoupdatepage public void gotoupdatepage api to go to samsung pay update page partner app checks the samsung pay status with getsamsungpaystatus statuslistener api if the status is #spay_not_ready and #extra_error_reason is #error_spay_app_need_to_update, partner app can call this api to go to update samsung pay app if samsung pay app version is same or bigger than 2 1 00, it goes to "about samsungpay" menu if samsung pay app version is lower than 2 1 00 or kr device, it launches samsung pay app main screen // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; samsungpay samsungpay = new samsungpay context, pinfo ; samsungpay gotoupdatepage ; since api level 1 2 activatesamsungpay public void activatesamsungpay api to bring the samsung pay app to a state in which cards can be added samsung pay might be either in stub only state or samsung account is not signed in state partner app checks the samsung pay status with getsamsungpaystatus statuslistener api if the status is #spay_not_ready and #extra_error_reason is #error_spay_setup_not_completed, partner app can call this api to launch samsung pay and user can sign in to the app // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; samsungpay samsungpay = new samsungpay context, pinfo ; samsungpay activatesamsungpay ; since api level 1 1 getwalletinfo public void getwalletinfo list<string> keys, statuslistener listener api to get the requested wallet information from samsung pay partner app can use this information to uniquely identify the user and samsung pay app on a particular device // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring samsungpay extra_issuer_name, "issuer name" ; bundle putstring samsungpay partner_service_type, samsungpay servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; samsungpay samsungpay = new samsungpay context, pinfo ; // bundle keys added to get wallet information from samsung pay // this information can be delivered to the partner server for eligibility check arraylist<string> keys = new arraylist<> ; keys add samsungpay wallet_user_id ; keys add samsungpay device_id ; samsungpay getwalletinfo keys, new statuslistener { @override public void onsuccess int status, bundle walletdata { // log d tag, "dowalletinfo onsuccess callback is called" ; // for visa, deviceid can be set to "clientdeviceid" as defined by visa string deviceid = walletdata get samsungpay device_id ; // for visa, walletuserid can be set to "clientwalletaccountid" as defined by visa string walletuserid = walletdata get samsungpay wallet_user_id ; } @override public void onfail int errorcode, bundle errordata { log e tag, "onfail callback is called, errorcode " + errorcode ; // to get more reason of the failure, // check some extra error codes in the errordata bundle such as samsungpay extra_error_reason if provided } } parameters keys - key list to get wallet information if the list is empty, all possible key values are returned the possible keys are #wallet_dm_id #device_id #wallet_user_id listener - callback through which the result is provided on success, statuslistener onsuccess int status, bundle data is invoked with wallet information the success code can be one of the following codes with bundle data status bundle keys bundle values usage vts mdes #error_none samsungpay#wallet_dm_id string device management id n/a paymentappinstanceid = device_id + padding "00" + wallet_dm_id *if you need 'paymentappinstanceid', you can generate it as above samsungpay#device_id string device id clientdeviceid samsungpay#wallet_user_id string wallet user id clientwalletaccountid on any failure, the error code is provided via statuslistener onfail int errorcode, bundle errordata note please refer spaysdk common_status_table in detail throws nullpointerexception - thrown if parameters are null since api level 1 2 samsung electronics samsung pay sdk 2 23 00 - jul 06 2026
tutorials mobile
blogas businesses strive to enhance their mobile payment capabilities and provide seamless transaction experiences to users, integrating third-party payment solutions like samsung pay has become increasingly common. however, amid the excitement of implementing these solutions, developers often encounter challenges and pitfalls that can hinder the integration process and impact the overall user experience. in this blog, we show some of the most common mistakes developers make when integrating the samsung pay sdk, and offer practical insights and best practices to overcome these hurdles and ensure successful implementation and testing. pitfall 1: using an unofficial email id to implement the samsung pay sdk, the first step is to establish a partnership between your company and samsung. when submitting a partnership request, do so using your company's official email domain. this precaution is crucial, as partnership requests originating from non-official email addresses are prone to rejection by the samsung relationship manager. pitfall 2: providing the wrong issuer name while creating your service while creating a service for the push provisioning feature, you have to add the issuer names, meaning the names of your financial institution or bank. you must make sure to provide the correct names that have been registered with the card networks such as visa, mastercard and so on. if incorrect names are provided, the getallcard() api returns an empty list even though the card has already been added to the samsung wallet. to confirm your issuer name, first add your card to the samsung wallet application. tap on the card in the wallet application, open the more menu, and select customer services. the correct issuer name is listed on the “customer services” pane. to correct your issuer name for services that you have created: select my projects > service management. select the service name to open the service details page. select edit info. you can delete the incorrect issuer name and enter a new one. pitfall 3: using service id with an invalid effective date a common error that occurs during sdk integration is the error_expired_or_invalid_debug_key (-310) error. this error occurs in two cases: using a newly created service id without generating an expiration date of the service: after creating a service, if you check the edit info of the service details page, you will find that the debug effective data is blank. hence, you have to generate a date right after creating the service. using a service id with an expired debugging date: the service id provided by samsung pay portal remains valid for 90 days. after that time, the service expires. therefore, you must generate a date for debugging every 90 days. to generate or extend the validity date of the service: select my projects > service management. select the service name to open the service details page. select edit info. click generate new date. provide a samsung account for testing the application. this account is placed on the allow list for testing. click generate. the new expiration date of your service appears on the page. remember to extend the date after 90 days if you continue testing your application past that point. pitfall 4: configuring the release service with insufficient information it is essential to include the apk file when setting up the release service. failure to include the apk file will result in samsung pay’s relationship manager rejecting the service, leading to delays in the release process. additionally, ensure that you have correctly integrated the appropriate service id into your release application. pitfall 5: testing your application with a mismatched configuration samsung wallet uses the service id, package name, and apk signature for partner verification. if you test your application with an apk signature different from the one already registered in the samsung pay portal, samsung pay recognizes that the apk signature is inconsistent with the service id and produces the error code -6 (not_allowed). in conclusion, navigating the integration of the samsung pay sdk can present you with many challenges. but, armed with the knowledge shared here, you can steer clear of some potential pitfalls and ensure a smoother implementation process. by prioritizing thorough testing, adhering to best practices, and maintaining clear communication with samsung's support channels, you can mitigate risks and deliver a seamless payment experience to users.
Ummey Habiba Bristy
Develop Samsung Pay
docprerequisites for samsung pay sdk for android to use the samsung pay sdk for android, make sure to meet the following prerequisites the device running your app uses the correct android version you have registered a service through the samsung pay portal this includes obtaining a valid service id and type required for integration samsung pay sdk for android is added to your project samsung pay api level is configured check the device android version the samsung pay sdk for android is designed exclusively for samsung mobile devices that support samsung pay run android lollipop 5 1 android api level 22 or later if you are implementing the card transactions use case managing customer's in-app payments through samsung pay , the android 6 0 m android api level 23 or later is required you need to check the device's android version and hide the samsung pay button if the device version is too low merchant apps using the samsung pay sdk for android version 1 5 must use the getsamsungpaystatus method if a device is running android lollipop 5 1 android api level 22 or earlier, the method returns the spay_not supported status code merchant apps using the samsung pay sdk for android version 1 4 or earlier not recommended must manually check the android os version running their app import android os build; // in-app payment supported on android m or above // check android version of the device if build version sdk_int < build version_codes m { // hide samsung pay button } add the samsung pay sdk for android to your project to use the samsung pay sdk for android if you do not have one set up already, download and install the ide of your choice android studio is recommended download the samsung pay sdk for android the sdk package has the following directory structure folder content docs javadoc api reference documentation containing descriptions of the apis included in the sdk libs samsungpay jar sdk java archive file that contains the samsung pay apis to be used by your app samples sample apps demonstrating how you can implement samsung pay apis in your app configure your ide to integrate samsung pay with your app add samsungpay jar to the libs folder of your android project enter the samsung pay dependency in the build gradle script dependencies { compile files 'libs/samsungpay jar' } import the sdk package into your code import com samsung android sdk samsungpay v2; if your app has any issues related to proguard code optimization, implement the following rules in debug mode dontwarn com samsung android sdk samsungpay ** -keep class com samsung android sdk ** { *; } -keep interface com samsung android sdk ** { *; } -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level -keepresourcexmlelements manifest/application/meta-data@name=debug_mode -keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key if you are using dexguard to secure your source code, apply the following additional rule -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level starting from android r os if the android os target sdk version is 30 , include the following <queries> element in the androidmanifest xml file <?xml version="1 0" encoding="utf-8"?> <manifest xmlns android="http //schemas android com/apk/res/android" xmlns tools="http //schemas android com/tools" package="xxx xxx xxx xxx"> <queries> <package android name="com samsung android spay" /> <package android name="com samsung android samsungpay gear" /> </queries> configure the samsung pay api level starting from the samsung pay sdk for android version 1 4, enhanced version control management improves backward compatibility and handles api dependency based on country and service type for example, if you integrate the latest sdk ― for example, version 2 22 ― but continue to only use apis based on version 1 4, your app remains compatible with the samsung wallet apps supporting version 1 4 without needing to upgrade the samsung wallet app the enhanced version control works as follows every api starting from the samsung pay sdk for android version 1 4 has an api level assigned to it, reflecting the sdk version set this level in the metadata section of your app’s androidmanifest xml file you can filter the samsung pay sdk for android’s javadoc reference by api level to determine your app's minimum api level based on the sdk features you are using the minimum possible api level is 1 4 setting the minimum api level in your androidmanifest xml file allows your app to use the defined api level without having to trigger an upgrade of the samsung wallet app on the customer’s device to set the minimum api level, implement the following code snippet in your androidmanifest xml file <application> <meta-data android name="spay_sdk_api_level" android value="2 22" /> // most recent sdk version is recommended as the api level to leverage the latest apis, but for russia, 2 17 needs to be set instead </application>
announcement
blogintroducing a smarter way to prepare for your next event—weather insights, right where your ticket lives. the problem every event-goer knows we've all been there. you're heading to an outdoor concert, a weekend football match, or a long-awaited festival. you have your ticket ready in samsung wallet. you arrive at the venue—and then it hits you, literally. rain you didn't plan for. wind that turns your umbrella inside out. heat you didn't dress for. the forecast was out there, sure—buried in a separate weather application you forgot to check. or maybe you glanced at it last night, but things changed by morning. the truth is, weather information and event details have always lived in two different worlds. until now. meet weather forecast in samsung wallet samsung wallet is closing the gap between knowing your plans and being prepared for them. with our newest feature—weather forecast—real-time weather information is now embedded directly into your ticket details page. no application switching. no guesswork. just the forecast you need, precisely when and where it matters most. powered by the weather channel (twc), one of the world's most trusted weather data providers, this feature automatically pulls the forecast for your event's exact location and time—so you always know what to expect before you step out the door. how it works the weather forecast integration is seamless by design. here's what you'll see when you open a ticket in samsung wallet: • weather at a glance. a clean, lightweight widget appears right beneath your event's location details, showing the expected conditions at event start time: temperature, weather icon (sun, rain, snow, storm, and more), and the event location name. • forecast for your event time. not the current weather. the weather when your event starts. whether it's a 7 pm concert tonight or a saturday afternoon game three days from now, you'll see the forecast tailored to the moment that matters. • severe weather alerts. in supported regions (including the us, canada, japan, europe, australia, and south korea), government-issued severe weather warnings appear directly on the widget. if there's a storm advisory or heat warning, you'll know before you go. • full forecast, one tap away. want the hour-by-hour breakdown? a single tap on the widget opens the weather channel's detailed forecast page—giving you the complete picture for the entire day of your event. why it matters this isn't just a nice-to-have. weather forecast on your tickets is a meaningful upgrade to how you experience events: • be prepared, not surprised. know whether to pack an umbrella, grab a jacket, or slather on sunscreen—before you leave the house, not after you arrive. • everything in one place. your ticket, your venue details, and now your weather forecast—all on one screen. no more bouncing between applications and trying to remember if you checked the right city. • timely, not intrusive. the weather widget appears automatically one week before your event and stays current with every refresh. it's there when you need it and gone once the event is over. no clutter, no noise. • smart weather alerts tracking. the feature specifically checks for governmental weather alerts on the day of your event and up to 4 hours after the event end time—so you're alerted to the conditions that matter most for getting there and getting home. built for the real world life doesn't always go perfectly, and neither do data connections. that's why weather forecast is designed with graceful fallbacks at every step: • no internet connection? you'll see a clear message that weather data is unavailable—not a blank space or a loading spinner. • missing venue location? a simple "check the weather" link still lets you manually look up conditions. • api hiccup? a friendly prompt guides you to check the forecast directly on the weather channel's site. • multi-day event? you'll see the forecast for the start time before the event begins, then current conditions during the event days. • event over? the widget disappears automatically. clean and simple. privacy by design here's something you'll appreciate: samsung wallet does not use your device's gps or collect any personal location data for this feature. the forecast is based solely on the event's venue information—the city and location already associated with your ticket. no tracking, no data sharing with third parties. the partner website opens only when you choose to tap. your privacy stays intact. global reach, local precision weather forecast in samsung wallet is rolling out globally—available to users in every market where samsung wallet operates (excluding china). whether you're attending a k-pop concert in seoul, a premier league match in london, or a broadway show in new york, your ticket now comes with a built-in weather briefing. boarding passes: arrive prepared at your destination the weather forecast feature isn't just for event tickets. boarding passes are also supported. wherever your journey takes you, samsung wallet keeps you informed. traveling by air? the weather widget on your boarding pass works the same way as it does on event tickets—but with a focus on your destination. before takeoff, check the forecast for your arrival city so you know whether to grab a coat or pack an umbrella before you land. and here's the smart part: after your flight's arrival time, the widget continues showing current weather conditions at your destination until the ticket expires. flight delayed? no problem. you can still check the real-time weather at your arrival city directly from your boarding pass, without opening another app. whether you're landing in rainy london or sunny barcelona, you'll step off the plane ready for what awaits. more than just tickets: a vision while the first release focuses on event tickets and boarding passes, the architecture is built for expansion. imagine checking the weather for your hotel reservation, your restaurant booking, or your hiking trip—all from within samsung wallet. this is the first step toward making samsung wallet not just the place where you store your plans, but the place where you prepare for them. for partners: zero effort, instant value here's the best part for ticketing partners and event organizers: you don't need to do anything. the weather forecast feature is implemented automatically—no integration work, no api calls, no additional steps required on your end. the only thing that matters is that the event location is clearly described in the ticket. as long as the venue name, city, and address are properly included in the ticket details (geographic coordinates are always the best solution), samsung wallet will automatically retrieve the location information and use it to fetch the accurate weather forecast for your event. that's it. samsung wallet handles everything else—from fetching real-time weather data from the weather channel to displaying it beautifully in the ticket details. your users get the added value of weather insights, and you get an enhanced ticket experience without any development effort. the bottom line samsung wallet has always been about convenience—keeping your cards, tickets, and passes in one secure place. with weather forecast, it becomes something more: your personal event companion, helping you arrive ready for whatever the sky has in store. no more arriving drenched. no more shivering in the stands. no more scrambling for weather information across multiple applications. just open your ticket, check the forecast, and go—confident and prepared. weather forecast in samsung wallet—because the best events are the ones you're ready for. availability: rolling out globally starting in late july 2026 with the samsung wallet update, excluding china. powered by: the weather channel supported ticket types: event tickets and boarding passes, with more coming soon. severe weather alerts: available in 36 countries : austria, australia, belgium, bulgaria, canada, croatia, cyprus, czech republic, denmark, estonia, finland, france, germany, greece, hungary, iceland, ireland, israel, italy, japan, latvia, lithuania, luxembourg, netherlands, norway, poland, portugal, romania, slovakia, slovenia, south korea, spain, sweden, switzerland, united kingdom, usa
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
Learn Code Lab
codelabintegrate samsung pay sdk flutter plugin into merchant apps for in-app payment objective learn how to integrate in-app payment with your flutter-based merchant apps using samsung pay sdk flutter plugin partnership request to use the samsung pay sdk flutter plugin, you must become an official samsung partner once done, you can fully utilize this code lab you can learn more about the partnership process by visiting samsung pay in samsung developers overview the samsung pay sdk flutter plugin allows developers to use samsung wallet features in flutter applications it is the wrapper of samsung pay sdk, which is an application framework for integrating samsung wallet features on galaxy devices the samsung pay sdk flutter plugin offers in-app payment feature that gives customers the opportunity to pay for products and services with samsung wallet set up your environment you will need the following samsung wallet app version 5 6 53, 5 8 0 samsung pay sdk flutter plugin android studio latest version recommended java se development kit jdk 11 or later flutter sdk a compatible galaxy device with android q 10 0 or android api level 29 or later android os versions noteflutter sdk must be installed and set up properly when developing flutter applications after downloading, follow the installation guide appropriate to your operating system after proper installation and setup, configure your android studio to include the flutter plugin for intellij check this editor guide for the detailed steps sample code here is a sample code for you to start coding in this code lab download it and start your learning experience! in-app payment flutter plugin sample code 20 4 mb start your project in android studio, click open to open an existing project locate the flutterinapppayment project from the directory, and click ok go to file > settings > languages & frameworks > flutter to change the flutter sdk path input the directory path where your flutter sdk is installed and click apply install the plugin and configure the api level add samsungpaysdkflutter_v1 01 00 folder in the project go to samsungpaysdkflutter_v1 01 00 > pubspec yaml file and click on pub get in right side of the action ribbon or run flutter pub get in the command line next, go to flutterinapppayment > pubspec yaml and add the samsungpaysdkflutter_v1 01 00 plugin under dependencies samsung_pay_sdk_flutter path /samsungpaysdkflutter_v1 01 00 warningbe careful of line alignment of pubspec yaml file, as the indentations indicate the structure and hierarchy of the data from the terminal, run flutter pub get command or click on pub get in the right side of the action ribbon configure the api level samsung pay sdk flutter plugin supports samsung pay sdk version 2 18 or later hence, we must set a valid api version latest version 2 19 of samsung pay sdk go to android > app > src > main > androidmanifest xml and add the api level in the meta-data of application tag <meta-data android name="spay_sdk_api_level" android value="2 19" /> // most recent sdk version is recommended to leverage the latest apis add the samsung pay button go to the main project, flutterinapppayment project > lib > main dart here, the ui is created using the build widget this widget shows the sample item information such as image, name, and price add a bottomnavigationbar before the end of the body of scaffold to display the samsung pay button bottomnavigationbar visibility visible isspaystatusready, child inkwell ontap { requestpaymentwithsamsungwallet ; }, child image asset 'assets/pay_rectangular_full_screen_black png' , , , check samsung pay status in main dart > myhomepage class, create an instance of samsungpaysdkflutter with valid partnerinfo service id and service type during onboarding, the samsung pay developers site assigns the service id and service type these data are used for partner verification static final samsungpaysdkflutterplugin = samsungpaysdkflutter partnerinfo serviceid service_id, data {spaysdk partner_service_type servicetype inapp_payment name} ; notethe service id is already provided in the sample code for this code lab however, this service id is for test purposes only and cannot be used for an actual application or service to change the service id in your actual application, the value of the variable service_id should be modified to check whether samsung pay is supported on your galaxy device, call the getsamsungpaystatus api and change the samsung pay button visibility accordingly in checksamsungpaystatus method, apply the following code void checksamsungpaystatus { //update ui according to samsung pay status myhomepage samsungpaysdkflutterplugin getsamsungpaystatus statuslistener onsuccess status, bundle async { if status == "2" { setstate { isspaystatusready = true; } ; } else { setstate { isspaystatusready = false; } ; _showtoast context,"spay status not ready" ; } }, onfail errorcode, bundle { setstate { isspaystatusready = false; } ; _showtoast context,"spay status api call failed" ; } ; } inside initstate method, call checksamsungpaystatus to ensure that getsamsungpaystatus api is called before any other api is called checksamsungpaystatus ; notethe getsamsungpaystatus api must be called before using any other feature in the samsung pay sdk flutter plugin create a custom payment sheet samsung pay sdk flutter plugin offers a custom type payment sheet called customsheet to customize the ui with additional payment related data here, create customsheet using the following controls amountboxcontrol it is a mandatory control to build a customsheet it provides the monetary details of the transaction addresscontrol it is used to display the billing and shipping address in makeamountcontrol method, add items and total price to build amountboxcontrol amountboxcontrol additem strings product_item_id, "item", 1199 00, "" ; amountboxcontrol additem strings product_tax_id, "tax", 5 0, "" ; amountboxcontrol additem strings product_shipping_id, "shipping", 1 0, "" ; amountboxcontrol setamounttotal 1205 00, spaysdk format_total_price_only ; in makebillingaddress method, add the following code to create billingaddresscontrol set sheetitemtype as zip_only_address while creating billingaddresscontrol to get the zip code as we are expecting to get the user's billing address from samsung wallet, set sheetupdatedlistener addresscontrol billingaddresscontrol = addresscontrol strings billing_address_id, sheetitemtype zip_only_address name ; billingaddresscontrol setaddresstitle strings billing_address ; billingaddresscontrol sheetupdatedlistener = billinglistener; return billingaddresscontrol; notefrom samsung pay sdk version 2 19 onwards, users can only add zip code as their billing address only the zip code is fetched from the user's samsung wallet instead of the full billing address implement this listener in makeupcustomsheet method to update the custom sheet when the user updates their billing address sheetupdatedlistener sheetupdatedlistener = sheetupdatedlistener onresult string controlid, customsheet sheet { if controlid == strings billing_address_id { var addresscontrol = sheet getsheetcontrol controlid as addresscontrol; setstate { postalcode = addresscontrol address! postalcode; } ; } myhomepage samsungpaysdkflutterplugin updatesheet sheet ; } ; create the shipping address in buildshippingaddressinfo method to add it in shipping addresscontrol this is the shipping address from the merchant app maddress = address addressee "jane smith", addressline1 "123 main st", addressline2 "suite 456", city "anytown", state "st", countrycode "usa", postalcode "12345", phonenumber "+1 555-123-4567", email "example@email com" ; add this address in makeshippingaddress method shippingaddresscontrol address = buildshippingaddressinfo ; finally, complete the makeupcustomsheet method by adding amountboxcontrol, billingaddresscontrol, and shippingaddresscontrol customsheet addcontrol makeamountcontrol ; customsheet addcontrol makebillingaddress sheetupdatedlistener ; customsheet addcontrol makeshippingaddress ; create a transaction request to start the payment process, the merchant app should create a transaction request with payment information in maketransactiondetailswithsheet method, add the merchant name and custom sheet in customsheetpaymentinfo customsheetpaymentinfo customsheetpaymentinfo = customsheetpaymentinfo merchantname "in app payment flutter app", customsheet makeupcustomsheet ; your merchant app must fill the following mandatory fields in customsheetpaymentinfo customsheetpaymentinfo merchantid = "123456"; customsheetpaymentinfo setordernumber "amz007mar" ; customsheetpaymentinfo setmerchantcountrycode "us" ; customsheetpaymentinfo addressinpaymentsheet = addressinpaymentsheet need_billing_send_shipping; request payment with a custom payment sheet the startinapppaywithcustomsheet api is called to request payment using a custom payment sheet in samsung pay this api requires customsheetpaymentinfo and customsheettransactioninfolistener first, implement this listener before starting the payment customsheettransactioninfolistener transactionlistener { customsheettransactioninfolistener customsheettransactioninfolistener = customsheettransactioninfolistener oncardinfoupdated paymentcardinfo paymentcardinfo, customsheet customsheet { myhomepage samsungpaysdkflutterplugin updatesheet customsheet ; }, onsuccess customsheetpaymentinfo customsheetpaymentinfo, string paymentcredential, map<string, dynamic>? extrapaymentdata { print "payment success" ; }, onfail string errorcode, map<string, dynamic> bundle { print "payment failed" ; } ; return customsheettransactioninfolistener; } lastly, call startinapppaywithcustomsheet api to start the payment in the requestpaymentwithsamsungwallet method void requestpaymentwithsamsungwallet { myhomepage samsungpaysdkflutterplugin startinapppaywithcustomsheet maketransactiondetailswithsheet , transactionlistener ; } run the app build the app by running flutter build apk --debug in the command line or going to build > flutter > build apk deploy the app on the device test it by clicking on samsung pay button to proceed with the payment transaction to thoroughly test the sample app, you must add at least one payment card to the samsung wallet app you're done! congratulations! you have successfully achieved the goal of this code lab now, you can integrate in-app payment with your flutter app by yourself! if you are having trouble, you may download this file in-app payment flutter plugin complete code 62 0 mb to learn more, explore samsung pay
Develop Samsung Browser
docweb payments integration guide overview to help standardize and streamline how payments are done on the web, the worldwide web consortium w3c has introduced a payment request api to provide an interface between a merchant web page and a mobile payment app, like samsung pay, to facilitate payment transactions samsung internet browser leverages the w3c payment request api to support samsung pay as a payment method for web purchases chrome also supports a samsung pay web payment method why integrate samsung pay into your website? samsung pay is accepted at more retail locations than any other mobile payment service available because of its unique ability to transact with newer nfc-supported payment terminals and legacy payment terminals it continues to enjoy the best user reviews among mobile payment apps now available for mobile website integration, samsung pay is secure, easy to set up, simple to use, and pre-installed on all new samsung galaxy-class smartphones when integrated with your website, samsung pay presents your users with a common checkout process that leverages samsung pay’s secure purchase authentication technology, eliminating manual entry or re-entry of card details and shipping destinations checkout is streamlined, conversions are maximized, and the exposure of sensitive data is kept to the absolute minimum simplifying the transaction process the benefits of the new process, certainly from an end-user perspective, is that the previous tedium ― request, authorization, payment, and result ― can now be handled in a single step for the web developer, it entails a single javascript api call for samsung pay users, there’s no change at all in the way a payment card is selected and authenticated after selecting the desired merchandise from the merchant’s web site, the user initiates checkout, selects samsung pay as the preferred payment method, authenticates with a fingerprint or pin, and voila ― payment complete that’s the user experience at its most basic when properly implemented, the api also supports editing the billing/shipping address in samsung pay and selecting a different enrolled card before approving the transaction with a fingerprint scan or entering a pin in terms of convenience, it’s a remote shopper’s dream ― no complicated, input-intensive forms to fill out, no fumbling for a plastic card to enter the account number, card expiration, and security code, and no worrying that someone other than the legitimate cardholder is attempting to make the payment meanwhile, samsung pay’s tokenized payload securely protects the transaction from intercept and replay attacks about this guide intended for web developers with a working knowledge of javascript and json, this guide takes you through the complete process of onboarding as a samsung pay merchant partner, creating/registering the w3c service for your domain, adding the w3c payment request object to your website, then testing and releasing your merchant website offering samsung pay as a payment method let's get started determining your gateway integration mode the api methods for integrating samsung pay with your website depend on the type of payment token your payment gateway pg handles — either gateway tokens or network tokens samsung pay supports requests for both types for instance, if stripe is your pg, you will want to request a gateway token from samsung pay on the other hand, if you’re using first data, you’ll want to request an encrypted network token bundle, for which you handle the token decryption yourself or work with the pg first data in this case to handle decrypting the token bundle the process begins when your merchant website makes a payment request and passes all required information to the browser, which then determines compatibility between the accepted payment methods for your website and the methods apps installed on the target device let’s take a brief look at how each integration mode — gateway token and network token — works with samsung pay gateway token mode although samsung pay doesn’t process the payment, your merchant website will still need to invoke the appropriate payment gateway apis to charge and process the token returned by your pg hence, when samsung pay returns a gateway token from stripe, for example, the recommended flow looks like this user selects samsung pay as the payment method at checkout in the merchant's website and the samsung pay app requests partner verification from the samsung pay online payment server encrypted payment information and the partner id are passed to the samsung-pg interface server samsung-pg interface server sends a transaction authorization request to the pg on behalf of the merchant; pg authenticates the partner id before generating a transaction reference id samsung-pg interface server returns the payment token to the pg i e , the gateway token it received from the samsung pay app in step 2 pg continues payment processing with the acquirer and payment network the result approved/declined is returned to the merchant website on the device for display to the user in this mode, samsung pay makes a call to your pg on your behalf and returns a chargeable gateway token network token mode under network token mode, the samsung pay api returns an encrypted network token bundle, which you can then either decrypt yourself or leverage the apis of your pg first data, for example to handle decryption and charge the token user selects samsung pay as the payment method at checkout in the merchant's website and the samsung pay app requests partner verification from the samsung pay online payment server encrypted payment information is passed from the samsung pay app to the pg through the merchant app via the pg sdk applying the merchant's private key, pg decrypts the payment information structure and processes the payment through the acquirer and payment network upon receiving authorization or rejection, pg notifies the merchant website through its pg sdk to simplify integration of network tokens, you can pass the encrypted payload directly to your pg and let it handle decryption in general, decrypting the payload yourself is more complex and involves private key management see your particular pg’s documentation for details once you determine which mode your pg supports, you're ready to register with the portal first, however, there are a number of prerequisites you'll need to satisfy prerequisites registering with the samsung pay developers portal and adapting the appropriate payment request apis for your website in accordance with the guidance contained herein will help to ensure a successful implementation to that end, the following requirements apply release contents minimum samsung pay app version 2 8 xx minimum samsung internet browser version 5 4 minimum chrome browser version 61 supported device models samsung galaxy-class smartphones running minimum version of the wallet app and browser supported payment gateways pgs view the most current list in the portal's payment gateway drop-down menu in service create/edit mode see step 5 under registering your domain for the w3c service registering with the portal through the samsung pay developers portal you can access valuable resources to help you manage the samsung pay features you incorporate into you partner app, including the ability to create multiple samsung pay service groups so you can use different services without the need to create multiple accounts invite co-workers to the portal to help you manage samsung pay features for your website register your website with samsung pay configure your samsung pay w3c service s to create a member account on the samsung pay developers portal open a browser like chrome, go to https //pay samsung com/developers, click sign up and confirm/acknowledge that you accept the samsung pay terms and conditions and understand the privacy policy, then do one of the following a if you already have a valid samsung account, click sign up and enter your samsung account id and password b if you do not have a samsung account, click create a samsung account to create one open the account activation email you receive and click the account activation link if you’re the first samsung pay member of your company to register, select the first option, click next, and complete a company and user profile if, on the other hand, you were given a samsung pay partner id by a co-worker, select the second option — my company is already registered — and enter your company’s partner id in the field provided, then click next after you receive notification by email that your membership is approved, typically within 2 business days, return to https //pay samsung com/developers, click sign in and enter your samsung account id and password for site access as a new member registering your domain for the w3c service your domain is the url associated with your website, whether in test or production the service type specifically associates w3c with your domain once you create the service, you will be prompted to configure the domain you want associated with it to create a new service go to my projects > service management and click create a new service select for test to define the service for initial integration with samsung pay, then click next select w3c mobile web payments as the service type and click next enter a service name and select “united states” as the service country select a payment gateway from the list of supported pgs if your payment gateway uses the network token mode, upload the certificate signing request csr you obtained from your pg supported formats are csr or pem contact your pg for details otherwise, key management is already established for pgs supporting samsung pay’s gateway token mode; hence, click connect with to create a new service connection with the pg and click ok enter the payment domain name s for your website in the service domain field and click add for example, if your domain is mywebstore com but the checkout page is hosted on the subdomain payments mywebstore com, you’ll need to enter payments mywebstore com as the service domain in the portal for each additional domain name, click add notewhen entering the domain name on the portal, do not include an https // prefix confirm your agreement with the terms and conditions, then click next adding w3c payment requests objects to your website in order to accept payments from samsung pay, your website must adhere to the w3c payment request api specification you can get started with the basics by completing the steps that follow and making the appropriate substitutions for your website step 1 feature detect prior making a w3c payment request, it’s wise to run a feature detect to ensure the browser in use supports the w3c payment request api if not, you should fall back to your traditional/normal checkout page example if window paymentrequest { // use payment request api } else { // fallback to traditional checkout window location href = ‘/checkout/traditional’; } step 2 create the paymentrequest constructor the first step is to create a paymentrequest object by calling the paymentrequest constructor, which has the following parameters methoddata – contains a list of payment methods that the website supports e g , visa, amex, samsung pay details – contains information about the shopping cart purchases e g , total, tax, fees, etc options – details pertaining to shipping address, user contact information, etc example var request = new paymentrequest methoddata, // required payment method data details, // required information about transaction options // optional parameter for things like shipping, etc ; step 3 add samsung pay to the methoddata parameter the methoddata parameter contains a list of payment methods supported by the merchant to support samsung pay, you’ll need to add it as a supported payment method notebasic-card is an optional supportedmethod for credit and debit cards saved in the browser, the card details of which are returned directly to the website from the browser before configuring this method, make sure your website and pg can handle generic payment information received from the browser and process with required pci compliance, if applicable see the [w3c basic card payment specification][7] for additional details be aware, however, that if you intend to support a branded samsung pay button, only samsung pay can be enabled as a payment method within the paymentrequest object; basic-card or any other payment method cannot be included if you already offer a generic payment request method, you can continue to do so — and include samsung pay as a payment method within that paymentrequest object from a user experience standpoint, the two distinct pathways look like this standard w3c implementation a standard w3c implementation adds samsung pay to your standard paymentrequest object as one of many supportedmethods available for user selection tapping checkout or its equivalent launches the standard browser payment sheet for user selection of the payment method and/or to add a debit/credit card to the list of options selecting samsung pay as the payment method and tapping pay launches the samsung pay payment sheet branded samsung pay implementation a branded implementation displays a "buy with samsung pay" button in place of your standard checkout button tapping the button will skip directly to the samsung pay payment sheet for authentication unless you specify paymentoptions if paymentoptions is not null, the browser payment sheet is launched see paymentoptions in step 7 for additional guidance first launching your website's checkout page is recommended for branded implementations this is because the samsung pay payment sheet only provides the user's billing address, which means your website will need to capture the user's preferred shipping address, where applicable for physical delivery of purchased goods if no shipping address and/or other options are needed, set the paymentoptions parameter to null as mentioned above, if you populate paymentoptions, the browser payment sheet is automatically launched keeping the foregoing implementations in mind, let's look at how to construct the methoddata argument for the network token mode and gateway token mode, respectively the fields in methoddata comprise supportedmethods – required; specifies https //spay samsung com/ i e , the samsung pay app and other methods suppored by your website data – values specific to the method; for samsung pay, these include version specifies the data structure being used by the merchant; should always be set to 1 until further notice required productid the service id obtained from the samsung pay partner portal required for partner verification; see step #8 under registering your domain for the w3c service merchantgatewayparameter this is the userid value registered with your pg required for gateway token mode in addition, userid should be set in the request parameter for mada token if a merchan request mada token, this field is mandatory as this filed should be included in the payload for mada token, there is a 15-character length limit paymentprotocol defaults to “protocol_3ds,” the only protocol currently supported by samsung pay optional allowedcardnetworks specifies the card brands/networks accepted by the merchant and supported by the pg required merchantname the name of the merchant to be displayed on the payment sheet; must be identical to the merchant name registered on the samsung pay partner portal required ordernumber unique value for merchant use as an external reference id optional isrecurring specifies transaction on subscription basis optional; default = false billingaddressrequired determines if a billing address must be filled-in by the user optional; default = false shown next are examples of the methoddata parameter for each of the supported token modes please note that samsung pay's w3c support for card brands is currently limited to mastercard, visa and american express discover is scheduled for support soon example – network token mode var methoddata = [ { supportedmethods ['https //spay samsung com'], data { 'version' '1', // always 1 until further notice 'productid' '2bc3e6da781e4e458b18bc', // service id from partner portal 'allowedcardnetworks' ['mastercard','visa'], 'merchantname' 'shop samsung demo ', // merchantname must be identical to merchant name on portal 'ordernumber' '1233123', } }] example – gateway token mode var methoddata = [ { supportedmethods ['https //spay samsung com'], data { 'version' '1', // always 1 until further notice 'productid' '7qr7h9ws1872bc3e6da781', // service id from partner portal 'merchantgatewayparameter' {"userid" "acct_ 17irf7f6ypzj7wor"}, 'allowedcardnetworks' ['mastercard','visa'], 'merchantname' 'shop samsung demo ', //merchantname must be identical with merchant name on portal 'ordernumber' '1233123', } }] step 4 fill out the transaction details parameter the details parameter contains information about the transaction there are two major components a total, which reflects the total amount and currency to be charged, and an optional set of displayitems that indicate how the final amount was calculated this parameter is not intended to be a line-item list, but is rather a summary of the order’s major components subtotal, discounts, tax, shipping costs, etc example var details = { displayitems [ { label "total of all items", amount { currency "usd", value "65 00" }, // us$65 00 }, { label "friends & family discount", amount { currency "usd", value "-10 00" }, // -us$10 00 pending true // the price is not yet determined } ], total { label "total", amount { currency "usd", value "55 00" }, // us$55 00 } } step 5 check eligibility to display samsung pay button if you do not support basic-card and you try to call show in step 6 when samsung pay or any other supportedmethod is not present on the device, the returned promise will reject with the following error domexception the payment method is not supported you can, however, check beforehand to see if the user has an available/supported method set up this is done with the canmakepayment method, which tells you whether the user has a payment method that can fulfill the current payment request example – canmakepayment const paymentrequest = new paymentrequest supportedpaymentmethods, transactiondetails, options ; // if canmakepayment isn’t available, default to assume the method is supported const canmakepaymentpromise = promise resolve true ; // feature detect canmakepayment if request canmakepayment { canmakepaymentpromise = paymentrequest canmakepayment ; } canmakepaymentpromise then result => { if !result { // the user does not have a supported payment method // todo redirect to traditional checkout flow return; } // todo the user has a payment - call show } catch err => { // todo either fall back to traditional checkout or call show } ; notebranded samsung pay buttons can be found on the [samsung pay developers][8] portal under the resources tab direct cdn links will be available soon step 6 call the show method to display the payment sheet the payment sheet can be activated by calling its show method this method invokes the browser’s native ui so the user can examine the details of the purchase, add or change the information, and submit it for payment a promise, indicated by its then method and callback function, resolves what will be returned when the user accepts or rejects the payment request example – show request show then function paymentresponse { // process paymentresponse here paymentresponse complete "success" ; } catch function err { console error "uh oh, something bad happened", err message ; } ; step 7 handle the paymentresponse once the user approves the payment request by verifying the payment option and shipping option if provided , the show method’s promise resolves, resulting in a paymentresponse object comprised of the following fields methodname string indicating the chose payment method e g , visa details dictionary containing information for methodname shippingaddress shipping address of the user, if requested shippingoption id of the selected shipping option, if requested payeremail email address of the payer, if requested payerphone telephone number of the payer, if requested payername name of the payer, if requested here, it’s important to remember that the response from the payment request api must be submitted by the merchant in accordance with the pg’s integration model and apis in all cases, the samsung pay response is encapsulated within the paymentresponse details parameter, which comprises the following fields paymentcredential – contains the payment credential information necessary for processing the transaction with the pg in network token mode, this field includes 3ds data in gateway token mode, it includes token information network token mode type use “s” version 1 0 0; standard for payment authentication aka mastercard securecode, verified by visa, and american express safekey data encrypted payload value gateway token mode reference token id reference status authorized or rejected/declined billingaddress – contains the billing address and related attributes for the cardholder, possibly including country [iso3166] alpha-2 code; canonical form is upper case for example, “us” addressline[n] most specific part of the address; can include a street name, a house number, apartment number, a rural delivery route, descriptive instructions, or a post office box number region top level administrative subdivision of the country; can be a state, a province, an oblast, or a prefecture city city/town portion of the address dependentlocality dependent locality or sub-locality within a city; fused for neighborhoods, boroughs, districts, or uk dependent localities postalcode postal code or zip code, also known as pin code in india sortingcode bank sorting code; for example, in the british and irish banking industries, the sort code is a six-digit number, is usually formatted as three pairs of numbers, for example 12-34-56, identifying both the bank and the branch where the account is held languagecode [bcp47] language tag for the address, in canonical form; used to determine the field separators and the order of fields when formatting the address for display organization organization, firm, company, or institution at this address recipient name of the recipient or contact person this member may, under certain circumstances, contain multiline information; for example, it might contain “care of” information phone telephone number of the recipient or contact person paymentinfo – contains the payment information, including card_last4digits last four digits of the card’s dpan cardbrand currently, either mastercard or visa ordernumber merchant’s unique external reference id supplied in the original request’s methoddata parameter if the user pays with a credit card using the basic-card method, then the details response returned directly to your website from the browser will contain cardholdername, cardnumber, expirymonth, expiryyear, cardsecuritycode, billingaddress example request show then paymentresponse => { var paymentdata = { // payment method string, e g “amex” method paymentresponse methodname, // payment details contains payment information details paymentresponse details /* request details depends on pg token mode network - e g , first data; or gateway - e g , stripe ---------------------------------------------------------|------------------------------------------------------| * gateway token mode |* network token mode | * “details” { |* “details { | * “paymentcredential” { |* “method” “3ds”, | * “reference” “tok_1asceoyf6ypzj7f8se6grp0i”, |* “paymentcredential” { | * “status” “authorized” |* “type” “s”, | * }, |* “version” “100”, | * |* “data” “long_encrypted_payload_value”, | * |* }, | *--------------------------------------------------------|------------------------------------------------------| * “paymentinfo” { * “card_last4digits” “1489”, * “cardbrand” “mastercard”, * “ordernumber” “1233123”, * “billingaddress” { * “country” “usa”, * “addressline” [“chhccy”, “hdyxych”], * “region” “ca”, * “city” “mountain view”, * “dependentlocality” “”, * “postalcode” “94043”, * “sortingcode” “”, * “languagecode” “en”, * “organization” “”, * “recipient” “”, * “phone” “” * } * } * } * */ }; return fetch ‘/validatepayment’, { method ‘post’, headers { ‘content-type’ ‘application/json’ }, body json stringify paymentdata } then res => { if res status === 200 { return res json ; } else { throw ‘payment error’; } } then res => { paymentresponse complete “success” ; }, err => { paymentresponse complete “fail” ; } ; } catch err => { console error “error, something went wrong”, err message ; } ; once payment information is received from samsung pay, the website should submit the payment information to the merchant’s pg for transaction processing the ui will show a spinner while the request takes place when a response is received, the website should call complete to close the ui the website is then free to show an order complete or order confirmation page for user feedback as previously mentioned, you can simplify integration of network tokens by passing the encrypted payload directly to your pg and letting it handle decryption in all cases, how you handle a submitted network token depends on the payment gateway refer to your particular pg’s documentation for details paymentoptions is an optional parameter in thepaymentrequest constructor depending on your particular requirements, you may want additional information, such as the user’s shipping address for physical goods purchased and contact details for guest users paymentoptions currently comprises the following requestpayername true if payer name is required; otherwise, false requestpayeremail true if payer email address is required; otherwise, false requestpayerphone true if payer telephone number is required; otherwise, false requestshipping true if shipping address is required; otherwise, false shippingtype available label options “shipping/pickup/delivery” for indicating to user; solely for display purposes example var options = { requestpayeremail false, requestpayername true, requestpayerphone false, requestshipping true, shippingtype "delivery" } noteif any of the elements listed above are set to true, the browser payment sheet is launched; otherwise, the samsung pay payment sheet is displayed putting it all together let’s assemble the various code blocks into a prototype to demonstrate the w3c payment request api in action function onbuyclicked { const samsung_pay = 'https //spay samsung com'; if !window paymentrequest { // paymentrequest api is not available - forwarding to legacy form based experience location href = '/checkout'; } // setup var supportedinstruments = [{ supportedmethods [ samsung_pay ], // 'https //spay samsung com' data { "version" "1", "productid" "2bc3e6da781e4e458b18bc", //service id from partner portal "allowedcardnetworks" ['mastercard','visa'], "ordernumber" "1233123", "merchantname" "shop samsung demo ", //merchant name in partner portal "merchantgatewayparameter" {"userid" "acct_17irf7f6ypzj7wor"}, "isrecurring" false, "billingaddressrequired" false, "paymentprotocol" "protocol_3ds" } }]; var details = { displayitems [{ label 'original donation amount', amount { currency 'usd', value '65 00' } }, { label 'friends and family discount', amount { currency 'usd', value '-10 00' } }], total { label 'total due', amount { currency 'usd', value '55 00' } }; var options = { requestshipping true, requestpayeremail true, requestpayerphone true, requestpayername true }; // initialization var request = new paymentrequest supportedinstruments, details, options ; // when user selects a shipping address request addeventlistener 'shippingaddresschange', e => { e updatewith details, addr => { var shippingoption = { id '', label '', amount { currency ‘usd’, value ‘0 00’ }, selected true}; // shipping to us is supported if addr country === 'us' { shippingoption id = 'us'; shippingoption label = 'standard shipping in us'; shippingoption amount value = '0 00'; details total amount value = '55 00'; // shipping to jp is supported } else if addr country === 'jp' { shippingoption id = 'jp'; shippingoption label = 'international shipping'; shippingoption amount value = '10 00'; details total amount value = '65 00'; // shipping to elsewhere is unsupported } else { // empty array indicates rejection of the address details shippingoptions = []; return promise resolve details ; { // hardcoded for simplicity if details displayitems length === 2 { details displayitems[2] = shippingoption; } else { details displayitems push shippingoption ; } details shippingoptions = [shippingoption]; return promise resolve details ; } details, request shippingaddress ; } ; // when user selects a shipping option request addeventlistener 'shippingoptionchange', e => { e updatewith details => { // there should be only one option do nothing return promise resolve details ; } details ; } ; // show ui then continue with user payment info request show then result => { // post the result to the server return fetch '/pay', { method 'post', credentials ‘include’, headers { 'content-type' 'application/json' }, body json stringify result tojson } then res => { // only if successful if res status === 200 { return res json ; } else { throw 'failure'; } } then response => { // you should have received a json object if response success == true { return result complete 'success' ; } else { return result complete 'fail' ; } } then => { console log 'thank you!', result shippingaddress tojson , result methodname, result details tojson ; } catch => { return result complete 'fail' ; } ; } catch function err { console error 'uh oh, something bad happened ' + err message ; } ; } document queryselector '#start' addeventlistener 'click', onbuyclicked ; refer to the official w3c integration specs for additional details and definition testing once you have the code saved and loaded, you’re ready to test be sure to test your website or test domain on a device running samsung internet browser and with the samsung pay wallet app already set up and ready to go in accordance with the prerequisites cited above if you use a separate subdomain for your test environment, be sure to add it as an eligible service domain for the service you configured under registering your domain for the w3c service remember that any/all subdomains for production must also be added to the service, up to a maximum of 10 service domains again, please note that samsung pay’s webpay api currently supports mastercard and visa only support for american express and discover is under development and will be available soon be sure to test using the samsung internet and chrome mobile browser apps to test select samsung pay as the payment method by clicking on the branded samsung pay button branded implementations or the samsung pay radio button standard w3c implementations this should launch the samsung pay payment sheet authenticate payment validate your results end to end isolate issues in the log, debug, and test again contact your samsung pay rm to coordinate assistance with troubleshooting recommended test cases check if the samsung pay is available in the payment option on the website verify samsung pay logo on browser sheet verify order summary on the payment sheet verify “edit” and “pay” buttons on payment sheet verify purchased item in the summary verify the billing address on the payment sheet change the billing address try to change the card in payment sheet when only one card is enrolled in samsung pay try to change the card when multiple cards is enrolled in samsung pay verify the payment amount verify the payment options verify the payment completion screen verify merchant name on the payment sheet verify merchant domain name on the payments sheet verify “cancel” and “pay” buttons on browser sheet try to make payment with large amount larger than max allowed amount and verify the behavior make a payment using samsung pay with a card already added for the merchant’s website basic-card verify transaction notification after w3c purchase verify transaction notification after refund set payment options for shipping address and verify that browser payment sheet launches and captures shipping address input/changes by user verify that the shipping cost is updated based on a shipping address change and is reflected in the updated total amount release once your tests are successful and you are satisfied with the results, take the following steps to ready your integrated with samsung pay website for release go to the samsung pay developers portaland create a new release service sharing identical attributes with the service you successfully tested a click on service management, then click create new service b select for release pictured , then click next c select w3c mobile web payments as the service type, then click next d enter a "release" service name and select "united states" as the service country e select united states as the service country f select your payment gateway from the drop-down menu, then click connect with for gateway token mode or provide a valid csr for network token mode g enter your service domain and click add for each additional domain name, click add remember, when entering domain names on the portal, do not include a "https"//" prefix h confirm your agreement with the terms and conditions, then click next retrieve the service id from the service details page and enter copy-paste it into your website's methoddata object in place of the current testing service id when your service is approved by your samsung pay rm — as indicated in the status column of your service management dashboard — you're ready to release your integrated website to the public send queries concerning service package approval to webpayment@samsungpay com
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.