Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
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 22 00 - nov 19 2024
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 class watchmanager java lang object samsungpaybase com samsung android sdk samsungpay v2 watchmanager all implemented interfaces apptoappconstants public final class watchmanager extends samsungpaybase implements apptoappconstants this class provides apis for watch management partner apps must check the samsung pay watch status on the device before performing any card management also, this class provides apis getting cards information, adding new card to samsung pay on watch, and so on since api level 2 5 field summary fields modifier and type field description static final string device_serial_num key to represent device serial number to generate the paymentappinstanceid static final int error_invalid_parameter this error indicates that the given parameter is invalid this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_spay_pin_lock_setup_canceled this error indicates that user canceled the pin lock setup partner app should ask user to setup pin for samsung pay gear static final int error_spay_watch_connection this error indicates that samsung pay watch plug-in can not connect with samsung pay watch partner app should ask user to check bluetooth connection or pairing static final int error_spay_watch_pay_progress this error indicates that samsung pay watch is in a process of payment static final int error_spay_watch_pin_lock_setup_canceled this error indicates that user canceled the pin lock setup partner app should ask user to setup pin for samsung pay watch static final int spay_watch_taking_log_for_report this error indicates that samsung pay watch is taking log for error report static final int spay_watch_update_is_ongoing this error indicates that samsung pay watch being updated fields inherited from interface com samsung android sdk samsungpay v2 apptoappconstants error_auth_code_expired, error_auth_code_invalid, error_auth_code_max_try_reached, error_auth_code_type_invalid, error_authentication_closed, error_authentication_failed, error_authentication_not_ready, error_authentication_timed_out, error_card_already_registered, error_card_idv_not_supported, error_card_not_supported, error_framework_internal, error_invalid_card, error_invalid_cardinput, error_max_card_num_reached, error_max_pan_provision_num_reached, error_server_reject, error_tsm_fail, error_verify_card, error_wallet_id_mismatch, extra_app2app_intent, extra_app2app_payload, extra_card_balance, extra_card_status_reason, extra_issuer_app_card_linked constructor summary constructors constructor description watchmanager android content context context, partnerinfo partnerinfo api to get the watchmanager instance the caller should set valid serviceid method summary all methodsinstance methodsconcrete methods modifier and type method description void activatesamsungpay api to bring the samsung pay on watch app to a state in which cards can be added samsung pay on watch might be samsung account is not signed in state partner app checks the samsung pay on watch 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 on watch and user can sign in to the app void addcard addcardinfo addcardinfo, addcardlistener listener api to add a card from partner app example issuer/bank app to samsung pay on watch partner app uses this api to add card to samsung pay on watch by providing the required card details void getallcards android os bundle cardfilter, getcardlistener listener api to get all the cards from samsung pay on watch for the given filter void getsamsungpaystatus statuslistener listener api to get the samsung pay on watch status on the device partner issuers applications must call this api to check the current state of samsung pay on watch before doing any operation void getwalletinfo list<string> keys, statuslistener listener api to get the requested wallet information from samsung pay on watch partner app can use this information to uniquely identify the user and samsung pay on watch app on a particular device void gotoupdatepage api to go to samsung pay on watch update page partner app checks the samsung pay on watch 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 on watch app methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait field details device_serial_num public static final string device_serial_num key to represent device serial number to generate the paymentappinstanceid since api level 2 5 see also constant field values error_spay_pin_lock_setup_canceled public static final int error_spay_pin_lock_setup_canceled this error indicates that user canceled the pin lock setup partner app should ask user to setup pin for samsung pay gear since api level 2 5 see also constant field values error_invalid_parameter public static final int error_invalid_parameter this error indicates that the given parameter is invalid this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 2 5 see also constant field values error_spay_watch_pin_lock_setup_canceled public static final int error_spay_watch_pin_lock_setup_canceled this error indicates that user canceled the pin lock setup partner app should ask user to setup pin for samsung pay watch since api level 2 5 see also constant field values spay_watch_update_is_ongoing public static final int spay_watch_update_is_ongoing this error indicates that samsung pay watch being updated since api level 2 5 see also constant field values spay_watch_taking_log_for_report public static final int spay_watch_taking_log_for_report this error indicates that samsung pay watch is taking log for error report since api level 2 5 see also constant field values error_spay_watch_pay_progress public static final int error_spay_watch_pay_progress this error indicates that samsung pay watch is in a process of payment since api level 2 5 see also constant field values error_spay_watch_connection public static final int error_spay_watch_connection this error indicates that samsung pay watch plug-in can not connect with samsung pay watch partner app should ask user to check bluetooth connection or pairing since api level 2 5 see also constant field values constructor details watchmanager public watchmanager android content context context, partnerinfo partnerinfo api to get the watchmanager instance the caller should set valid serviceid partnerinfo is passed to samsung pay on watch for caller verification context ct = activity; // or context ct = service; string issuername = "mybank"; // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring watchmanager extra_issuer_name, issuername ; bundle putstring watchmanager partner_service_type, watchmanager servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; watchmanager watchmanager = new watchmanager ct, pinfo ; parameters context - activity context or service context partnerinfo - partner information throws nullpointerexception - thrown if parameters are null since api level 2 5 method details getsamsungpaystatus public void getsamsungpaystatus @nonnull statuslistener listener api to get the samsung pay on watch status on the device partner issuers applications must call this api to check the current state of samsung pay on watch 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 watchmanager partner_service_type, watchmanager servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; watchmanager watchmanager = new watchmanager context, pinfo ; watchmanager getsamsungpaystatus new statuslistener { @override public void onsuccess int status, bundle data { // success case if status == spay_ready { log d tag, "samsung pay on watch is ready on the device" ; // perform your operation } else if status == spay_not_ready { // samsung pay on watch 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 { // samsung pay on watch is not supported on this device log d tag, "device does not support samsung pay on watch" ; } } @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 watchmanager extra_error_reason if provided } } ; parameters listener - callback through which the result is provided on success, samsung pay on watch status code is provided via statuslistener onsuccess int status, bundle data if samsung pay on watch is ready to be used, #spay_ready will be returned otherwise, #spay_not_ready or #spay_not_supported can be returned with #extra_error_reason from bundle also, partner can get extra information from bundle data bundle keys if provided bundle values spaysdk extra_country_code device country code iso 3166-1 alpha-2 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 2 5 gotoupdatepage public void gotoupdatepage api to go to samsung pay on watch update page partner app checks the samsung pay on watch 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 on watch app // set the serviceid which is assigned by the samsung pay developer during on boarding string serviceid = "sampleserviceid"; bundle bundle = new bundle ; bundle putstring watchmanager partner_service_type, watchmanager servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; watchmanager watchmanager = new watchmanager context, pinfo ; watchmanager gotoupdatepage ; since api level 2 5 activatesamsungpay public void activatesamsungpay api to bring the samsung pay on watch app to a state in which cards can be added samsung pay on watch might be samsung account is not signed in state partner app checks the samsung pay on watch 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 on watch 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 watchmanager partner_service_type, watchmanager servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; watchmanager watchmanager = new watchmanager context, pinfo ; watchmanager activatesamsungpay ; since api level 2 5 getwalletinfo public void getwalletinfo list<string> keys, @nonnull statuslistener listener api to get the requested wallet information from samsung pay on watch partner app can use this information to uniquely identify the user and samsung pay on watch 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 watchmanager extra_issuer_name, "issuer name" ; bundle putstring watchmanager partner_service_type, watchmanager servicetype app2app tostring ; partnerinfo pinfo = new partnerinfo serviceid, bundle ; watchmanager watchmanager = new watchmanager context, pinfo ; // bundle keys added to get wallet information from samsung pay on watch // this information can be delivered to the partner server for eligibility check arraylist<string> keys = new arraylist<> ; keys add watchmanager wallet_user_id ; keys add watchmanager device_id ; watchmanager 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 watchmanager device_id ; // for visa, walletuserid can be set to "clientwalletaccountid" as defined by visa string walletuserid = walletdata get watchmanager 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 watchmanager 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 device_serial_num 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 #wallet_dm_id string device management id n/a paymentappinstanceid = device_serial_num + wallet_dm_id *if you need 'paymentappinstanceid', you can generate it as above #device_id string device id clientdeviceid #wallet_user_id string wallet user id clientwalletaccountid device_serial_num string device serial number n/a 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 2 5 addcard public void addcard @nonnull addcardinfo addcardinfo, @nonnull addcardlistener listener api to add a card from partner app example issuer/bank app to samsung pay on watch partner app uses this api to add card to samsung pay on watch by providing the required card details this helps user to add their cards to samsung pay on watch directly from partner app watchmanager watchmanager = new watchmanager ct, pinfo ; string cardtype = card card_type_credit; string tokenizationprovider = addcardinfo provider_abcd; // get it from issuer app // samsung pay on watch does not provide detailed payload information // generate provisioning payload in accordance with your card network specifications string testpayload = "thisistestpayloadcardinfo1234567890"; bundle carddetail = new bundle ; carddetail putstring addcardinfo extra_provision_payload, testpayload ; addcardinfo addcardinfo = new addcardinfo cardtype, tokenizationprovider, carddetail ; watchmanager addcard addcardinfo, new addcardlistener { @override public void onsuccess int status, card card { log d tag, "onsuccess callback is called" ; } @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 watchmanager extra_error_reason or watchmanager extra_request_id if provided } @override public void onprogress int currentcount, int totalcount, bundle bundledata { log d tag,"onprogress callback is called " + currentcount + " / " + totalcount ; } } ; parameters addcardinfo - detail card information to add listener - callback through which the result is provided on success, addcardlistener onsuccess int, card is invoked with #error_none status code with added card information on any failure, the error code is provided via addcardlistener onfail int errorcode, bundle errordata the failure code can be one of the following codes with bundle data status bundle keys bundle values #error_registration_fail -104 #extra_error_reason apptoappconstants error_card_already_registered -500 apptoappconstants error_framework_internal -501 apptoappconstants error_invalid_card -502 apptoappconstants error_invalid_cardinput -503 error_invalid_parameter -504 apptoappconstants error_server_reject -505 apptoappconstants error_max_card_num_reached -506 apptoappconstants error_card_not_supported -514 apptoappconstants error_max_pan_provision_num_reached -515 apptoappconstants error_wallet_id_mismatch -516 error_spay_watch_pin_lock_setup_canceled -701 spay_watch_update_is_ongoing -702 spay_watch_taking_log_for_report -703 error_spay_watch_pay_progress -704 error_spay_watch_connection -705 #extra_request_id string value returned from server note please refer spaysdk common_status_table for other error status throws nullpointerexception - thrown if parameters are null since api level 2 17 getallcards public void getallcards @nullable android os bundle cardfilter, @nonnull getcardlistener listener api to get all the cards from samsung pay on watch for the given filter since api level 2 5, partner must define issuer names as a card filter on samsung pay developers while on-boarding bundle cardfilter = new bundle ; watchmanager getallcards cardfilter, new getcardlistener { @override public void onsuccess list<card> cards { // getting card status is success if cards == null || cards isempty { log e tag,"no card is found" ; return; } else { // perform operation with card data for card s cards { log d tag, "cardid " + s getcardid + "cardstatus" + s getcardstatus ; // get extra card data if s getcardinfo != null { string last4fpan = s getcardinfo getstring watchmanager extra_last4_fpan ; string last4dpan = s getcardinfo getstring watchmanager extra_last4_dpan ; string cardtype = s getcardinfo getstring watchmanager extra_card_type ; string cardissuername = s getcardinfo getstring watchmanager extra_issuer_name ; log d tag, "last4fpan " + last4fpan + "last4dpan" + last4dpan + "app2apppayload " + app2apppayload ; } } } } @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 watchmanager extra_error_reason if provided } } ; parameters listener - callback through which the result is provided on success, getcardlistener onsuccess list is invoked with list of cards on any failure, the error code is provided via getcardlistener onfail int, bundle note please refer spaysdk common_status_table in detail throws nullpointerexception - thrown if listener is null since api level 2 13 samsung electronics samsung pay sdk 2 22 00 - nov 19 2024
Develop Samsung Blockchain
docapi implementation samsung blockchain keystore api level get instance get seedhash check for mandatory app update is root seed backed up get supported coins get hd path get a list of addresses get a list of extended public keys sign a transaction is reboot authentication required go to samsung blockchain keystore settings handle error codes deeplinks samsung blockchain keystore api level samsung blockchain keystore api level plays a key role to ensure that the required api level of samsung blockchain keystore on a user’s device is properly installed to support the api that your android app tries to call for example, if your android app is trying to implement a new samsung blockchain keystore api that requires “api level 2”, your android app will need to check whether samsung blockchain keystore app installed on user’s device also supports api level 2 if a user’s app supports api level 1, then your app will need to guide users to update samsung blockchain keystore app to the latest version users can be directed to the update page in galaxy store otherwise, there will be a runtime exception due to api level exception when calling apis with level higher than the level supported by the user’s version the api level for each api will be mentioned in the javadoc, under “since” title, and developers can call “getkeystoreapilevel api” to check the current api level on the user’s device your android app will need to check the api level whenever needed – it may be at the beginning of running samsung blockchain keystore app or every time your app calls an api public void getkeystoreapilevel { int keystoreapilevel = scwservice getinstance getkeystoreapilevel ; boolean iskeystoreapisupported = keystoreapilevel > 0; } get instance scwservice getinstance will need to be used to call any of the apis provided by samsung blockchain keystore if samsung blockchain keystore is supported on the device, an instance will be returned if it is not available on the device, then null will be returned if null is returned, it means samsung blockchain keystore is not supported on the user’s device a different keystore or a wallet needs to be used scwservice scwserviceinstance = scwservice getinstance ; get seed hash getseedhash api aims to help developers distinguish two things 1 check whether user has set up samsung blockchain keystore 2 check whether root seed recovery phrase has been changed or not every time a new root seed or a wallet is created or restored, the seed hash in a string value will be changed actually, this is not the preimage of the real seed, but a pseudo hash value so, it is not possible to calculate the real seed with the pseudo one it is strongly recommended for the application to cache the returned hash value to reduce the number of times to check the derived address’s validity if the returned value is same as cached, the derived addresses are still valid, so the application keeps using these addresses otherwise, the application should refresh the addresses from new seed with getaddresslist or getextendedpublickeylist api whenever the application starts, it needs to call getseedhash in case that the returned value is a zero-length string, it means that there is no wallet in the samsung blockchain keystore so, the application ui needs to guide users to jump to samsung blockchain keystore to create a wallet with scwdeeplink main deeplink public void getseedhash { string seedhash = scwservice getinstance getseedhash ; boolean initialized = seedhash != null && seedhash length > 0 ; } check mandatory app update checkformandatoryappupdate api is to help developers check if a user must update samsung blockchain keystore because samsung blockchain keystore handles only one task at a time, make sure to not call the checkformandatoryappupdate api in the background as it may cause other api calls or requests to be cancelled if a mandatory app update is needed, users can be directed to the galaxy store using a deeplink, scwdeeplink galaxy_store otherwise, users will see the mandatory app update popups during an operation process, such as signing a transaction, and will need to update samsung blockchain keystore before proceeding note scwservice scwcheckformandatoryappupdatecallback will need to be implemented correspondingly scwservice scwcheckformandatoryappupdatecallback callback = new scwservice scwcheckformandatoryappupdatecallback { @override public void onmandatoryappupdateneeded boolean needed { if needed { startdeeplink scwdeeplink galaxy_store ; } } }; scwservice getinstance checkformandatoryappupdate callback ; how to handle the returned value a boolean needed value of whether a mandatory update is needed or not will be returned if needed, developers will need to guide users to go to samsung blockchain keystore app page in galaxy store to update is root seed backed up isrootseedbackedup api helps developers check if there is a backup of root seed since a user can create a wallet without a backup of root seed, developers can advise the user to make root seed backup if a backup of root seed is needed, the users will be directed to the page which backs up the mnemonic phrases in the samsung blockchain keystore using a deep link, scwdeeplink backup_wallet boolean isbackedup = scwservice getinstance isrootseedbackedup ; if !isbackedup { startdeeplink scwdeeplink backup_wallet ; } how to handle the returned value the result of root seed backup will be returned in a boolean type get supported coins getsupportedcoins api is used to find out which type of cryptocurrencies are supported, in case there is a different logic that developers must implement for different cryptocurrencies it is returned in an int array of standard coin types according to bip standard – for example, 60 for ethereum int[] supportedcoins = scwservice getinstance getsupportedcoins ; stringbuilder sb = new stringbuilder ; sb append "supported coins" append '\n' ; for int i = 0; i < supportedcoins length; i++ { sb append '[' append i append "] " append supportedcoins[i] append '\n' ; } string s = sb tostring ; get hd path gethdpath api helps developers derive hd path for a specified coin type this api can be used as a parameter when deriving an address and requesting to sign a transaction note that utxo-based cryptocurrency, such as bitcoin will not be supported for this api no callback will be needed for this api as hd path in string type will be returned immediately //derive hd path for the cryptocurrency that your app supports string ethereumhdpath = scwservice gethdpath scwcointype eth, 0 ; string klaytnhdpath = scwservice gethdpath scwcointype klay, 0 ; string tronhdpath = scwservice gethdpath scwcointype tron, 0 ; string stellarhdpath = scwservice gethdpath scwcointype xlm, 0 ; there are two parameters needed coin type and address index coin type use scwcointype class to specify the cryptocurrency that your app uses address index address index is like an account number it is recommended to use 0 as the default address index increasing the address index will generate a different account for example, if you need another ethereum account, then you can increase this address index to 1 if you need just one address for your service, then make sure to use the same coin type and same address index throughout your service so that user does not get confused with multiple addresses examples the returned value will be hd path in a string format this hd path will be needed for getaddresslist api and signing cryptocurrency apis scwservice gethdpath scwcointype eth, 0 will return “m/44’/60’/0’/0/0” scwservice gethdpath scwcointype eth, 1 will return “m/44’/60’/0’/0/1” scwservice gethdpath scwcointype klay, 0 will return “m/44’/8217’/0’/0/0” scwservice gethdpath scwcointype tron, 0 will return “m/44’/195’/0’/0/0” scwservice gethdpath scwcointype xlm, 0 will return “m/44’/148’/0’” for more details on hd path refer to key management section in understanding keystore you can find how hd path is used in samsung blockchain keystore get a list of addresses getaddresslist api allows developers to request to get a list of addresses that correspond to a list of hd paths a list of the hd path, compatible with bip-44 needs to be passed on to bring the addresses the depth of hd path should be between 3 and 6 also, scwservice scwgetaddresslistcallback will need to be implemented correspondingly scwservice scwgetaddresslistcallback callback = new scwservice scwgetaddresslistcallback { @override public void onsuccess list<string> addresslist { } @override public void onfailure int errorcode, string errormessage { //handle errors } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; scwservice getinstance getaddresslist callback, hdpathlist ; hierarchical deterministic path hd path examples hdpath for ethereum m/44'/60'/0'/0/0 hdpath for bitcoin m/44'/0'/0'/0/0 if you are unsure about what hd path is, then you can generate hd path with gethdpath api except for bitcoin how to handle the returned value the returned value will be a list of addresses in a list** format each address will correspond to the hd path in the arraylist minimize calling getaddresslist api by checking seed hash value to avoid calling getaddresslist api as much as possible, please utilize getseedhash api to check whether the root seed has been changed or not, since different seed hash value implies that the corresponding address has also been updated get a list of extended public keys getextendedpublickeylist api allows developers to request to get a list of extended public keys that correspond to a list of hd paths a list of the hd path, compatible with bip-44 needs to be passed on to bring the public key the depth of path should be between 3 and 6 take note that the scwservice scwgetextendedpublickeylistcallback will need to be implemented correspondingly scwservice scwgetextendedpublickeylistcallback callback = new scwservice scwgetextendedpublickeylistcallback { @override public void onsuccess list<byte[]> extendedpublickeylist { } @override public void onfailure int errorcode, string errormessage { //handle errors } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; scwservice getinstance getextendedpublickeylist callback, hdpathlist ; hierarchical deterministic path hd path examples hdpath for ethereum m/44'/60'/0'/0/0 hdpath for bitcoin m/44'/0'/0'/0/0 how to handle the returned value the returned value will be list <byte[]> that corresponds to each hd path requested in the arraylist each byte array is composed of 33 bytes of compressed public key and 32 bytes of chain code you can derive the child public key based on this data note that you need to derive the address of the compressed public key or call getaddresslist api to get the address minimize calling getextendedpublickeylist api by checking seed hash value use getseedhash api to check whether the root seed has been changed or not, since different seed hash value implies that corresponding public keys have also been updated sign a transaction there are seven apis that support signing cryptocurrency transactions ethereum, personal sign message in ethereum, bitcoin, klaytn, tron, personal sign message in tron, and stellar note only signing a transaction is included in the samsung blockchain keystore scope 1 signethtransaction api signethtransaction api as the name implies, sends a request to samsung blockchain keystore to sign an ethereum transaction likewise, scwservice scwsignethtransactioncallback will need to be implemented scwservice scwsignethtransactioncallback callback = new scwservice scwsignethtransactioncallback { @override public void onsuccess byte[] signedethtransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string toaddress = "0xe7425ee1bc64ab7c51ce3617cb83e76fd545f1a9"; string ethamount = "123 456789"; string ethgasprice = "12000000000"; string ethgaslimit = "21000"; string data = ""; long chainid = 1; string hdpath = scwservice gethdpath scwcointype eth, 0 ; byte[] encodedunsignedethtx = createrawtransaction toaddress, ethamount, ethgasprice, ethgaslimit, data ; private byte[] createrawtransaction param1, param2, … { //implement your code here } scwservice getinstance signethtransaction callback, encodedunsignedethtx, hdpath, chainid ; the parameters to take note are as follows encodedunsignedethtx a byte array of an rlp-encoded unsigned ethereum raw transaction hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing chainid chain id to prevent replay attacks between different chain for eip1559 transaction, chainid should be null how to handle the returned value the signed transaction will be returned in a byte array type in a rlp-encoded format 2 signethpersonalmessage api signethpersonalmessage api can be used to request to samsung blockchain keystore to sign a message in ethereum scwservice scwsignethpersonalmessagecallback will need to be implemented scwservice scwsignethpersonalmessagecallback callback = new scwservice scwsignethpersonalmessagecallback { @override public void onsuccess byte[] signedpersonalmessage { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype eth, 0 ; byte[] unsignedmsg = "to sign up, please sign this message " getbytes ; scwservice getinstance signethpersonalmessage callback, unsignedmsg, hdpath ; the parameters to take note are as follows unsignedmsg – a byte array of raw message to be signed by samsung blockchain keystore the "\u0019ethereum signed message \n" prefix will be added by samsung blockchain keystore, so your android app should not include the prefix in the message hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the type of return is a byte array of signed message based on r, s, v values for a transaction’s signature respectively 3 signbtctransaction api signbtctransaction api can be used to create a request to samsung blockchain keystore to sign a bitcoin transaction the scwservice scwsignbtctransactioncallback will need to be implemented scwservice scwsignbtctransactioncallback callback = new scwservice scwsignbtctransactioncallback { @override public void onsuccess byte[] signedbtctransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; list<utxo> utxos = new arraylist<> ; arraylist<string> inputhdpathlist = new arraylist<> ; string changehdpath = "m/44'/0'/0'/0/0"; string inputhdpath1 = "m/44'/0'/0'/0/0"; string inputhdpath2 = "m/44'/0'/0'/0/1"; utxos add getunspentoutputs inputhdpath1 ; utxos add getunspentoutputs inputhdpath2 ; transactionextended unsignedtx = makeunsignedtransaction networkparams, utxos, to, value, fee ; for int i = 0; i < unsignedtx getinputs size ; i++ { string inputhdpath = unsignedtx getinputs gethdpath i ; inputhdpathlist add inputhdpath ; } private transaction makeunsignedtransaction networkparameters networkparams, list<utxo> utxos, string to, long value, long fee { //make unsigned transaction among unspent outputs to spend value with fee //implement your code here } scwservice getinstance signbtctransaction callback, transaction, inputhdpathlist, changehdpath ; the parameters to take note are as follows transaction a byte array of a serialized unsigned bitcoin transaction to be signed by samsung blockchain keystore inputhdpathlist a list of hd path that corresponds to the addresses linked to the transaction inputs in transaction this list also corresponds to the private key which is used for signing bip-44, 49, 84 are supported and coin type “1” in hd path can be used for bitcoin test network parameter check samsung blockchain keystore will verify the requested transaction using transactioninput in transaction and inputhdpathlist each transactioninput should correspond to an hd path in inputhdpathlist if there are multiple transactioninput, then corresponding inputhdpathlist and transactioninputs should be listed in the same order changehdpath if there is a return change, then include the hd path that corresponds to the change address if the change address is not needed, then this value should be null how to handle the returned value the signed transaction will be returned in a byte array type 4 signklaytransaction api signklaytransaction api can be used to request to samsung blockchain keystore to sign a klaytn transaction scwservice scwsignklaytransactioncallback will need to be implemented scwservice scwsignklaytransactioncallback callback = new scwservice scwsignklaytransactioncallback { @override public void onsuccess byte[] signedklaytransaction { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype klay, 0 ; byte[] unsignedtransaction = getunsignedtx ; int klaytnchainid = 1001; scwservice getinstance signklaytransaction callback, unsignedtransaction, hdpath, klaytnchainid ; the parameters to take note are as follows unsignedtransaction a byte array of raw transaction to be signed by samsung blockchain keystore it is same as the sigrlp value mentioned in klaytn official document hdpath - hd path that corresponds to the public key linked to your android app that also corresponds to the private key which is used for signing klaytnchainid – the klaytn network id or the integer to identify the network "8217" is klaytn cypress mainnet and "1001" is klaytn baobab testnet how to handle the returned value the signed transaction will be returned in a byte array type in a rlp-encoded format 5 signtrxtransaction api signtrxtransaction api can be used to request to samsung blockchain keystore to sign a tron transaction scwservice scwsigntrxtransactioncallback will need to be implemented scwservice scwsigntrxtransactioncallback callback = new scwservice scwsigntrxtransactioncallback { @override public void onsuccess byte[] signedtrxtransaction { //handle signed tron transaction } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype tron, 0 ; string from = “tdcmwosbafcegqqnuarnjghy4tabdcmdwi” string to = “tq6pm81jdc2ghruonytzgvpc7svyqcemeu”; int amount = 2; byte[] unsignedtransaction = createunsignedtransaction hdpath from, to, amount ; private byte[] createunsignedtransaction param1, param2, … { //implement your code here } scwservice getinstance signtrxtransaction callback, unsignedtransaction, hdpath ; the parameters to take note are as follows unsignedtransaction a byte array of raw tron transaction to be signed by samsung blockchain keystore hdpath - hd path that corresponds to the public key linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value signed transaction will be returned in a byte array 6 signtrxpersonalmessage api signtrxpersonalmessage api can be used to request to the samsung blockchain keystore to sign a message in tron the scwservice scwsigntrxpersonalmessagecallback will need to be implemented scwservice scwsigntrxpersonalmessagecallback callback = new scwservice scwsigntrxpersonalmessagecallback { @override public void onsuccess byte[] signedpersonalmessage { } @override public void onfailure int errorcode, string errormessage { //handle error } }; string hdpath = scwservice gethdpath scwcointype tron, 0 ; byte[] unsignedmsg = "to sign up, please sign this message " getbytes ; scwservice getinstance signtrxpersonalmessage callback, unsignedmsg, hdpath ; the parameters to take note are as follows unsignedmsg a byte array of raw message to be signed by samsung blockchain keystore a "\u0019tron signed message \n32" prefix will be added by samsung blockchain keystore, so your android app should not include the prefix in the message hdpath hd path that corresponds to the address linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the type of return is a byte array of signed message based on values for a transaction’s signature - r, s, v respectively 7 signxlmtransaction api signxlmtransaction api can be used to request to the samsung blockchain keystore to sign a stellar transaction the scwservice scwsignxlmtransactioncallback will be needed to be implemented scwservice scwsignxlmtransactioncallback callback = new scwservice scwsignxlmtransactioncallback { @override public void onsuccess byte[] signedxlmtransaction { //handle signed stellar transaction } @override public void onfailure int errorcode, string errormessage { //handle error } }; string recipientaccount = “gay5dorarbd5l3fbbwuhxkciv7vcmqicsllj7gyr4664av4mxtx2fh4o”; string amount = “100”; paymentoperation operation = new paymentoperation builder recipientaccount, asset, amount build ; string hdpath = scwservice gethdpath scwcointype xlm, 0 ; arraylist<string> hdpathlist = new arraylist<> ; hdpathlist add hdpath ; string sourceaccount = “gb7zviydvsww3ctfj2v3oproahgbuomebwib55xieii3aq6523pg4lm5”; string memo = "hello12347"; byte[] unsignedtransaction = createunsignedtransaction sourceaccount, operation, memo, networkid ; private byte[] createunsignedtransaction param1, param2, … { //implement your code here // include networkid, envelopetype envelopte_type_tx , and xdr-encoded transaction } scwservice getinstance signxlmtransaction callback, unsignedtransaction, hdpathlist ; the parameters to take note are as follows unsignedtransaction – a byte array of raw transaction to be signed by samsung blockchain keystore it is the same as the signature base, which includes networkid, envelopetype, and xdr-encoded transaction hdpathlist a list of hd path that corresponds to the addresses linked to your android app that also corresponds to the private key which is used for signing how to handle the returned value the signed transaction will be returned in a byte array developers can use base64 encoding to implement this result into envelopexdr, which can derive the transaction that can be submitted to the network is reboot authentication required the isrebootauthenticationrequired api allows you to check whether pin authentication is required after reboot some keystore api calls can require pin authentication after device reboot these calls are successful only after the user enters their blockchain keystore pin at the prompt the isrebootauthenticationrequired method allows you to determine whether accessing the keystore api requires pin authentication boolean isrebootauthenticationrequired = scwservice getinstance isrebootauthenticationrequired ; if isrebootauthenticationrequired { // user prompted for pin authentication } else { // user not prompted for pin authentication } • handling the returned value the isrebootauthenticationrequired method returns a boolean value go to samsung blockchain keystore settings samsung blockchain keystore provides a user-friendly setup page for the first time users and a settings page for existing users developers can easily jump to samsung blockchain keystore settings by using a deeplink, scwdeeplink main there are two purposes of calling the samsung blockchain keystore main activity setup samsung blockchain keystore for first time users after calling getseedhash api, if the wallet is not created, a zero length value will be returned this is when your android app should call samsung blockchain keystore settings via a deep link as shown below samsung blockchain keystore will check if a user needs to set up a new wallet and if needed, will lead to a setup page after the activity is finished, your android app should call the getseedhash api, once more, to make sure that the wallet has been created and the corresponding seed hash value is returned samsung blockchain keystore settings for existing users for existing users, when samsung blockchain keystore settings is called, a user will see a list of menu related to samsung blockchain keystore management features include changing the pin, removing the wallet, checking a recovery phrase to back up the wallet, enabling/disabling fingerprint as an authentication method, or changing alarm notifications settings more information about the samsung blockchain keystore, such as notices, terms and conditions, and app information can be also found here a sample code for calling samsung blockchain keystore via a deeplink is as follows uri uri = uri parse scwdeeplink main ; intent intent = new intent intent action_view ; intent setdata uri ; intent setflags intent flag_activity_new_task ; mcontext startactivity intent ; *do not call startactivityforresult intent as no results will be returned make sure to use startactivity intent instead handling error codes in addition to general error codes, the following are some special cases that developers may want to look out for mandatory update is needed samsung blockchain keystore was removed due to user entering wrong pin more than n times api key is invalid the popups above will be shown from samsung blockchain keystore app, though the samsung blockchain keystore will still return corresponding error codes in the mandatory update error case, the user will see a popup with a link to galaxy apps store page to update samsung blockchain keystore if it was reset, due to entering a wrong pin more than n times, then the user will need to create or import the wallet via samsung blockchain keystore service again it is recommended that developers call checkformandatoryappupdate api before calling other apis, to check whether a mandatory app update is needed for this api, no ui or popup will be shown from samsung blockchain keystore upon integration, developers may receive an “error_package_signature_verification_failed” error in this case, developers can turn on developer mode to skip the app verification stage yet, developers will need to implement proper app id, officially issued by the samsung blockchain keystore team before launching your android app in the market public interface scwerrorcode { int error_mandatory_app_update_needed = -8; int error_package_signature_verification_failed = -11; int error_wallet_reset = -12; int error_check_app_version_failed = -15; int error_tnc_not_agreed = -6; } please refer to the scwerrorcode class in javadoc for more details on error codes samsung blockchain keystore deeplinks deep links to samsung blockchain keystore and deep link to update samsung blockchain keystore app in galaxy store are provided developers can implement the links below to direct users to go to the main page and back up root seed page in samsung blockchain keystore settings directly deep link to galaxy store can be used when user needs to update samsung blockchain keystore app features deeplink main page scwdeeplink main galaxy apps store scwdeeplink galaxy_store backup wallet scwdeeplink backup_wallet
Develop Samsung Wallet
docapi guidelines app2app sdk integration specs description & use rp sdk is an app2app sdk for samsung wallet driver's license service online scenarios this sdk provides an implementation for direct communication between the samsung wallet and partner applications build the settings rpsdk requires additional dependencies with dependencies { implementation "rp-sdk-1 0-release aar" implementation "androidx core core-ktx 1 3 2" implementation "androidx lifecycle lifecycle-runtime-ktx 2 7 0" implementation "androidx lifecycle lifecycle-livedata-core-ktx 2 7 0" implementation "io reactivex rxjava2 rxjava 2 2 21" implementation "io reactivex rxjava2 rxkotlin 2 4 0" implementation "io reactivex rxjava2 rxandroid 2 1 1" implementation "com squareup okhttp3 okhttp 4 11 0" implementation "com google code gson gson 2 10 1" implementation "org bouncycastle bcprov-jdk15to18 1 66" implementation "com nimbusds nimbus-jose-jwt 9 37 3" } androidmanifest xml <manifest xmlns android="http //schemas android com/apk/res/android"> <uses-permission android name="android permission internet" /> <queries> <package android name="com samsung android spay" /> </queries> </manifest> r8 / proguard the specific rules are already bundled into the aar which can be interpreted by r8 automatically sdk method app2app sdk supports one method request signature & parameters of the request method fun request targetpackagename string, requestid string, applink string, onresponselistener onresponselistener? = null parameter name description targetpackagename the pakcage name to connect to requestid a random string to identify each request applink the applink built by samsung mcs server guide onresponselistener a listener to receive each events or requests [sample code] binding button setonclicklistener { rpclientapis request "com samsung android spay", uuid randomuuid tostring , applink, object rpclientapis onresponselistener { override fun ongetmdocrequestdata deviceengagementbytes bytearray bytearray? { log i tag, "ongetmdocrequestdata $deviceengagementbytes " /** * 1 prepare mdoc request data iso-18013-5 * 2 build sessionestablishmentbytes iso-18013-5 * 3 encrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations **/ return "encryptedsessionestablishmentbytes" } override fun onmdocresponse encryptedresponse bytearray { log i tag, "onmdocresponse $encryptedresponse " /** * 1 decrypt it with hkdf iso-18013-5, 9 1 1 5 cryptographic operations * 2 cbor decode it **/ } override fun onmdocresponsefailed exception exception { log i tag, "onmdocresponsefailed $exception " } } } error code explanation the below exceptions might occur through the onmdocresponsefailed callback exceptions name description rpcommunicationexception this error occurs when the data requested by the listener is incorrect rpconnectionfailedexception this occurs when the app 2 app communication between apps is not working this usually occurs when the target package name is written incorrectly web2app api integration specs the api specifications that need to be implemented by the rp partner are described below called by samsung to the rp partner send key send the wallet application key info and return the data field types requested to the client for authentication of the mdl [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/key headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details path parameters cardidstring 32 required wallet card identifier issued from partner portal when the partner manager signs up for partner services and registers the wallet card they want to service refid string 32 required unique content identifier defined by the content provider query parameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, and it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "relyingparty", "subtype" "others", "designtype" "us-01" }} [example] post {partner server url}/rp/v1 0/{cardid}/{refid}/key content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyymdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtfoddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxscxltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdbyny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nuedrvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmjnq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0zvenbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzddevfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnplekwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgfmodhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvxvketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nxm46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvuqncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuqhtjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbwycvx8wa” } [response] type value description http status code 200 ok payload data string 3000 required jwt data encrypted with the data field types requested to the client for authentication of the mdl [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request send authentication data the data is encrypted according to the requested data and then transmitted along with the data card information [request] type value description method post url {partner server url}/rp/v1 0/{cardid}/{refid}/auth headers authorization string 1024 required credential token the token can have the prefix "bearer" as an authorization type, e g , bearer <credentials> * refer to authorization token for more details pathparameters cardid string 32 required wallet card identifier issued from partner portal when the partner manager signs up for partner services and registers the wallet card they want to service refid string 32 required unique content identifier defined by the content provider queryparameter n/a payload data string 3000 required jwt data encrypted with the public key information and card type if decrypted this data is decoded, it has the following format information { “data” “xxxxxxxxxxx”, “card” {"type" "idcard","subtype" "drivers","designtype" "us-01" }} [example] post {partner server url}/rp/v1 0/{cardid}/{refid}/auth content-type application/json { “data” “eyjjdhkioijbvvriiiwidmvyijoimiisinbhcnruzxjjzci6inrlc3qilcj1dgmioje3mtyymdyznjaxmtasimfszyi6iljtmju2in0 zxlkbgjttwlpaupctvrjnfiwtk5jaxdpwvd4bklqb2lvbe5ctfu5qljwqxrnaluysw4wllz5afaxs0fnmvjhbzbdn2nix2pydgtfoddqbnhrrmpfwkppcnnsuus4mnn0owvxtjeyvzvmoejax1d5ngvzmze3vdnad0pncmpwzwdzoek3avlcwwrlogj5lxfimjblu3ruc3jsszlpslfnn1fam2xzauxscxltb0vlbervd0fpatrmry1jukzwdvlrbxrintg3utd1zwnuq1lwwgzwalvecg01yxbfbdv3szm1ugz3d0dkrem2tmowz1awbtz3nk1kdl9mddbvzwc2mwzjagdbyny0emxmzju2cvyzm0t6zjdjbwvpbkjrnnpmsgutymfwyxhvzk5ld2htzwvjuzftv3larm1nvlj6mefsmnbxa0dqlvjkt1iza3vzavo0vjfidy1aq2iyvwvwyvdzru9nuedrvw1mbtfuowjwt1zmz1nuv1f0se5pvtfjyvrhtg1dwlpvqs5pmzzrd1g4wmjnq21wd3o2ll9kzehfvxnnbm13b1drddrmcu4xmuncauntsnutbwpyv2zrckxos0zvenbss085ckdxbudpz0pqukf1ntfsotryc2vivwdfwu9ns2rgr1vomwjhmhb3y0tfngtjmet2dkfowhprodn0azbjqzrot2f6vzlmovntt0rhmu9imefoavfzqzddevfqnndnlwflvk8waejwsejkmeduruh1z3exc21vvmxrbjblsnjqwhm4x3fwcnplekwtadfpcfk1aes1zug5q3nisms0aehcngnmwulkrujfz09bcgzxcgfumgfsvgfmodhhdxlqsgzhdgrma0tlwdv0q0rtajixse5tt0fhwtjvwlzrr0hxu0wzngjabtu5aezmnvdha0ljce9bmhlwue9tqznwtflkv2jsmm85lkfoedbvytvgetzudkxkvxvketazshc e07yyl7ior3885vykss5_q1icpx750uu2ge5sujsedx3dr_u0x4tse9_0nxm46dywnfuxruagfjdnjhibc707li9vi3xtyihwnweifydgv1qb9oddkyyzuahxqmjhvuqncdt6df2caqzf5qgmvqfmgse_t7ipu8vqfxe34do-skzj8ftduss2ecdanbqokchih3m39noubpfhcx68plpcw50dixlupxwegniu2t3co24yliaklgac669accxdqr34utvuqhtjt_ftxkahalzoa34_hj_s82fivixh1itd74uojzse7ibwya_kvysozavnmztz2th9cbwycvx8wa” } [response] type value description http status code 200 ok400 bad request [result] http status code description 200 ok success 400 bad request requests cannot or will not be processed due to somethingthat is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error the server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable the server is not ready to handle the request code explanation based on the sample code jwt jws + jwe decryption between the wallet backed server and partner server 1 verify by generateing a jws using the body data // generate jws by the body data private static signedjwt parsejwt final string data { try { return signedjwt parse data ; } catch parseexception e { log error "parserjwt error class {}, error message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "parserjwt error" ; } } // verify jws using samsung public key public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } 2 decrypt the jwe using the jws jweobject parse signedjwt getpayload tostring public static string getdecryptedpayloadfrom final key privatekey, final jweobject data { try { data decrypt new rsadecrypter privatekey privatekey ; // decryption jwe using partner private key return data getpayload tostring ; } catch joseexception e { log error "joseexception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "getdecryptedpayloadfrom error" ; } } 3 convert to the format send by the client public requestbody getrequestbody final keyring keyring { final signedjwt signedjwt = jwtutils verify keyring gettargetpublickey , encrypteddata, 60 * 10000 ; // verify and generate jws try { final string strbody = jwtutils getdecryptedpayloadfrom keyring getsourceprivatekey , jweobject parse signedjwt getpayload tostring ; // decryption jwe by the jws return objectmapper readvalue strbody, requestbody class ; // convert to data format requested by client } catch parseexception | jsonprocessingexception e { log error "getrequestbody {}", e getmessage ; throw new customexception httpstatus internal_server_error, "data body parse error" ; } } generate mdocestablishment 1 generate rsa key per refid public class transactioncontext { private final keypair keypair; // rsa key private final byte[] clientengagement; // body data received through key api, base64url decoded value @equalsandhashcode exclude private int encryptmessagecounter = 0; // count value when encrypted @equalsandhashcode exclude private int decryptmessagecounter = 0; // count value when decrypted } private cache<string, transactioncontext> contextcache; // rsa key management per refid with memory cache // generate and store rsa key per refid only once upon first request public transactioncontext settransactioncontext final string key, final string base64encodedclientengagement { log info "base64encodedclientpublickey {}", base64encodedclientengagement ; this contextcache put key, new transactioncontext keyutils generatekeypair , base64utils decode base64encodedclientengagement getbytes ; return this gettransactioncontextby key ; } // part of retrieving ras key based on refid public transactioncontext gettransactioncontextby final string key { return optional ofnullable this contextcache getifpresent key orelsethrow -> { log info "{} is empty", key ; return new customexception httpstatus bad_request, "no key matching the refid" ; } ; } 2 create request field values @override public mono<list<string>> createrequest final partnerinputdto inputdto { final string mockdata = "{ \"doctype\" \"org iso 18013 5 1 mdl\", \"namespaces\" { \"org iso 18013 5 1\" { \"sex\" false, \"portrait\" false, \"given_name\" false, \"issue_date\" false, \"expiry_date\" false, \"family_name\" false, \"document_number\" false, \"issuing_authority\" false }, \"org iso 18013 5 1 aamva\" { \"dhs_compliance\" false, \"edl_credential\" false } } }"; return mono just collections singletonlist mockdata ; } 3 generate establishment @allargsconstructor public class establishment { private final transactioncontext context; // info of client public key , partner private key, public key private final list<string> strreqs; // data field information required for authentication to the client private final keyring keyring; // rsa key information for jwt jws + jwe encryption and decryption between wallet backed server and partner server } protected cborobject generate { final cborobject sessionestablishment = cborobject newmap ; sessionestablishment set e_reader_key, cborobject fromobjectandtag keyutils getereaderkey context , tag_size ; // generate onekey by public key in transactioncontext sessionestablishment set data, cborobject fromobject cipherutils encrypt context, generaterequestformat getrequestcborobjectsfrom strreqs ; // add request data field information for authentication return sessionestablishment; } generate the response value jwt jws + jwe 1 generate establishment with jwe public static string encryptedstringjwe final key publickey, final string data { // please enter samsung public key and establishment data final jweobject jwe = new jweobject new jweheader builder jwealgorithm rsa_oaep_256, encryptionmethod a128gcm build , new payload data ; try { jwe encrypt new rsaencrypter rsapublickey publickey ; return jwe serialize ; } catch joseexception e { log error "encryptedstringjwe exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "encryptedstringjwe error" ; } } 2 generate jws by jwe public static string generatesignedstringjws final key privatekey, final key publickey, final string payload { // enter your partner’s public key, private key, and jwe data try { final jwsobject jwsobj = new jwsobject getdefaultjwsheader , new payload payload ; jwssigner signer = new rsassasigner new rsakey builder rsapublickey publickey privatekey rsaprivatekey privatekey build ; jwsobj sign signer ; return jwsobj serialize ; } catch joseexception e { log error "encryptedstringjws exception message {}", e getmessage ; throw new customexception httpstatus internal_server_error, "generatesignedstringjws error" ; } } 3 generate jwt jws + jwe public partneroutputdto topartneroutputdto { final cborobject generate = this generate ; final string establishment = base64 geturlencoder encodetostring generate encodetobytes ; final string strjwe = jwtutils encryptedstringjwe keyring gettargetpublickey , establishment ; final jwsheader jwsheader = jwtutils getdefaultjwsheader keyring getversion , keyring getcertificateid , "partnerid" ; return new partneroutputdto jwtutils generatesignedstringjws jwsheader, keyring getsourceprivatekey , keyring getsourcepublickey ,strjwe ; } authentication processing for values in data fields requested for authentication 1 retrieve transactioncontext value stored in cache using refid value @override public mono<transactioncontext> getcontext final partnerinputdto inputdto { return mono just this transactioncontextmanager gettransactioncontextby inputdto getrefid ; } 2 processes the decryption process of the request body data like jwt jws + jwe decryption between wallet backed server and partner server 3 generate mdocresponse public class mdocresponse { private final transactioncontext context; // managed tranactioncontext by refid private final byte[] data; // base64url decoded data after decrypting jwt jws + jwe data public mdocresponse final transactioncontext context, final string inputdto { this context = context; this data = base64utils decode inputdto getbytes standardcharsets utf_8 ; } } 4 get the field values requested for authentication from the data in mdocresponse public string getdata { // sessiondata = { // ? "data" bstr ; encrypted mdoc response or mdoc request // ? "status" uint ; status code // } final cborobject response = cborobject decodefrombytes data ; checktype response, cbortype map ; final cborobject data = response get data ; checktype data, cbortype bytestring ; return cborobject decodefrombytes isencryptedmode ? cipherutils decrypt this context, data getbytestring data getbytestring tojsonstring ; } 5 create a session value using the transactioncontext value managed by refid and then decrypt it private static byte[] processcipher final ciphermode ciphermode, final transactioncontext context, final byte[] bytes { // ciphermode encrypt or decrypt, bytes data passed by the client try { cipher cipher = cipher getinstance "aes/gcm/nopadding" ; final int counter = ciphermode encrypt == ciphermode ? context getencryptmessagecounter context getdecryptmessagecounter ; gcmparameterspec parameterspec = new gcmparameterspec 128, getsessionkeyiv ciphermode identifier, counter ; cipher init ciphermode ciphermode , getsecretkeyspec context, ciphermode info , parameterspec ; return cipher dofinal bytes ; } catch invalidalgorithmparameterexception | nosuchpaddingexception | illegalblocksizeexception | nosuchalgorithmexception | badpaddingexception | invalidkeyexception e { log error "error type {}, message {}", e getclass , e getmessage ; throw new customexception httpstatus internal_server_error, "processcipher error" ; } } 6 examining data received from the client @override public mono<void> authentication final string response { log info "response info {}", response ; return mono empty ; }
Develop Samsung Pay
docsample applications sample apps, use cases, and ux strategies are included here to aid you in understanding the sdk and implementing it in your application sample source code and apks can be downloaded from download section sample merchant app included with the samsung pay sdk to demonstrate its features, the sample merchant app shows you how to implement the payment sheet’s dynamic controls to leverage additional customer order and payment data and/or create a more custom ui look and feel the following payment sheet controls are available addresscontrol plaintextcontrol amountboxcontrol spinnercontrol controls are applied to suit a particular purpose or need for example, displaying a promotion notice in the payment sheet using the plaintextcontrol applying an addresscontrol this control is used to display the billing or shipping address on the payment sheet based on samsung pay’s my info user profile or addresses provided by your merchant app during the transaction request when creating the control, controlid and sheetitemtype are needed to distinguish the billing address from the shipping address otherwise, your merchant app sets the following properties address title – displays a merchant-defined title on the payment sheet if empty, the default title such as “billing address” is displayed address – provides various methods to retrieve address details the merchant app can retrieve the phone number using the 'getphonenumber' method of 'customsheetpaymentinfo' address starting from api level 1 5, the addressee’s email address has also been added retrieve the email address using 'getemail' you can also set a display option for the shipping address with 'setdisplayoption' for more information, see the samsung pay sdk-api reference javadoc and the sample code included with the samsung pay sdk sheetupdatedlistener – used to capture the response from the samsung wallet app; merchant app must deliver to the samsung wallet app an amountboxcontrol to display payment information on a custom payment sheet when the onresult callback is called, the updatesheet method must also be called to update the current payment sheet errorcode – used for containing error codes directly related to the address the workflows for billingaddresscontrol and shippingaddresscontrol are shown below the following sample code demonstrates use of addresscontrol on the payment sheet fun makebillingaddresscontrol addresscontrol { val billingaddresscontrol = if !iszipcodeonly { // for billing address addresscontrol billing_address_id, sheetitemtype billing_address billingaddresscontrol addresstitle = "billing address" } else { /* * for billing address with zip code only * since api level 2 19, sheetitemtype zip_only_address * for us country only */ addresscontrol billing_address_id, sheetitemtype zip_only_address billingaddresscontrol addresstitle = "zip code" } //this callback is received when controls are updated billingaddresscontrol sheetupdatedlistener = sheetupdatedlistener return billingaddresscontrol } //listener for billing or zip code only billing address fun sheetupdatedlistener sheetupdatedlistener { return sheetupdatedlistener { updatedcontrolid string, customsheet customsheet -> log d tag, "onresult billingaddresscontrol updatedcontrolid $updatedcontrolid" val addresscontrol = customsheet getsheetcontrol updatedcontrolid as addresscontrol val billaddress = addresscontrol address //validate only zipcode or billing address and set errorcode if needed if addresscontrol sheetitem sheetitemtype == sheetitemtype zip_only_address { val errorcode int = validatezipcodebillingaddress billaddress log d tag, "onresult updatesheetbilling errorcode $errorcode" addresscontrol errorcode = errorcode customsheet updatecontrol addresscontrol } else { val errorcode = validatebillingaddress billaddress log d tag, "onresult updatesheetbilling errorcode $errorcode" addresscontrol errorcode = errorcode customsheet updatecontrol addresscontrol } // update transaction values val amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol amountboxcontrol updatevalue product_item_id, 1000 0 amountboxcontrol updatevalue product_tax_id, 50 0 amountboxcontrol updatevalue product_shipping_id, 10 0 amountboxcontrol updatevalue product_fuel_id, 0 0, "pending" amountboxcontrol setamounttotal 1060 0, amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol try { // call updatesheet for the full amountboxcontrol; mandatory paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } } // for shipping address fun makeshippingaddresscontrol addresscontrol { val shippingaddresscontrol = addresscontrol shipping_address_id, sheetitemtype shipping_address shippingaddresscontrol addresstitle = "shipping address" val shippingaddress = customsheetpaymentinfo address builde setaddressee "name" setaddressline1 "addline1" setaddressline2 "addline2" setcity "city" setstate "state" setcountrycode "usa" setpostalcode "zip" setphonenumber "555-123-1234" setemail "user@samsung com" build shippingaddresscontrol address = shippingaddress /* * set address display option on custom payment sheet * if displayoption is not set, then default addresscontrol is displayed on custom payment sheet * the possible values are combination of below constants * {display_option_addressee} * {display_option_address} * {display_option_phone_number} * {display_option_email} */ var displayoption_val = addressconstants display_option_addressee // addressee is mandatory displayoption_val += addressconstants display_option_address displayoption_val += addressconstants display_option_phone_number displayoption_val += addressconstants display_option_email shippingaddresscontrol displayoption = displayoption_val return shippingaddresscontrol } here’s how these controls display on a custom payment sheet applying a plaintextcontrol this control is used for displaying a title with a two lines of text or a single line of text without a title on the payment sheet when allocating this control, a controlid is needed the merchant app sets both the title, as applicable, and the text diagrammed below is the flow between your merchant app and samsung pay the merchant app code invoking this class would look something like the following fun makeplaintextcontrol plaintextcontrol { val plaintextcontrol = plaintextcontrol "exampleplaintextcontrolid" plaintextcontrol settext "plain text [example]", "this is example of plaintextcontrol" return plaintextcontrol } and this is how it displays on the custom payment sheet applying an amountboxcontrol amountboxcontrol is used for displaying purchase amount information on the payment sheet it requires a controlid and a currencycode, and consists of item s and amounttotal, defined as follows and diagrammed on the next page item – consists of id, title, price, and extraprice if there is an extraprice in amountboxcontrol, its text is displayed on the payment sheet even though there is an actual numerical price value if there is no extraprice, then currencycode with the price value is displayed amounttotal – consists of price and displayoption the displayoption allows predefined strings only your merchant app can set the text to “estimated amount”, “amount pending”, “pending”, “free”, and so forth the ui format for the string is different for each option notethe setamounttotal api may accept strings that are not predefined as an argument, but itgenerates an invalid parameter condition or returns an error code in such cases for details, see the javadoc samsung pay sdk-api reference, available in the documentation folder of your downloaded sdk package here’s a coding example to demonstrate the use of amountboxcontrol in a payment sheet fun makeamountcontrol amountboxcontrol { val amountboxcontrol = amountboxcontrol amount_control_id, "usd" amountboxcontrol additem product_item_id, "item", 1000 0, "" amountboxcontrol additem product_tax_id, "tax", 50 0, "" amountboxcontrol additem product_shipping_id, "shipping", 10 0, "" amountboxcontrol setamounttotal 1060 0, amountconstants format_total_price_only amountboxcontrol additem 3, product_fuel_id, "fuel", 0 0, "pending" return amountboxcontrol } the merchant app can also add new items using the 'additem' method of 'amountcontrolbox' during callback importantyour merchant app needs to call the updatevalue item_id method of amountboxcontrol to update each amount item then call customsheet updatecontrol to make the changes take effect in customsheet eventually, paymentmanager updatesheet 'customsheet' must be called to let samsung pay know that no further action is pending in the merchant app when the custom sheet is updated, the merchant can add new items to amountboxcontrol for example, if the user selects a specific card in the payment sheet which the merchant offers, a discount item can be added via the updatesheet // example for adding new item while updating values val amount = sheet getsheetcontroll "id_amount" amount updatevalue "itemid", 900 0 amount updatevalue "taxid", 50 0 amount updatevalue "shippingid", 10 0 amount updatevalue "fuelid", 0 0 // add “discount” item amount additem 4, "discountid", "discount", -60 0, "" amount setamounttotal 1000 0, amountconstants format_total_price_only sheet updatecontrol amount // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet sheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } applying the spinnercontrol this control is used for displaying spinner options on a payment sheet when creating the control, controlid, title, and sheetitemtype are needed to distinguish between the types of spinner to be displayed your merchant app sets the following properties with spinnercontrol title – the merchant-defined spinner title to appear the payment sheet sheetitemtype – provides various types of spinner a shipping_method_spinner and an installment_spinner are the two types of spinner available as of api level 1 6 noteshipping_method_spinner can be used when the shipping address comes from the samsung wallet app; i e , when the customsheetpaymentinfo addressinpaymentsheet option is set to need_billing_and_shipping or need_ shipping_spay when the shipping address is provided by the merchant app send_shipping or need_billing_ send_shipping , it is not changeable in the payment sheet the shipping fee if applied must be pre-calculated on the merchant app side here’s an example of constructing a spinnercontrol within your merchant app // construct spinnercontrol for shipping method val spinnercontrol = spinnercontrol shippingmethod_spinner_id, "shipping method ", sheetitemtype shipping_method_spinner // let the user can select one shipping method option on the payment sheet spinnercontrol additem "shipping_method_1", getstring android r string standard_shipping_free spinnercontrol additem "shipping_method_2", getstring android r string twoday_shipping spinnercontrol additem "shipping_method_3", getstring android r string oneday_shipping spinnercontrol selecteditemid = "shipping_method_1" // set default option // listen for sheetcontrol events spinnercontrol setsheetupdatedlistener sheetupdatedlistener { updatedcontrolid, customsheet -> val amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol val spinnercontrol = customsheet getsheetcontrol updatedcontrolid as spinnercontrol when spinnercontrol selecteditemid { "shipping_method_1" -> amountboxcontrol updatevalue product_shipping_id, 10 0 "shipping_method_2" -> amountboxcontrol updatevalue product_shipping_id, 10 + 0 1 "shipping_method_3" -> amountboxcontrol updatevalue product_shipping_id, 10 + 0 2 else -> amountboxcontrol updatevalue product_shipping_id, 10 0 } amountboxcontrol setamounttotal 1000 + amountboxcontrol getvalue product_shipping_id , amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } // construct spinnercontrol for installment plan val spinnercontrol = spinnercontrol installment_spinner_id, "installment", sheetitemtype installment_spinner spinnercontrol additem "installment_1", "1 month without interest" spinnercontrol additem "installment_2", "2 months with 2% monthly interest" spinnercontrol additem "installment_3", "3 months with 2 2% monthly interest" spinnercontrol selecteditemid = "installment_1" // set default option // listen for sheetcontrol events spinnercontrol setsheetupdatedlistener sheetupdatedlistener { updatedcontrolid, customsheet -> val amountboxcontrol amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol val spinnercontrol = customsheet getsheetcontrol updatedcontrolid as spinnercontrol val totalinterest = 0 0 when spinnercontrol selecteditemid { "installment1" -> amountboxcontrol updatevalue product_total_interest_id, totalinterest "installment2" -> // calculate total interest again and updatevalue amountboxcontrol updatevalue product_total_interest_id, totalinterest "installment3" -> // calculate total interest again and updatevalue amountboxcontrol updatevalue product_total_interest_id, totalinterest else -> amountboxcontrol updatevalue product_total_interest_id, totalinterest } amountboxcontrol setamounttotal 1000 + amountboxcontrol getvalue product_total_interest_id , amountconstants format_total_price_only customsheet updatecontrol amountboxcontrol // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet customsheet } catch e illegalstateexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } } update sheet with custom error message to display a custom error message on the payment sheet, use updatesheet with customerrormessage fun updatesheet sheet customsheet, errorcode int, customerrormessage string this api method is an extended version of the existing updatesheet sheet method which gives the merchant the ability to display a custom error message in the payment sheet’s authentication area it can be used to inform the user of any foreseen error scenarios encountered // update sheet with custom_messsage error code paymentmanager updatesheet customsheet, paymentmanager custom_message,"phone number entered is not valid please change your phone number " sample issuer app the samsung pay sdk also provides a sample issuer app to showcase samsung pay sdk features issuer app can add card to samsung wallet by selecting specific token service provider tsp from the dropdown menu to add cobadge card you need to select primary and secondary token service providers tsp from the dropdown menus for more information, refer to the samsung pay sdk api reference and sample code
Learn Code Lab
codelabdevelop a secure blockchain app objective learn how to create your own decentralized applications dapp using samsung blockchain keystore sdk overview integrating with new technology like blockchain is a burden to most developers for this reason, we offer a way to interwork with samsung blockchain keystore sdk with less effort developers can easily become a dapp developer with our samsung blockchain keystore sdk decentralized applications dapps run and store data on the blockchain network instead of a central server dapps offer increased security and reliability compared to centralized applications moreover, it provides a simple method for in-app payments using cryptocurrency samsung blockchain keystore sdk is used to obtain account information and sign a transaction to transfer cryptocurrency or execute smart contract execution in this code lab, you can learn how to integrate samsung blockchain keystore sdk into your app and how to implement blockchain basic concepts such as account information and signing transactions set up your environment you will need the following java se development kit 8 or later android studio latest version recommended mobile phone which supports samsung blockchain sample code here is a sample code for you to start coding in this code lab download it and start your learning experience! keystore sdk sample code 897 12 kb enable developer mode the developer mode helps developers test the samsung blockchain keystore in developer mode, app id verification is bypassed, so samsung blockchain keystore apis will be enabled to activate developer mode on your mobile device, follow the steps below navigate through settings > biometrics and security > samsung blockchain keystore and click about blockchain keystore tap the samsung blockchain keystore app name quickly, ten times or more if succeeded, developer mode will show noteonly a limited number of devices can be activated for one test app open project file after downloading the sample code, open the given android application project this project is a simple comments dapp based on ethereum ropsten test network it retrieves comments data from smart contract, displays them on the screen, and makes a transaction to execute smart contract function to post user’s comment in the next steps, you can get an account address and execute dapp service with blockchain keystore and you can see the result of successful dapp execution set the app id here, you don’t need to set the application id to use samsung blockchain keystore sdk instead, you must enable developer mode as described previously for the release version of your android app, in your android manifest file, add a metadata with a name as scw_app_id and a value as the app id issued by samsung blockchain keystore team samsung blockchain keystore aar file will read this value when your android app is initialized and help your android app connect to samsung blockchain keystore <manifest xmlns android="http //schemas android com/apk/res/android" package="com samsung android sdk coldwallet test" android versioncode="1" android versionname="1 0"> <application> <meta-data android name="scw_app_id" android value= <!-- put your app id here --> /> </application> </manifest> import samsung blockchain keystore sdk library into the project the sdk library is located at aar/keystoresdk_v1 5 1 aar of the project file to import the library go to gradle scripts > build gradle and enter the following dependencies dependencies { repositories { flatdir{ dirs 'aar' } } implementation 'com samsung android sdk coldwallet keystoresdk_v1 5 1@aar' } check the status of samsung blockchain keystore the first thing to do is to check the status of samsung blockchain keystore in the sample application, it is implemented at initializekeystore in presenter intropresenter java you can find the following steps to check the status of keystore in your android app, call scwservice getinstance if the returned value is an instance and not null, then it means samsung blockchain keystore is supported on the device however, if null is returned, the user must use a different keystore in the sample code, toast a message to notify that the device doesn’t support the keystore // check samsung blockchain keystore is supported or not if scwservice getinstance == null { mcontract toastmessage "samsung blockchain keystore is not supported on your device " ; } call getkeystoreapilevel api to see if the current samsung blockchain keystore being used, properly supports the features that your android app is currently aiming for if the required api level is higher than the current samsung blockchain keystore level, users are directed to samsung blockchain keystore app page in galaxy store through the provided deeplink to update // check installed api level else if scwservice getinstance getkeystoreapilevel < 1 { // if api level is lower, jump to galaxy apps to update keystore app mcontract showdialog "" , "ok" , "the api level is too low jump to galaxy store" , -> mcontract launchdeeplink scwdeeplink galaxy_store ; } check if a user has set up the samsung blockchain keystore and is ready to use it by calling getseedhash api if the seed hash value in string is zero-length, this means the user has not set up samsung blockchain keystore yet hence, your app will need to guide the user to jump to samsung blockchain keystore via deeplink to either create or import a wallet // check seed hash exist else if scwservice getinstance getseedhash length == 0 { // if seed hash is empty, // jump to blockchain keystore to create or import wallet mcontract showdialog "" , "ok" , "the seed hash is empty " + "jump to blockchain keystore to create/import wallet " , -> mcontract launchdeeplink scwdeeplink main ; } if the getseedhash api returned value is not zero-length, it means that the user has successfully set up samsung blockchain keystore if there is a previously saved or cached seed hash value, compare the two seed hash values if those two values are not equal, nor if there is no such saved cached seed hash value, then the address has to be checked again if the seed hash value has been changed, it means the master seed has been changed as well, meaning the address that your android app was linked to may no longer be the same address // check seed hash cached else if !textutils equals cachedseedhash, scwservice getinstance getseedhash { // if the seed hash is different from cached, update seed hash and address // go to next activity final string ethereumhdpath = "m/44'/60'/0'/0/0"; getethereumaddress ethereumhdpath , success, errorcode, address, seedhash -> { if success { updateaddress address ; updateseedhash seedhash ; mcontract showtimelineactivity true ; } else { mcontract toastmessage "cannot get address error code " + errorcode ; } mcontract setloading false ; } ; return false; } if those two values are equal, it means checking the keystore status was successful, and you can move on to the next step // success else { // set address from cached value // go to next activity string address = prefshelper getinstance getcachedaddress ; updateseedhash cachedseedhash ; updateaddress address ; mcontract showtimelineactivity false ; } get the ethereum address in the blockchain network, the address can be used like a user’s account as the balance and the transaction history can be checked using the address in this sample project, get the address from keystore and display the address and account balance in the bottom sheet of the screen keystore is a hierarchical deterministic hd wallet, a standard tree structure represented by derivation paths for the ethereum address, use “m/44'/60'/0'/0/0” follow bip44 it is implemented at getethereumaddress string hdpath, getethereumaddresscallback callback in presenter/intropresenter java arraylist<string> path = new arraylist<> ; path add hdpath ; scwservice getinstance getaddresslist new scwservice scwgetaddresslistcallback { @override public void onsuccess list<string> list { string seedhash = scwservice getinstance getseedhash ; string address = list get 0 ; callback onaddressreceived true, 0, address, seedhash ; } @override public void onfailure int errorcode, string errormessage { callback onaddressreceived false, errorcode, "", "" ; } }, path ; sign a transaction ether value transfer or smart contract execution is executed by transactions that users create and sign signing a transaction is the process of generating a signature on it using the private key of the transaction sender samsung blockchain keystore can be utilized to sign a cryptocurrency transaction, such as ethereum by implementing the following steps creates an unsigned transaction, and requests samsung blockchain keystore to sign the transaction via apis like signethtransaction then the user will see a transaction confirmation page on a secure screen called, trusted user interface tui executed in trusted execution environment tee by samsung blockchain keystore once the user confirms the transaction with pin or biometrics authentication, like fingerprint, samsung blockchain keystore will sign a transaction with the private key derived from the given hd path when samsung blockchain keystore returns the signed transaction, your app can submit or send the signed transaction to the blockchain network in this sample project, create an unsigned transaction to execute posting a comment smart contract in addition, sign the transaction with keystore and send the transaction it is implemented at signtransaction in presenter/writefeedpresenter java // sign the transaction with samsung blockchain keystore // use hdpath m/44'/60'/0'/0/0 final string hdpath = "m/44'/60'/0'/0/0"; scwservice getinstance signethtransaction new scwservice scwsignethtransactioncallback { @override public void onsuccess byte[] signedtransaction { boolean result = sendsignedtransaction signedtransaction ; listener transactiondidfinish result, "" ; } @override public void onfailure int errorcode, string errormessage { listener transactiondidfinish false, "error code " + errorcode ; } }, unsignedtx, hdpath, null ; run the app and try it out the app screen should look like below you're done! congratulations! you have successfully achieved the goal of this code lab now, you can create a decentralized app by yourself! if you're having trouble, you may download this file keystore sdk complete code 897 07 kb
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 interface apptoappconstants all known implementing classes cardmanager, watchmanager public interface apptoappconstants this interface provides the common values of watchmanager and cardmanager since api level 2 5 field summary fields modifier and type field description static final int error_auth_code_expired this error indicates that auth code is expired this is returned as spaysdk extra_error_reason for error_verify_card error static final int error_auth_code_invalid this error indicates that auth code is invalid this is returned as spaysdk extra_error_reason for error_verify_card error static final int error_auth_code_max_try_reached this error indicates that maximum idnv try reached this is returned as spaysdk extra_error_reason for error_verify_card error static final int error_auth_code_type_invalid this error indicates that auth code type is invalid this is returned as spaysdk extra_error_reason for error_verify_card error static final int error_authentication_closed this error indicates that authentication is force closed during update card service static final int error_authentication_failed this error indicates that authentication is failed during update card service static final int error_authentication_not_ready this error indicates that authentication is not ready state during update card service static final int error_authentication_timed_out this error indicates that authentication is closed due to timeout during update card service static final int error_card_already_registered this error indicates that the requested operation is already done and this operation cannot be performed again this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_card_idv_not_supported this error indicates that the card does not support any idnv this is returned as spaysdk extra_error_reason for error_verify_card error static final int error_card_not_supported this error indicates that card is not supported this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_framework_internal this error indicates that an error occurred in payment framework while processing the request this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error for example, unable to load certificate from ta, unable to access payment framework db, and so on static final int error_invalid_card this error indicates that the card is invalid this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_invalid_cardinput this error indicates that the user entered invalid card information this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_max_card_num_reached this error indicates that the maximum number of card limit has reached and user cannot add more card to samsung pay this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_max_pan_provision_num_reached this error indicates that the limit number of enrollments of this pan has reached and user cannot add this pan this time static final int error_server_reject this error indicates that the server declined the request this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final int error_tsm_fail this error indicates that tsm error is reported during card downloading static final int error_verify_card this error indicates that server was unable to verify the card operation this may be due to invalid verification code static final int error_wallet_id_mismatch this error indicates that wallet id is mismatch this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error static final string extra_app2app_intent key to represent app2app intent name defined by issuer server static final string extra_app2app_payload key to represent app2app payload sent by issuer server static final string extra_card_balance key to represent card balance static final string extra_card_status_reason key to represent extra card status for issuer app static final string extra_issuer_app_card_linked key to represent extra card information for card link field details error_verify_card static final int error_verify_card this error indicates that server was unable to verify the card operation this may be due to invalid verification code since api level 1 2 see also constant field values error_card_already_registered static final int error_card_already_registered this error indicates that the requested operation is already done and this operation cannot be performed again this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 1 2 see also constant field values error_framework_internal static final int error_framework_internal this error indicates that an error occurred in payment framework while processing the request this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error for example, unable to load certificate from ta, unable to access payment framework db, and so on since api level 1 2 see also constant field values error_invalid_card static final int error_invalid_card this error indicates that the card is invalid this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 1 2 see also constant field values error_invalid_cardinput static final int error_invalid_cardinput this error indicates that the user entered invalid card information this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 1 2 see also constant field values error_server_reject static final int error_server_reject this error indicates that the server declined the request this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 1 2 see also constant field values error_max_card_num_reached static final int error_max_card_num_reached this error indicates that the maximum number of card limit has reached and user cannot add more card to samsung pay this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 1 2 see also constant field values error_tsm_fail static final int error_tsm_fail this error indicates that tsm error is reported during card downloading this is for tsm solution only since api level 1 4 see also constant field values error_authentication_not_ready static final int error_authentication_not_ready this error indicates that authentication is not ready state during update card service since api level 1 8 see also constant field values error_authentication_failed static final int error_authentication_failed this error indicates that authentication is failed during update card service since api level 1 8 see also constant field values error_authentication_closed static final int error_authentication_closed this error indicates that authentication is force closed during update card service since api level 1 8 see also constant field values error_authentication_timed_out static final int error_authentication_timed_out this error indicates that authentication is closed due to timeout during update card service since api level 1 8 see also constant field values error_card_not_supported static final int error_card_not_supported this error indicates that card is not supported this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 2 5 see also constant field values error_max_pan_provision_num_reached static final int error_max_pan_provision_num_reached this error indicates that the limit number of enrollments of this pan has reached and user cannot add this pan this time user needs to contact issuer to resolve this issue this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 2 5 see also constant field values error_wallet_id_mismatch static final int error_wallet_id_mismatch this error indicates that wallet id is mismatch this is returned as spaysdk extra_error_reason for spaysdk error_registration_fail error since api level 2 5 see also constant field values error_auth_code_invalid static final int error_auth_code_invalid this error indicates that auth code is invalid this is returned as spaysdk extra_error_reason for error_verify_card error since api level 2 7 see also constant field values error_auth_code_expired static final int error_auth_code_expired this error indicates that auth code is expired this is returned as spaysdk extra_error_reason for error_verify_card error since api level 2 7 see also constant field values error_auth_code_max_try_reached static final int error_auth_code_max_try_reached this error indicates that maximum idnv try reached this is returned as spaysdk extra_error_reason for error_verify_card error since api level 2 7 see also constant field values error_auth_code_type_invalid static final int error_auth_code_type_invalid this error indicates that auth code type is invalid this is returned as spaysdk extra_error_reason for error_verify_card error since api level 2 7 see also constant field values error_card_idv_not_supported static final int error_card_idv_not_supported this error indicates that the card does not support any idnv this is returned as spaysdk extra_error_reason for error_verify_card error since api level 2 7 see also constant field values extra_app2app_intent static final string extra_app2app_intent key to represent app2app intent name defined by issuer server since api level 1 1 see also constant field values extra_app2app_payload static final string extra_app2app_payload key to represent app2app payload sent by issuer server since api level 1 1 see also constant field values extra_card_balance static final string extra_card_balance key to represent card balance since api level 1 8 see also constant field values extra_card_status_reason static final string extra_card_status_reason key to represent extra card status for issuer app since api level 1 4 see also constant field values extra_issuer_app_card_linked static final string extra_issuer_app_card_linked key to represent extra card information for card link since api level 2 2 see also constant field values samsung electronics samsung pay sdk 2 22 00 - nov 19 2024
Develop Samsung Internet
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
Learn Code Lab
codelabcreate an android automotive operating system aaos app with payments via samsung checkout objective create a shopping app for android automotive os aaos , which uses templates from aaos and ignite store, and processes payments via the ignite payment sdk powered by samsung checkout partnership request to use the ignite payment sdk and have access to development tools and resources, such as ignite aaos emulators, you must become an official partner once done, you can fully utilize this code lab you can learn more about the partnership process by visiting the ignite store developer portal overview android automotive os android automotive os aaos is a base android platform that runs directly on the car and is deeply integrated with the underlying vehicle hardware unlike the android auto platform, users can download compatible apps with aaos directly into their cars, without needing a phone, and utilize an interface specifically designed for the car screen aaos can run both system and third-party android applications as aaos is not a fork and shares the same codebase as android for mobile devices, developers can easily adapt existing smartphone apps to function on aaos the diagram below illustrates the architecture of aaos at the hardware abstraction layer hal level, aaos incorporates additional components such as the vehicle hal vhal , exterior view system evs , and broadcast radio br to handle vehicle properties and connectivity at the framework level, car service and webview modules are included at the application level, the main system applications include car system ui, car launcher, and car input method editor ime additionally, car media and automotive host are incorporated as system apps third-party apps are classified into three categories audio media, car templated, and parked car templates the car templated apps use templates specified by the car app library, which are rendered by the automotive host, customized by original equipment manufacturers oem the library consists of approximately 10 templates list, grid, message, pane, navigation and is utilized in both android auto aa and android automotive os aaos apps to target aaos, you must incorporate an additional app-automotive library that injects the carappactivity into the app the carappactivity needs to be included in the manifest and can be set as distractionoptimized upon launching the application, the carappactivity provides a surface that is employed by the automotive host to render the template models additionally, on the harman ignite store, you can optionally integrate the ignite-car-app-lib, which adds supplementary templates such as explore, listdetails, routeoverview, and poistreaming harman ignite store the harman ignite store is a white-labeled and modular aaos-based automotive app store by connecting app developers with car manufacturers, harman creates unique in-vehicle experiences the ignite store has a rich app ecosystem with unique content, growth opportunities, and long-term partnerships it facilitates future-proof monetization with a payments api powered by samsung checkout after registering at the ignite store developer portal, developers can submit their apps for certification and testing by harman upon approval from the oem, the developer can proceed with publishing their app comprehensive developer documentation and tools are available to support app developers throughout the development process payments api the ignite store comes enabled with payment features empowering developers to monetize their apps developers are now able to offer their apps as paid apps the payment sdk exposes apis for goods and services, in-app purchases, and subscriptions developers can also integrate their own payment service providers psps , to sell goods or services, and receive the money directly in their bank account for a frictionless in-car payment experience, ignite provides a dedicated digital wallet app for end-users to securely store their credit card information the payment processor is powered by the industry proven samsung checkout the developer portal provides additional documentation to allow developers to access ignite aaos emulators, vim3, tablet or cuttlefish ignite images, and additional guidelines set up your environment you will need the following ignite aaos system image running on android emulator or on reference devices android studio latest version recommended java se development kit jdk 11 or later sample code here is a sample code for you to start coding in this code lab download it and start your learning experience! aaos ignite shopping app sample code 11 7 mb prepare your ignite aaos emulator add the ignite aaos emulator to your android studio by following the guide provided in the ignite store developer console open the device manager and start the emulator configure the emulator to use fake data for payments, as instructed in the ignite store developer console under the offline mode tab in the payment sdk section the sample app requires navigation from point a starting location to point b destination location the destination addresses are predefined and near san jose mcenery convention center to shorten the distance between two locations, follow the steps below to set the starting location a open the extended controls in the emulator panel b go to location, search for a location near the destination location, and click set location next, in the emulator, go to the ignite navigation app's settings and enable the following enable navigation simulation enable mock location provider go to settings > system > developer options > location and set ignite navigation as mock location app start your project after downloading the sample code containing the project files, open your android studio and click open to open an existing project locate the downloaded android project igniteautomotivepaymentssdc202488 from the directory and click ok check the ignite payment sdk dependency verify that the ignite payment sdk library is included in the dependencies section of the module's build gradle file dependencies { implementation files 'libs/ignite-payment-sdk-3 13 0 24030417-0-snapshot aar' } add payment permission next, go to the manifests folder and, in the androidmanifest xml file, include the payment_request permission to perform in-app purchases <uses-permission android name="com harman ignite permission payment_request" /> this ensures that the app has the necessary permissions to perform transactions and handle sensitive financial data show the payment screen when an item is added to the cart, the shopping cart screen displays the select store button, selected pickup store address, total amount to pay, and details of each item added the screen also includes the pay button go to kotlin + java > com harman ignite pickupstore > screens > shoppingcartscreen kt in the docheckout function, use the car app's screenmanager to navigate to the payment screen from the shopping cart screen after clicking the pay button getscreenmanager push paymentscreen carcontext, session notethe screenmanager class provides a screen stack you can use to push screens that can be popped automatically when the user selects a back button in the car screen or uses the hardware back button available in some cars instantiate the ignite payment client the ignite payment api provides a singleton class called ignitepaymentclientsingleton, which enables performing and tracking transactions navigate to the paymentscreen kt file and instantiate the ignite payment client private val mipc = ignitepaymentclientsingleton getinstance carcontext define the ignite payment transaction callback the ignite payment transaction provides three callback methods onsuccess, oncanceled, and onfailure after each callback, make sure to set the ispaymentfailed variable to track whether a payment is successful or not update the session which owns the shopping cart screen to reflect the status of the payment transaction call the updatetemplate function to invalidate the current template and create a new one with updated information private val mipctcb = object iignitepaymentclienttransactioncallback { override fun onsuccess requestuuid string?, sessionid string?, successmessage string?, paymentadditionalproperties hashmap<string, string>? { log d tag, log_prefix + "onsuccess rid $requestuuid, sid $sessionid, sm $successmessage" cartoast maketext carcontext, "payment successful", cartoast length_short show ispaymentfailed = false session paymentdone requestuuid, sessionid, successmessage updatetemplate } override fun oncanceled requestuuid string?, sessionid string? { log d tag, log_prefix + "oncanceled rid $requestuuid, sid $sessionid" cartoast maketext carcontext, "payment canceled", cartoast length_long show ispaymentfailed = true session paymenterror requestuuid, sessionid, null updatetemplate } override fun onfailure requestuuid string?, sessionid string?, wallererrorcode int, errormessage string { log d tag, log_prefix + "onfailure rid $requestuuid, sid $sessionid, wec $wallererrorcode, em $errormessage" cartoast maketext carcontext, "payment failed", cartoast length_long show ispaymentfailed = true session paymenterror requestuuid, sessionid, errormessage updatetemplate } } define the ignite payment client connection callback the ignite payment client needs to be connected in order to perform a payment request once the client connects successfully, retrieve the names of the shopping cart items and use them to create an order summary afterwards, construct an ignite payment request containing the total amount, currency code, merchant id, and details of the order summary then, initiate the payment process by invoking the readytopay function of the ignite payment client api private val mipccb = iignitepaymentclientconnectioncallback { connected -> log d tag, log_prefix + "onpaymentclientconnected $connected" if connected { val textsummary = session shoppingcart cartitems jointostring ", " { item -> item name } val ipr = ignitepaymentrequest builder setamount session shoppingcart gettotal * 100 setcurrencycode currencycode usd setpaymentoperation paymentoperation purchase setmerchantid constants merchant_id setordersummary ordersummary builder setordersummarybitmapimage bitmapfactory decoderesource carcontext resources, session shoppingcart store largeicon setordersummarylabel1 "${carcontext getstring r string pickupstore_app_title } ${session shoppingcart store title}" setordersummarysublabel1 session shoppingcart store address setordersummarylabel2 textsummary setordersummarysublabel2 carcontext getstring r string pickupstore_payment_sublabel2 build build try { mipc readytopay ipr, mipctcb } catch e exception { log d tag, log_prefix + "payment exception $e" e printstacktrace } catch e error { log d tag, log_prefix + "payment error $e" e printstacktrace } } } start the payment process and go back to previous screen after the transaction next, in the startpayment function, connect the ignite payment client and the connection callback to start the payment process mipc connect mipccb after the transaction is completed, the updatetemplate function refreshes the template used in the payment screen before calling the schedulegoback function modify the schedulegoback function to navigate back to the previous template screen shopping cart you can use the pop method of the screenmanager screenmanager pop start the navigation to the store to collect the paid pickup the shopping cart screen shows the pickup store location, details of the order, and go to store button after a successful payment go to kotlin + java > com harman ignite pickupstore > pickupstoresession kt modify the navigatetostore geofence geofence function to trigger the navigation to the pickup store when the go to store button is clicked you can use the intent carcontext action_navigate with geo schema rfc 5879 data, containing latitude and longitude e g , geo 12 345, 14 8767 to send the intent, use the carcontext startcarapp api call val geouristring = "geo ${geofence latitude},${geofence longitude}" val uri = uri parse geouristring val navintent = intent carcontext action_navigate, uri try { carcontext startcarapp navintent } catch e exception { log e tag, log_prefix + "navigatetostore exception starting navigation" e printstacktrace cartoast maketext carcontext, "failure starting navigation", cartoast length_short show } run the app on ignite aaos emulator run the pickup-store-app on ignite aaos emulator when the app starts for the first time, it requests for user permissions click grant permissions choose allow all the time for location permission and click the return button 4 browse the pickup store catalog and add items to shopping cart open the shopping cart and click pay you can also change the pickup store by clicking select store check the order summary and billing information then, click confirm and pay to process payment after a successful payment, the app returns to shopping cart screen with the updated transaction information click go to store to start the navigation to the store the app displays a notification when the car is near the store click the notification to show a reference qr code to present to the store upon pick up you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can create an aaos templated app, which supports payments by yourself! if you're having trouble, you may download this file aaos ignite shopping app complete code 11 7 mb learn more by going to the developer console section of the ignite store developer portal
Learn Code Lab
codelabintegrate in-app payment into merchant apps using samsung pay sdk objective learn how to integrate in-app payment with your merchant apps using samsung pay sdk partnership request to use the samsung pay sdk, 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 page, here in samsung developers notein accordance with the applicable samsung partner agreements, this code lab covers setup and use of the samsung pay sdk for purposes of integrating the samsung pay app with partner apps the use cases and corresponding code samples included are representative examples only and should not be construed as either recommended or required overview the samsung pay sdk is an application framework for integrating selected samsung pay features with android-based partner apps on samsung devices in-app payment, which allows customers to pay for products and services with samsung pay, is one of the operations supported alongside push provisioning and open favorite cards partner apps can leverage the samsung pay sdk to perform different operations ― push provisioning and open favorite cards for issuers; in-app payment for merchants key components include partner app app developed by merchant or issuer for making online or offline payments and provisioning payment cards through samsung pay samsung pay sdk sdk integrated into the partner app for direct communication with samsung pay samsung pay app pay app with which the samsung pay sdk communicates financial network comprises the payment gateways, acquirers, card associations, and issuers that participate in transaction processing under agreement with the merchant most common use case for in-app payment the merchant app allows the user to make payments with samsung pay upon user selection of the samsung pay option, the merchant app calls the apis included in the samsung pay sdk to initiate a transaction with the samsung pay app the samsung pay app responds with the tokenized payment information necessary to complete the transaction the merchant app forwards this payment information to the designated payment gateway pg , either directly through the merchant's web server or indirectly via the samsung-pg interface server for standard transaction processing for more detailed information, see the official samsung pay sdk programming guide set up your environment you will need the following samsung wallet or samsung pay app depending on the country a compatible mobile device with android marshmallow 6 0 or android api level 23 or later android os versions samsung pay sdk android studio latest version recommended java se development kit jdk 11 or later 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 sample code 1 90 mb integrate the samsung pay sdk with your app the following steps comprise the general process for integrating the samsung pay sdk with your app sign up for the samsung pay developers site by clicking sign up and register your samsung account or create it if you don't already have one , then sign in follow the on-screen instructions for adding your app and creating a new service to generate the service id you'll need to use in your project download the samsung pay sdk by going to resources > sdk download add the samsung pay sdk jar file samsungpay jar to your android project using android studio or file explorer develop your partner app with the required api calls and callbacks for samsung pay integration upload a release version of your app to the samsung pay developers site for approval upon samsung approval, publish your partner app to the google play store and samsung galaxy apps 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 using the provided test service id enforces your app to use the fixed properties below service id 0915499788d6493aa3a038 package name com test beta pay app version 1 0/ 1 or higher start your project after downloading the sample code containing the project files, in android studio click open to open existing project locate the downloaded android project sampleonlinepay from the directory and click ok add the samsungpaysdk_2 18 00_release jar file from the sdk's libs folder to your android project's libs folder go to gradle scripts > build gradle module sampleonlinepay app and enter the following to the dependencies block implementation files 'libs/samsungpaysdk_2 18 00_release jar' if the target sdk version is 30 android 11 or the r-os , you must include the following <queries> element in androidmanifest xml <queries> <package android name="com samsung android spay" /> </queries> configure the api level as of sdk version 1 4, enhanced version control management has been introduced to improve backward compatibility and handle api dependency from country and service type for example, if a partner integrates the latest sdk—for instance, api level 2 18—but continues to use apis based on level 1 4, the partner app remains compatible with samsung pay apps supporting api level 1 4 without upgrading the samsung pay app implement the following in application tag of androidmanifest xml <meta-data android name="spay_sdk_api_level" android value="2 17" /> // most recent sdk version is recommended to leverage the latest apis add an xml layout and modify the activity next, replace the xml layout in res > layout > activity_main xml this layout shows the sample item information such as image, name, and price <?xml version="1 0" encoding="utf-8"?> <layout xmlns tools="http //schemas android com/tools" xmlns app="http //schemas android com/apk/res-auto" xmlns android="http //schemas android com/apk/res/android"> <androidx constraintlayout widget constraintlayout android layout_width="match_parent" android layout_height="match_parent" tools context=" mainactivity"> <imageview android id="@+id/imageview" android layout_width="350dp" android layout_height="184dp" android layout_margintop="100dp" app layout_constraintend_toendof="parent" app layout_constraintstart_tostartof="parent" app layout_constrainttop_totopof="parent" android src="@drawable/galaxy_s23_ultra_image"/> <imageview android id="@+id/samsung_pay_button" android layout_width="wrap_content" android layout_height="75dp" app layout_constraintbottom_tobottomof="parent" app layout_constraintend_toendof="parent" app layout_constraintstart_tostartof="parent" android src="@drawable/pay_rectangular_full_screen_black" android visibility="invisible"/> <textview android id="@+id/textview" android layout_width="wrap_content" android layout_height="wrap_content" android layout_margintop="10dp" android text="galaxy s23 ultra" android textsize="16sp" android textstyle="bold" app layout_constraintend_toendof="parent" app layout_constraintstart_tostartof="parent" app layout_constrainttop_tobottomof="@+id/imageview" /> <textview android id="@+id/textview2" android layout_width="wrap_content" android layout_height="wrap_content" android layout_margintop="5dp" android text="$1,199 00" android textsize="14sp" app layout_constraintend_toendof="parent" app layout_constrainthorizontal_bias="0 517" app layout_constraintstart_tostartof="parent" app layout_constrainttop_tobottomof="@+id/textview" /> </androidx constraintlayout widget constraintlayout> </layout> since you added a data binding layout, you need to inflate the xml file differently go to java > com > test > beta > pay > mainactivity kt, and declare the databinding variable in the mainactivity class private lateinit var databinding activitymainbinding replace the standard setcontentview declaration with the data binding version inside the oncreate method databinding = databindingutil setcontentview this, r layout activity_main check samsung pay status in the mainactivity, create the samsungpay instance to determine if the device supports samsung pay and if the samsung pay button can be displayed as the user's payment option, check the samsung pay status samsungpay requires a valid partnerinfo from the merchant app, which consists of service id and service type during onboarding, the samsung pay developers site assigns the service id and service type in the mainactivity, declare the partnerinfo variable private lateinit var partnerinfo partnerinfo then, set the partnerinfo in the oncreate method val bundle = bundle bundle putstring spaysdk partner_service_type, spaysdk servicetype inapp_payment tostring partnerinfo = partnerinfo service_id, bundle after setting partnerinfo, call the getsamsungpaystatus method via updatesamsungpaybutton function inside the oncreate method updatesamsungpaybutton the getsamsungpaystatus method of the samsungpay class must be called before using any other feature in the samsung pay sdk write the updatesamsungpaybutton function as follows private fun updatesamsungpaybutton { val samsungpay = samsungpay this, partnerinfo samsungpay getsamsungpaystatus object statuslistener { override fun onsuccess status int, bundle bundle { when status { spaysdk spay_ready -> { databinding samsungpaybutton visibility = view visible // perform your operation } spaysdk 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 databinding samsungpaybutton visibility = view invisible } spaysdk spay_not_allowed_temporally -> { // if extra_error_reason is error_spay_connected_with_external_display, // guide user to disconnect it databinding samsungpaybutton visibility = view invisible } spaysdk spay_not_supported -> { databinding samsungpaybutton visibility = view invisible } else -> databinding samsungpaybutton visibility = view invisible } } override fun onfail errorcode int, bundle bundle { databinding samsungpaybutton visibility = view invisible toast maketext applicationcontext, "getsamsungpaystatus fail", toast length_short show } } } tipfor the list and detailed definition of status codes such as spay_ready, refer to checking samsung pay status noteas of sdk version 1 5, if the device has android lollipop 5 1 android api level 22 or earlier versions, the getsamsungpaystatus api method returns a spay_not supported status code merchant apps using sdk 1 4 or earlier must check their app's android version activate the samsung pay app the samsungpay class provides an api method called activatesamsungpay to activate the samsung pay app on the same device where the partner app is running if the getsamsungpaystatus returns spay_not_ready and the extra_error_reason is error_spay_setup_not_complete, the partner app needs to display an appropriate message to the user then, call activatesamsungpay to launch samsung pay app and request the user to sign in in updatesamsungpaybutton function, add the code to call activatesamsungpay method via doactivatesamsungpay function when the status is spay_not_ready // if extra_error_reason is error_spay_setup_not_completed, // call activatesamsungpay val extraerror = bundle getint samsungpay extra_error_reason if extraerror == samsungpay error_spay_setup_not_completed { doactivatesamsungpay spaysdk servicetype inapp_payment tostring } create the doactivatesamsungpay function as below private fun doactivatesamsungpay servicetype string { val bundle = bundle bundle putstring samsungpay partner_service_type, servicetype val partnerinfo = partnerinfo service_id, bundle val samsungpay = samsungpay this, partnerinfo samsungpay activatesamsungpay } create a transaction request upon successfully initializing the samsungpay class, the merchant app should create a transaction request with payment information samsung pay offers two types of online payment sheet―normal and custom the normal payment sheet has fixed display items ― items, tax, and shipping the custom payment sheet offers more dynamic controls for customizing the ui, together with additional customer order and payment data for this code lab, use the custom payment sheet and populate the fields in customsheetpaymentinfo to initiate a payment transaction /* * make user's transaction details * the merchant app should send paymentinfo to samsung pay via the applicable samsung pay sdk api method for the operation * being invoked * upon successful user authentication, samsung pay returns the "payment info" structure and the result string * the result string is forwarded to the pg for transaction completion and will vary based on the requirements of the pg used * the code example below illustrates how to populate payment information in each field of the paymentinfo class */ private fun maketransactiondetailswithsheet customsheetpaymentinfo? { val brandlist = brandlist val extrapaymentinfo = bundle val customsheet = customsheet customsheet addcontrol makeamountcontrol return customsheetpaymentinfo builder setmerchantid "123456" setmerchantname "sample merchant" setordernumber "amz007mar" // if you want to enter address, please refer to the javadoc // reference/com/samsung/android/sdk/samsungpay/v2/payment/sheet/addresscontrol html setaddressinpaymentsheet customsheetpaymentinfo addressinpaymentsheet do_not_show setallowedcardbrands brandlist setcardholdernameenabled true setrecurringenabled false setcustomsheet customsheet setextrapaymentinfo extrapaymentinfo build } private fun makeamountcontrol amountboxcontrol { val amountboxcontrol = amountboxcontrol amount_control_id, "usd" amountboxcontrol additem product_item_id, "item", 1199 00, "" amountboxcontrol additem product_tax_id, "tax", 5 0, "" amountboxcontrol additem product_shipping_id, "shipping", 1 0, "" amountboxcontrol setamounttotal 1205 00, amountconstants format_total_price_only return amountboxcontrol } private val brandlist arraylist<spaysdk brand> get { val brandlist = arraylist<spaysdk brand> brandlist add spaysdk brand visa brandlist add spaysdk brand mastercard brandlist add spaysdk brand americanexpress brandlist add spaysdk brand discover return brandlist } request payment with a custom payment sheet the startinapppaywithcustomsheet method of the paymentmanager class is applied to request payment using a custom payment sheet in samsung pay when you call the startinapppaywithcustomsheet method, a custom payment sheet is displayed on the merchant app screen from there, the user can select a registered card for payment and change the billing and shipping addresses as necessary the payment sheet lasts for 5 minutes after calling the api if the time limit expires, the transaction fails in the mainactivity class, declare the paymentmanager variable private lateinit var paymentmanager paymentmanager then, in oncreate , set an onclicklistener method before calling the updatesamsungpaybutton function to trigger the startinapppaywithcustomsheet function when the samsungpaybutton is clicked databinding samsungpaybutton setonclicklistener { startinapppaywithcustomsheet } lastly, create a function to call startinapppaywithcustomsheet method of the paymentmanager class /* * paymentmanager startinapppaywithcustomsheet is a method to request online in-app payment with samsung pay * partner app can use this method to make in-app purchase using samsung pay from their * application with custom payment sheet */ private fun startinapppaywithcustomsheet { paymentmanager = paymentmanager applicationcontext, partnerinfo paymentmanager startinapppaywithcustomsheet maketransactiondetailswithsheet , transactioninfolistener } /* * customsheettransactioninfolistener is for listening callback events of online in-app custom sheet payment * this is invoked when card is changed by the user on the custom payment sheet, * and also with the success or failure of online in-app payment */ private val transactioninfolistener paymentmanager customsheettransactioninfolistener = object paymentmanager customsheettransactioninfolistener { // this callback is received when the user changes card on the custom payment sheet in samsung pay override fun oncardinfoupdated selectedcardinfo cardinfo, customsheet customsheet { /* * called when the user changes card in samsung pay * newly selected cardinfo is passed and partner app can update transaction amount based on new card if needed * call updatesheet method this is mandatory */ paymentmanager updatesheet customsheet } override fun onsuccess response customsheetpaymentinfo, paymentcredential string, extrapaymentdata bundle { /* * you will receive the payloads shown below in paymentcredential parameter * the output paymentcredential structure varies depending on the pg you're using and the integration model direct, indirect with samsung */ toast maketext applicationcontext, "onsuccess ", toast length_short show } // this callback is received when the online payment transaction has failed override fun onfailure errorcode int, errordata bundle? { toast maketext applicationcontext, "onfailure ", toast length_short show } } run the app after building the apk, you can run the sample merchant app and see how it connects to samsung pay upon clicking the button at the bottom of the screen to thoroughly test the sample app, you must add at least one card to the samsung pay app you're done! congratulations! you have successfully achieved the goal of this code lab now, you can integrate in-app payment with your app by yourself! if you face any trouble, you may download this file in-app payment complete code 2 26 mb to learn more about developing apps for samsung pay devices, visit developer samsung com/pay
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.