Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials mobile
blogdigital identity verification has become a rising topic in the current technological landscape. samsung wallet allows samsung galaxy device users to securely register their state-issued us driver's license in their device, letting them use it as a mobile driver's license (mdl). through the "verify with wallet" (vww) functionality, samsung wallet provides android developers with the ability to authenticate a user's identity directly from their application by utilizing the user's registered mdl on the device. the implementation of the functionality is based on and is fully compliant with the iso 18013-5 standard. in this article, we explore the complete process of implementing verify with wallet in an android application. prerequisites in order to complete the tasks in this article and implement a complete sample application for verifying a user's identity, you need the following: valid us driver's license or state id us region samsung galaxy device with mdl support complete the samsung wallet partner onboarding process understanding the verify with wallet process samsung wallet offers a native relying party (rp) sdk for android applications. rp sdk is an app2app sdk designed for enabling samsung wallet's mdl service in online use cases. by integrating this sdk, you can leverage the vww functionality within their applications. in your application, you need to create a json object for defining the request and a json payload for the relying party card. then, you can utilize the rp sdk to create a valid mdoc request using the provided information. finally, the request needs to be sent to the samsung wallet application. in response, samsung wallet sends an encrypted response back to the application, which contains the requested information in a cbor encoded format. the application can then decode the provided data and use it as necessary. refer to the iso 18013-5 standard, aamva mdl guidelines and the samsung wallet documentation for a better understanding of the vww process. implementing the verify with wallet functionality in your android application the process of implementing vww in an android application includes creating a relying party card for samsung wallet, downloading and integrating the rp sdk into the android application and implementing the necessary functions in the android application for completing the verification process. creating a relying party wallet card template in the samsung wallet partners portal in order to implement and use the vww functionality, you need a wallet card of the relying party type for this purpose. to create a relying party wallet card template: go to the samsung wallet partners portal. select wallet card > create wallet cards. from wallet card templates, select relying party. select the applicable service location and authentication issuer from the advanced setting section. make sure to select the proper values for the card, otherwise the verification process may not work. figure 1: creating a relying party card for vww integrating the rp sdk in an android application once the relying party card template has been created, we can download and integrate the rp sdk to work with the android application. step 1: download the rp sdk for android to download the rp sdk: download the zip file containing the latest rp sdk release aar file from samsung wallet code resources on the samsung developer website. extract the aar file from the downloaded zip file. copy and paste the downloaded rp-sdk-x.xx-release.aar file inside a new directory in the android studio project (for example, \libs\). step 2: add android manifest permissions to implement the verify with wallet functionality, the application needs both the internet access permission and the ability to query the installed samsung wallet application. to provide the application with these permissions, open the androidmanifest.xml file in the android studio project and add the following lines: <uses-permission android:name="android.permission.internet" /> <queries> <package android:name="com.samsung.android.spay" /> </queries> step 3: add gradle dependencies in the application's build.gradle file, load the rp sdk aar file and the necessary additional dependencies for using the sdk, as follows: // load rp sdk aar file implementation(files("libs/rp-sdk-1.05-release.aar")) //cbor decoding dependencies implementation("com.upokecenter:cbor:4.0.1") implementation("com.augustcellars.cose:cose-java:1.1.0") // other dependencies implementation("com.google.code.gson:gson:2.11.0") implementation("org.bouncycastle:bcprov-jdk15to18:1.66") implementation("com.nimbusds:nimbus-jose-jwt:9.37.3") 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") after these steps, the rp sdk is ready for use in your android application. configuring the android application for verify with wallet next, we need to complete the implementation of the verify with wallet functionality in your android application. step 1: build a card payload for the relying party card first, we need to create a request payload for the relying party card following the specification. private fun buildapp2apppayload(): string { return payload .replace("{refid}", uuid.randomuuid().tostring()) .replace("{createdat}", system.currenttimemillis().tostring()) .replace("{updatedat}", system.currenttimemillis().tostring()) } private val payload = """ { "card": { "type": "relyingparty", "data": [ { "createdat": {createdat}, "updatedat": {updatedat}, "language": "en", "refid": "{refid}", "attributes": { "clientpackagename": "com.ahsan.verifyappsample", "clienttype": "app", "fontcolor": "#ffffff", "logoimage": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "logoimage.darkurl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "logoimage.lighturl": "https://kr-cdn-gpp.mcsvc.samsung.com/mcp25/resource/2024/9/4/b940b7a2-0f55-42ce-8da7-025d50dbb6b7.png", "providername": "samsung verification sample" } } ] } } """.trimindent() step 2: build the applink the applink is a tokenized url that is similar to the cdata tokens used for samsung wallet cards. the samsung wallet rp sdk includes a function to generate the applink using the payload and the partner credentials (private key, public key, partner id, card id, certificate id, etc.). to build the applink, you can simply call the rpclientapis.buildapplink() function with the required parameters: val rpclientapis = rpclientapis(this) val applink = rpclientapis.buildapplink( partnerid = partner_id, cardid = card_id, payload = buildapp2apppayload(), samsungpublickey = samsung_certificate, partnerpublickey = partner_certificate, partnerprivatekey = partner_private_key, partnercertificateid = certificate_id, isstagingserver = true ) step 3: build the request data finally, once the applink creation is complete, we can send the verification request using the rp sdk. before sending the request, we need to specify exactly which information we wish to retrieve. for this purpose, we need to create a json document following the iso 18013-5 specification and specify the fields we wish to retrieve in the response. it is possible to request for the following fields in the request data under the "org.iso.18013.5.1" namespace: portrait family_name given_name document_number age_in_years resident_address birth_date issue_date expiry_date sex height weight_range weight eye_colour hair_colour organ_donor driving_privileges veteran additionally, it is also possible to request for the following 3 fields, under the "org.iso.18013.5.1.aamva" namespace: domestic_driving_privileges dhs_compliance edl_credential in our example, we only try to retrieve the following 4 fields: family_name, age_in_years, issue_date, and expiry_date. in the following code example, we build the request string accordingly: val requestdata = """ { "doctype": "org.iso.18013.5.1.mdl", "namespaces": { "org.iso.18013.5.1": { "family_name": true, "age_in_years": true, "issue_date": true, "expiry_date": true } } } """.trimindent() step 4: create the onresponselistener class when using the vww rp sdk, it is necessary to create a listener class for both sending the request and for receiving and processing the response from the mdoc server. for our example, let's create an empty placeholder onresponselistener class which extends the rp sdk's onresponselistener class. class onresponselistener(private val requestdata: string) : rpclientapis.onresponselistener{ override fun ongetmdocrequestdata(deviceengagementbytes: bytearray): bytearray? { todo("not yet implemented") } override fun onmdocresponse(encryptedresponsebytes: bytearray) { todo("not yet implemented") } override fun onmdocresponsefailed(exception: exception) { log.e(tag, "response processing failed", exception) } } initiating the verification request to initiate the identity verification process, we need to establish a secure session and send a structured request to the samsung wallet application. we can use the previously created onresponselistener class for this purpose. step 1: define the ongetmdocrequestdata() function for sending the request data inside the ongetmdocrequestdata() function, we need to do 2 things for establishing a secure encrypted session: generate an elliptic curve key pair build session establishment bytes following the iso-18013-5 specification. once the key pair is generated, we can use this key pair, the device engagement bytes, and the previously created request data for building the encrypted session establishment bytes. the device engagement bytes are provided automatically inside the ongetmdocrequestdata() function by the rp client sdk. private val securerepository = securerepository() override fun ongetmdocrequestdata(deviceengagementbytes: bytearray): bytearray? { val keypair = securerepository.generateeckeypair() val encryptedsessionestablishmentbytes = securerepository.buildsessionestablishment(requestdata, deviceengagementbytes, keypair) return encryptedsessionestablishmentbytes!! } for further information regarding generating the key pair and building the session establishment bytes, check the provided sample code. step 2: initiate a verification request with the applink once the ongetmdocrequestdata() function is ready, we can use the request() function to initiate the verification request. val sessionid = uuid.randomuuid().tostring() val wallet_package = "com.samsung.android.spay" rpclientapis.request( wallet_package, sessionid, applink, onresponselistener(requestdata) ) processing the request response once the mdoc request has been sent and processed successfully, the application should receive a bytearray as response in the onmdocresponse() function inside the listener class. this bytearray is an encrypted json object. once decrypted, the response should look like the following: { "documents": [ { "issuersigned": { "namespaces": { "org.iso.18013.5.1": [ "pghkawdlc3rjrbku-mzyyw5kb21uagnkngduzdl5z2i1ctrjadv4znpxzwxlbwvudelkzw50awzpzxjrzxhwaxj5x2rhdgvszwxlbwvudfzhbhvlwhqymdmxltexltixvda3ojawojawwg", "pghkawdlc3rjrbknbwzyyw5kb21udjg1nmsydzizzzq3ohk5ctq0ahjxzwxlbwvudelkzw50awzpzxjsywdlx2lux3llyxjzbgvszw1lbnrwywx1zrgr", "pghkawdlc3rjrblvwwzyyw5kb21ubnrtdnj5oxlucxcyzjy2bmp2nxrxzwxlbwvudelkzw50awzpzxjqaxnzdwvfzgf0zwxlbgvtzw50vmfsdwxaddiwmjmtmtetmdhumdc6mda6mdba", "pghkawdlc3rjrbnxqwzyyw5kb21uoxjqd2nydjz6cxpqzm1xajnkcnhxzwxlbwvudelkzw50awzpzxjrzmftawx5x25hbwvszwxlbwvudfzhbhvlzufoc2fu" ] }, "issuerauth": [ "dcba", { "33": "..." }, "...", "..." ] }, "devicesigned": {…}, "doctype": "org.iso.18013.5.1.mdl" } ], "version": "1.0", "status": 0 } the values inside the org.iso.18013.5.1 json array are the information we requested, in the cbor (concise binary object representation) format. for example, if we decode the value: "pghkawdlc3rjrblvwwzyyw5kb21ubnrtdnj5oxlucxcyzjy2bmp2nxrxzwxlbwvudelkzw50awzpzxjqaxnzdwvfzgf0zwxlbgvtzw50vmfsdwxaddiwmjmtmtetmdhumdc6mda6mdba", we find that this cbor object contains the issue_date field and its value is 2023-11-08t07:00:00.000z. similarly, every value provided in the array is a cbor object that can be decoded using cbor decoders to find a key-value pair containing the requested information. we can now receive the mdoc response in the onmdocresponse() function and decode it to retrieve the final requested values: override fun onmdocresponse(encryptedresponsebytes: bytearray) { val plainresponse = securerepository.decryptmdocresponse(encryptedresponsebytes) log.i(tag, "plainresponse=${plainresponse?.toprettyjson()}") val mdoccontent = mdoc18013utils.parsemdocresponse(plainresponse!!) mdoccontent.foreach { (key, value) -> log.i(tag, "$key: $value") } } here, securerepository.decryptmdocresponse() performs the decryption operation and converts the encrypted bytes into a plain json response. afterwards, the mdoc18013utils.parsemdocresponse() function takes the plain response and decodes each cbor-encoded element contained in the org.iso.18013.5.1 array and returns these values in a simplified dictionary of key-value pairs. if you wish to learn more about these functions, you can check out the provided sample code. with this step, the sample application's implementation of verify with wallet is complete. you can now build and run the application. in the sample application, once the user clicks the "verify with samsung wallet" button, the vww procedure is initiated. once the user confirms that they wish to share their information, the application will receive the requested information about the user. figure 2: complete the verification process using vww conclusion in this article, we have explored how you can integrate the verify with wallet rp sdk directly into your application and use it to verify the user's identity. feel free to integrate the rp sdk in your own application and test the verify with samsung wallet process as well. if you have any further queries regarding this process, feel free to reach out to us through the samsung developers forum. related resources iso/iec 18013-5:2021 - personal identification — iso-compliant driving licence — part 5: mobile driving licence (mdl) application mobile driver license - american association of motor vehicle administrators - aamva rp sdk download link verify with wallet api guidelines relying party card specifications sample code download link
Mobassir Ahsan
Develop Samsung Pay
doc3 5 app-to-app identity verification 3 5 1 overview in mobile payment push provisioning, identity & verification id&v ensures that only the rightful cardholder can add their payment card to samsung wallet samsung wallet supports multiple id&v methods to prevent unauthorized access and fraud, including – sms, email, phone call, access code, bank website, app, or support, and app-to-app id&v app-to-app id&v allows users to verify their identity through their bank's mobile application during push provisioning samsung wallet supports following integration path using android intents does not require sdk – this guide focuses on this method note american express does not support app-to-app id&v 3 5 2 user experience the following figure illustrates the ui flow for app-to-app id&v when the user wants to add a payment card to samsung wallet and selects the “open banking app” option 3 5 3 implementing app-to-app id&v this method allows samsung wallet to launch a bank’s mobile app, where the user’s identity is verified before provisioning their payment card 3 5 4 key concepts term description id&v identity & verification – confirms the cardholder’s identity before provisioning a card tsp token service provider – handles tokenization and supplies id&v methods samsung tr samsung token requestor – communicates with the tsp on behalf of samsung wallet app-to-app id&v launches the bank’s app from samsung wallet to complete identity verification 3 5 5 app-to-app id&v process flow to verify their payment card in the samsung wallet application, the user must accept the terms and conditions, after which samsung wallet initiates token provision through the samsung token requestor tr from the trust service provider tsp the tsp provides samsung wallet with the available id&v methods and the data needed to perform user verification through your application when the user selects “open banking app” in samsung wallet, an android activity launches your application through an intent the intent contains information from the tsp server you can implement app-to-app id&v support in your banking application in 2 ways token activation through bank server - after user verification, the token is activated through your bank’s backend and tsp apis token activation through samsung wallet application - after user verification, your bank server returns an authorization code to samsung wallet, which is used to activate the token the samsung tr and tsp the following figure shows the app-to-app id&v process flow launch the application to launch your application, the samsung wallet application calls the startactivityforresult method, providing the following intent data from the tsp server package name of your application intent action, whose specific name depends on the tsp additional data in the intent extra_text key, depending on the card type mastercard a base64-encoded json object with the following elements paymentappproviderid, paymentappinstanceid, tokenuniquereference, accountpansuffix, and accountexpiry visa an encrypted json payload including pan id, tr id, token reference id, last 4 digits of pan, device id, and wallet account id intent data is generated with the getapp2appintent method in the samsung wallet application public intent getapp2appintent { intent app2appintent = new intent ; app2appintent setpackage packagename ; app2appintent setaction action ; if !textutils isempty extratext { app2appintent putextra intent extra_text, extratext ; } return intent; } note for information about the data in the intent extra_text key, refer to the card network’s own specifications the samsung wallet application only transfers the data to your application for handling process the id&v request to enable your application to handle the intent data transmitted from the samsung wallet application, in your “androidmanifest xml” file, define an activity with the intent action used by the tsp <activity android name="app2appidnvactivity"> <intent-filter> <action android name="com bank mobileapp action launch_a2a_idv"/> <category android name="android intent category default"/> </intent-filter> </activity> when your application is called by samsung wallet, start the activity to process the id&v request the data passed by the intent can be processed through your backend server along with other data that the application already has, such as user and account information if user verification is successful, you can activate the token by calling the tsp api return to samsung wallet after the user has completed verification, your application must direct the user back to samsung wallet using the activity setresult resultcode, resultintent method if the value of resultcode is result_ok, the resultintent object must contain extra bundle data the step_up_response key must have one of the following values depending on the scenario intent result = new intent ; // authentication successful result putextra "step_up_response", "accepted" ; // authentication failed; do not add the user’s card result putextra "step_up_response", "declined" ; // authentication failed; allow user to retry or select another id&v method result putextra "step_up_response", "failure" ; // authentication failed because the application was not ready result putextra "step_up_response", "appnotready" ; activity setresult result_ok, result ; to use an authentication code to activate the token in samsung wallet, you must also include the activation_code key-value intent result = new intent ; result putextra "step_up_response", "accepted" ; result putextra "activation_code", authcode ; activity setresult result_ok, result ; otherwise, the value of resultcode is result_cancel, when the user has canceled the operation intent result = new intent ; activity setresult result_cancel ; 3 5 6 samsung ui wallet flow the samsung wallet ui flow for push provisioning using app-to-app identity verification id&v refers to the sequence of user interface steps a user experience when adding a payment card and verifying their identity via their bank’s mobile app
tutorials mobile
blogas businesses strive to enhance their mobile payment capabilities and provide seamless transaction experiences to users, integrating third-party payment solutions like samsung pay has become increasingly common. however, amid the excitement of implementing these solutions, developers often encounter challenges and pitfalls that can hinder the integration process and impact the overall user experience. in this blog, we show some of the most common mistakes developers make when integrating the samsung pay sdk, and offer practical insights and best practices to overcome these hurdles and ensure successful implementation and testing. pitfall 1: using an unofficial email id to implement the samsung pay sdk, the first step is to establish a partnership between your company and samsung. when submitting a partnership request, do so using your company's official email domain. this precaution is crucial, as partnership requests originating from non-official email addresses are prone to rejection by the samsung relationship manager. pitfall 2: providing the wrong issuer name while creating your service while creating a service for the push provisioning feature, you have to add the issuer names, meaning the names of your financial institution or bank. you must make sure to provide the correct names that have been registered with the card networks such as visa, mastercard and so on. if incorrect names are provided, the getallcard() api returns an empty list even though the card has already been added to the samsung wallet. to confirm your issuer name, first add your card to the samsung wallet application. tap on the card in the wallet application, open the more menu, and select customer services. the correct issuer name is listed on the “customer services” pane. to correct your issuer name for services that you have created: select my projects > service management. select the service name to open the service details page. select edit info. you can delete the incorrect issuer name and enter a new one. pitfall 3: using service id with an invalid effective date a common error that occurs during sdk integration is the error_expired_or_invalid_debug_key (-310) error. this error occurs in two cases: using a newly created service id without generating an expiration date of the service: after creating a service, if you check the edit info of the service details page, you will find that the debug effective data is blank. hence, you have to generate a date right after creating the service. using a service id with an expired debugging date: the service id provided by samsung pay portal remains valid for 90 days. after that time, the service expires. therefore, you must generate a date for debugging every 90 days. to generate or extend the validity date of the service: select my projects > service management. select the service name to open the service details page. select edit info. click generate new date. provide a samsung account for testing the application. this account is placed on the allow list for testing. click generate. the new expiration date of your service appears on the page. remember to extend the date after 90 days if you continue testing your application past that point. pitfall 4: configuring the release service with insufficient information it is essential to include the apk file when setting up the release service. failure to include the apk file will result in samsung pay’s relationship manager rejecting the service, leading to delays in the release process. additionally, ensure that you have correctly integrated the appropriate service id into your release application. pitfall 5: testing your application with a mismatched configuration samsung wallet uses the service id, package name, and apk signature for partner verification. if you test your application with an apk signature different from the one already registered in the samsung pay portal, samsung pay recognizes that the apk signature is inconsistent with the service id and produces the error code -6 (not_allowed). in conclusion, navigating the integration of the samsung pay sdk can present you with many challenges. but, armed with the knowledge shared here, you can steer clear of some potential pitfalls and ensure a smoother implementation process. by prioritizing thorough testing, adhering to best practices, and maintaining clear communication with samsung's support channels, you can mitigate risks and deliver a seamless payment experience to users.
Ummey Habiba Bristy
Develop Samsung Pay
docfaqs and troubleshooting if the samsung pay app throws error_not_allowed -6 error_unable_to_verify_caller -359 , what needs to be checked on the partner app side? for debug verify that the serviceid is correct; make sure it was generated for the test mode and not for release verify that the servicetype is correct; make sure it is same as the value assigned by the samsung pay developers portal when you create the service verify that the device’s samsung account is registered allowed under test accounts in the service details for release verify that the serviceid is correct; make sure it was generated for release and not for the test mode verify that the servicetype is correct; make sure it is same as the value assigned by the samsung pay developers portal when you create the service ask your samsung pay relationship manager rm to confirm that the status of your service is approved i received an onsuccess callback for a `getallcards ` response but the card list is empty even though there already one or more installed cards in samsungpay one of the most common exceptions during development is that “getallcard ” returns an empty list even though the card has already been added to the samsung wallet the main reason for this exception is the mismatch of an issuer name with the samsung pay portal the issuer name on the samsung pay portal and the actual issuer name of the card must be the same to overcome this problem if you cannot confirm the actual issuer name of the card, just add the card to samsung wallet app and see its details information open wallet app > tap on the card > three-dot menu > customer service option > under the title you will find the issuer name the following screenshot would be helpful for better understanding, i have received an onfail callback for `getsamsungpaystatus ` with a `spay_not_supported` status code if your app’s target api level is set to 30 or higher, refer to setting up your sdk development environment part and follow guide for android r os targetsdkversion 30 i am getting 500 error when registering a csr while creating the 'web payment' service what should i do? if your csr was signed using your own private key rather than signed by a payment gateway, please select payment gateway with 'none default ' note the default pg name is 'none default ' i am getting error_partner_app_signature_mismatch error this error occurs due to the following reasons the package name configured in the samsung pay portal is not the same as the application the signature of the apk that has been uploaded to the samsung pay portal and the testing apk is not same check the app’s package name from samsung pay portal > my projects > app management > click on a specific app name i am getting error_not_registered_user_for_debugging error this error occurs if the samsung account has not been added to samsung pay portal while the service status is debugging log into the samsung pay portal first then go to my projects> service management > click on your service name > add test accounts in the service details page i am getting error_inadequate_data_from_db error this error occurs due to the following reasons payment gateway pg csr is required for merchant who is integrating with pg if this csr is missing, merchant app will face this error you should ask your pg to provide pg csr and upload it into the samsung pay portal log into the samsung pay portal first then go to my projects> service management > click on your service name to upload your csr this error occurs when the apk uploaded to samsung pay portal has invalid information please double check with below limitations app package name 50 byte app version 20 length app signature 100 length i am getting error_not_supported_country_code error this error happens if selected countries in samsung pay portal doesn't match with partner's device country or device iso please add the device country on service detail by following the steps below go to samsung pay portal > login using the manager account > my projects > service management > click on a specific service > click on edit info > add country under service location i am getting error_service_not_exist error no service is found under the provided id, service has been deleted or an invalid service id please check the service id or create a new service to use it for your further testing to check the service id, log into the samsung pay portal first then go to my projects> service management > click on your service name to create new service, go through the partner on boarding guide i am getting error_not_approved_service error the error arises when the service is not in the "debugging" state for test environments or "approved" or "verifying" for release environments please contact your rm to change the status of your service i am getting spay_not_approved_service error the error code spay_not_supported typically indicates that the device either lacks compatibility to run samsung pay or the samsung pay app is not installed make sure the wallet app you're using is a valid one or you could reach our support for help i am getting error_spay_app_need_to_update error this error signifies that the samsung wallet app requires an update in such cases, the partner app should prompt the user to update samsung wallet app if the user agrees, the app should invoke the samsungpay gotoupdatepage api to guide the user to the update page for samsung wallet app i am getting error_partner_sdk_version_not_allowed error this error indicates that the partner app is utilizing a samsung pay sdk that is not permitted using a valid samsung pay sdk version should solve this issue we recommend using the latest version of the sdk please check the latest version from here i am getting error_sdk_not_supported_for_this_region error this error indicates that the samsung pay sdk is not supported in particular region for example, if the device is from the country that samsung pay sdk is not supported, then the partner app verification will be failed please contact with your rm to know supported region for specific version of the samsung pay sdk i am getting error_not_allowed error this error indicates that requested operation is not allowed for example, partner app verification has failed in samsung pay server please create support ticket in developer support channel by attaching the dumpstate log i am getting error_invalid_payload error this error occurs if the samsung wallet service is not enabled by the card issuer please contact your card issuer to enable the digital wallet service for your card i am getting error_card_not_supported error this error indicates that the requested operation is already done and this operation cannot be performed again at first, delete the card from samsung wallet app and then try push provisioning again i am getting error_invalid_parameter error the error caused by wrongly created payload issuer need to create payload correctly based on card network's specification i am getting error_card_already_registered error this error indicates that the requested operation is already done and this operation cannot be performed again at first, delete the card from samsung wallet app and then try push provisioning again i am getting unknown_error_code error you can create a ticket via samsung developer portal > support > dev support with the following information for technical support regarding this samsung pay sdk implementation error description or comment to explain what kinds of issue you are having as possible as detail for example what is the issue? which apis used for your test scenario? what is expected response from the api and what is actual response? dumpstate log to take dumpstate log please follow the steps from here how to get samsung wallet test app? please follow the steps below to get the samsung wallet test app login into pay samsung com/developer using your samsung account go to support> request test app copy the galaxy app url then click on my projects > service management select specific service register your test samsung account in test account field
Learn Code Lab
codelabintegrate samsung pay web checkout with merchant sites objective learn how to integrate the samsung pay payment system into your merchant sites using the samsung pay web checkout sdk partnership request to use the samsung pay web checkout sdk, you must become an official samsung pay partner once done, you can fully utilize this code lab you can learn more about the partnership process by visiting the samsung pay page here in samsung developers notein accordance with the applicable samsung pay partners agreements, this code lab covers the setup and use of the samsung pay web checkout sdk for purposes of integrating samsung pay with merchant sites the use cases and corresponding code samples included are representative examples only and should not be considered as either recommended or required overview the samsung pay web checkout service enables users to pay for purchases on your website with payment cards saved in the samsung wallet app on their mobile device it supports browser-based payments on both computers and mobile devices a mobile device with samsung wallet installed is required to make purchases through samsung pay web checkout when the user chooses to pay with samsung pay, they must provide their samsung account id email id or scan the qr code on the screen with their mobile device the user then authorizes the purchase within the samsung wallet application, which generates the payment credential on the device and transmits it to your website through the web checkout for more information, see samsung pay web checkout set up your environment you will need the following access to samsung pay developers site samsung wallet test app from samsung pay developers site samsung galaxy device that supports samsung wallet app internet browser, such as google chrome codesandbox account notein this code lab, you can use the samsung wallet test app to try the functionality of the samsung pay web checkout service in a staging environment you can use the official samsung wallet app from the galaxy store once your service is in the production environment start your project and register your service in your browser, open the link below to access the project file of the sample merchant site codesandbox io/s/virtual-store-sample-fnydk5 click the fork button to create an editable copy of the project next, follow the steps below to register your sample merchant site in the samsung pay developers site go to my projects > service management click create new service select web online payment as your service type enter your service name and select your service country select your payment gateway from the list of supported payment gateways pg if your pg uses the network token mode, upload the certificate signing request csr or privacy enhanced mail pem file you obtained from your pg contact your pg for details 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 will need to enter payments mywebstore com as the service domain for each additional domain url, click add in this code lab, the generated preview url of the forked project is your service domain click the name of the newly created service to see its details, such as the generated service id that you can use for all the registered service domains include the samsung pay web checkout javascript sdk the samsung pay web checkout sdk uses javascript to integrate the samsung pay payment system to your website this sdk allows users to purchase items via web browser in the <head> section of the index html file of the project, include the samsung pay web checkout javascript sdk file <script src="https //img mpay samsung com/gsmpi/sdk/samsungpay_web_sdk js"></script> initialize the samsung pay client to initiate payments using the samsung pay api, create a new instance of the paymentclient class and pass an argument specifying that the environment as stage write the code below in the <script> tag of the <body> section const samsungpayclient = new samsungpay paymentclient { environment "stage" } ; when the service is still in debug or test mode, you can only use the staging environment to test payment functionality without processing live transactions noteby default, the service is initially set to debug or test mode during creation to switch the service status to release mode, a request must be made through the samsung pay developers site after successfully transitioning to release mode, change the environment to production next, define the service id, security protocol, and card brands that the merchant can support as payment methods the service id is the unique id assigned to your service upon creation in the samsung pay developers site let paymentmethods = { version "2", serviceid "", //input your service id here protocol "protocol_3ds", allowedbrands ["visa", "mastercard"] }; check whether the samsung pay client is ready to pay using the given payment method call the createandaddbutton function if the response indicates that the client is ready samsungpayclient isreadytopay paymentmethods then function response { if response result { createandaddbutton ; } } catch function err { console error err ; } ; create and implement the samsung pay button go to the <body> section and, inside the page-container div, create a container for the samsung pay button <div align="center" id="samsungpay-container"></div> next, go back to the <script> tag and write the createandaddbutton function inside this function, generate the samsung pay button by calling the createbutton method ensure that the button appears on the page by appending it to the container you created function createandaddbutton { const samsungpaybutton = samsungpayclient createbutton { onclick onsamsungpaybuttonclicked, buttonstyle "black"} ; document getelementbyid "samsungpay-container" appendchild samsungpaybutton ; } function onsamsungpaybuttonclicked { // create the transaction information //launch the payment sheet } from the createandaddbutton function, call the onsamsungpaybuttonclicked function when the user clicks the generated button create the transaction information in the onsamsungpaybuttonclicked function, create the transactiondetail object for the user’s purchase input your service domain in the url key let transactiondetail = { ordernumber "sample0n1y123", merchant { name "virtual shop", url "", //input your service domain countrycode "us" }, amount { option "format_total_estimated_amount", currency "usd", total 2019 99 } }; below are the descriptions of the keys included in the transactiondetail object key type description ordernumber string order number of the transaction allowed characters [a-z][a-z][0-9,-] merchant object data structure containing the merchant information merchant name string merchant name merchant url string merchant domain url e g , samsung com the maximum length is 100 characters merchant countrycode string merchant country code e g , us for united states iso-3166-1 alpha-2 amount object data structure containing the payment amount amount option string display format for the total amount on the payment sheet format_total_estimated_amount = displays "total estimated amount " with the total amountformat_total_price_only = displays the total amount only amount currency string currency code e g , usd for us dollar the maximum length is 3 character amount total string total payment amount in the currency specified by amount currencythe amount must be an integer e g , 300 or in a format valid for the currency, such as 2 decimal places after a separator e g , 300 50 notefor the complete list of specifications for the transactiondetail object, see samsung pay web checkout api reference launch the payment sheet after creating the transaction information, call the loadpaymentsheet method to display the web checkout ui the user can either input their email address or scan the generated qr code a timer screen in the web checkout ui is displayed after the user input, while a payment sheet is launched in the user's samsung wallet app the payment sheet contains the payment card option s and the transaction details when the user confirms their payment on their mobile device, you will receive the paymentcredential object generated by the device then, inform the samsung server of the payment result using the notify method the paymentresult object contains the payment result information during transaction processing and after the payment is processed with the pg network notefor real transactions, you need to extract the payment credential information from the 3ds data key within the paymentcredential object and process it through your payment provider however, in this code lab, you only need to print the paymentcredential to the console samsungpayclient loadpaymentsheet paymentmethods, transactiondetail then function paymentcredential { console log "paymentcredential ", paymentcredential ; const paymentresult = { status "charged", provider "test pg" }; samsungpayclient notify paymentresult ; } catch function error { console log "error ", error ; } ; other possible values of the status key are charged - payment was charged successfully canceled - payment was canceled by either the user, merchant, or the acquiring bank rejected - payment was rejected by the acquiring bank erred - an error occurred during the payment process test the samsung pay button after integrating the samsung pay web checkout service into your sample merchant site, follow the steps below to test the functionality of the integrated service open your sample merchant site in a new tab then, click the pay with samsung pay button in the web checkout ui, enter the email address of your samsung account to send a payment request to samsung pay tap the push notification sent to the samsung wallet app installed on your mobile device then, click accept when the payment sheet is loaded, tap on pin and enter your pin to proceed a verified message will display in both the samsung wallet app and web checkout ui to indicate that the payment was processed successfully you're done! congratulations! you have successfully achieved the goal of this code lab topic now, you can integrate the samsung pay web checkout service into your website by yourself if you're having trouble, you may check the complete code below codesandbox io/s/virtual-store-complete-dkhzfx to learn more about developing apps for samsung pay devices, visit developer samsung com/pay
Develop Samsung Wallet
docapi guidelines adding wallet card specs when integrating with samsung wallet, the add to wallet functionality allows users to securely add cards such as loyalty cards, payment cards, or tickets to their samsung wallet app to ensure a smooth and successful integration, partners need to follow specific api guidelines for adding card specs here is an overview of the steps and key components you need to consider when integrating the api for adding wallet cards data transmit link the data transmit link is the api endpoint through which partners send the initial card data e g , card number, expiration date, issuer information, barcode, etc to samsung wallet the most common and straightforward method is the data transmit link approach, which securely includes tokenized data in the atw link the atw link format for this method is as follows note-the name data transmit link has been changed from typical flow type value description url https //a swallet link/atw/v3/{cardid}#clip?cdata={cdata} path parameters cardid string required wallet card identifier issued from partner portal when the partner manager signs up for partner services and registers the wallet card they want to service hash path parameters #clip string required parameters for the hash link * the first letter is capitalized query parameters cdata string required actual payload data in basic json format to communicate between partners and samsung wallet this must be secured in jwt json web token format * see security [example] https //a swallet link/atw/v3/1656147182764415319#clip?cdata=eyjjdhkioijkv1qilcjhbgcioijsinrpbwvzdgftcci6imnyzwf0zwqgdgltzsisinbhcnruzxjjrci6inbhcnruzxigsuqifq … … … … dn0_oz3xcr0juq3mlszliutxfotewnz0mqj7kinjysnm5xfwqt5vcn20peebelgux8vjxly4_9g4bhq-hd4o9poyutuawew yzdlmtfho -nycel3t0yznzad2kck_hrtwigeerhlgn6ydaq_fpfdslxsa3zjtnpg3wcuqew5cidpbpfswbqlropqepnawg5nlm3dkaa4a1dzazmbsr1bgzhrh_viknx3cy5mo0jnbexl_yiz5_wb379uyswumqipitzvg2ijyvfht17i4 data fetch link the data fetch link allows partners to retrieve card details after the card has been added to the samsung wallet in cases involving sensitive data or when providing static links, data fetch link method is highly recommended links using this approach include only a unique reference id, and wallet cards are added by querying data through get card data path as specified in partner portal note- the name data fetch link has been changed from slim data flow please be aware that if the link is exposed to unintended users, it can be exploited please prepare the integration with this in mind it is crucial to ensure that the refid, used for a reference value, is generated in a manner that is not easily deducible by potential attackers type value description url https //a swallet link/atw/v3/{certificateid}/{cardid}#clip?pdata={pdata} path parameters certificateidstring 4 conditional ertificate identifier based on a csr during onboarding 4 digits alphanumeric * must be generated from partner portal cardidstring 32 required wallet card identifier * it must be generated from partners portal hash path parameters #clipstring 5 required parameters for the hash link query parameter pdatastring 2048 required unique id defined by content providers this has identification for each user's wallet card contents * for secure transactions, a reference id refid must be in a form that cannot be inferred example - https //a swallet link/atw/v3/ymtt/1656147182764415319#clip?pdata=sighcziwm9g updating wallet card specs when users add cards to samsung wallet, their data can be updated through server interactions to manage these updates, partners need to configure their api settings via the partner portal follow the steps below to manage and update the cards added to samsung wallet samsung server will notify the result of 'add to wallet' via send card state partners get the callback url for samsung server api from send card state payload using the callback url, partners can make actions for the added cards via samsung server api depending on the interfaces, samsung server triggers specific operations for example, when update notification is called, samsung server calls partners' server to look up the updated contents ![] https //d3 unf4s5rp9dfh cloudfront net/samsungwallet_doc/updating-wallet-card-specs png partner server api samsung server can call the following api by using endpoint on the registered card information if the partner server manages an inbound allow list, contact us to register samsung server ip address get card data the get card data allows partners to retrieve the most up-to-date information about a card that has already been added to samsung wallet this api is crucial for ensuring that the partner’s system has accurate and current details about a user's card, whether for display, transaction validation, or other purposes [request] type value description method get url {partner server url}/cards/{cardid}/{refid}?fields={fields} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * refer to the 'add to wallet' interfaces refid string 32 required a unique content identifier defined by the content provider query parameter fields string 128 optional attributes which intended to retrieve can be specified using commas , as separators e g balance,barcode value payload n/a example get /cards/12584806754/ref-20230304-0003 [response] type value description http status 200 ok 204 no content payload option1 cdata string 4096 conditional card object json * this field needs to be encrypted * see security payload option2 card object conditional card information * card object as an alternative to cdata * if cards includes sensitive data, it is highly recommended using cdata card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] createdat long 13 required timestamp of data epoch timestamp in milliseconds data[] updatedat long 13 required timestamp of data epoch timestamp in milliseconds data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, canceled, pending, suspended * see card states for details data[] language string 8 required default content language code e g , en, ko data[] attributes object required card data attributes data[] attributes {fields} attribute fields by card type *see wallet cards data[] localization[] array of object optional information for multilingual support localization[] language string 8 required multilingual content language code e g , en, ko localization[] attributes {fields} for displaying a given language, "data[] attributes" can be replaced by localized versions *see wallet cards [example option1 ] { "cdata" "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 eyjzdwiioiixmjm0nty3odkwiiwibmftzsi6ikpvag4grg9liiwiawf0ijoxnte2mjm5mdiyfq sflkxwrjsmekkf2qt4fwpmejf36pok6yjv_adqssw5c" } [example option2 ] { "card" { "type" "ticket", "subtype" "movies", "data" [{ "refid" "ref-20230304-0002", "createdat" 1612660039000, "language" "en", "attributes" { "title" "samsung wallet" /* refer to wallet cards */ }, "localization" [{ "language" "ko", "attributes" { "title" "삼성월렛" } }] }] } } [example filtered using select parameter ] get /cards/12584806754/ref-20230304-0003?select=idphoto { "card" { "type" "ticket", "subtype" "entrances", "data" [{ "refid" "ref-20230304-0003", "createdat" 1612660039000, "language" "en", "attributes" { "idphoto" "{idphoto data}" } }] } } or { "cdata" tokenize{data} } [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request send card state the send card state is used to manage the state or history of the card using this api if the card state is changed on the samsung device, samsung calls this api using a refid [request] type value description method post url {partner server url}/cards/{cardid}/{refid} headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-request-id string 32 required request identifier randomly generated uuid string path parameters cardid string 32 required wallet card identifier * refer to the 'add to wallet' interfaces refid string 32 required a unique content identifier defined by the content provider query parameters cc2 string 2 required country code cc2 for samsung server api event string 16 required events on wallet carde g , added, updated, deleted, provisioned* see card states for details payload callback string 1024 optional callback url for samsung server api [example] post /cards/12584806754/ref-20230304-001?cc2=us&event=added { "callback" "https //us-tsapi walletsvc samsung com" } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request samsung server api the samsung server api allows partners to notify their content changes to samsung wallet depending on your service requirements, you can choose from private domain or public domain to send notifications the domain selection depends on your system's needs and security preferences service domain environment domain public domain https //tsapi-card walletsvc samsung com private domain ‘callback’ field from send card state api request payload key components private domain recommended for ip registration - if your service requires registering static ip addresses on your system, we recommend using the private domain when you use the private domain, you will receive a callback url in the send card state api response this url will direct your system to the correct endpoint to send content updates or changes public domain recommended for no ip registration - if your service does not require ip registration or has more flexible network access, you can use the public domain the public domain api endpoint allows easier integration without requiring specific ip addresses to be registered however, it does require a country code cc2 as a path parameter for each request this ensures that content is correctly routed based on the user's region or country to configure the api integration for different environments e g , testing, production , you must first register a new card service with samsung this process will assign you a new card id for use in your api calls the card id is crucial for identifying and tracking the specific card you are interacting with to ensure safe and secure communication, servers should configure token-based authentication for information, refer to the authorization token update notification allows partners to notify samsung wallet when there are changes or updates to the content of a wallet card this ensures that the card information within samsung wallet remains up-to-date and accurate [request] type value description method post url {cc2}/wltex/cards/{cardid}/updates headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> * see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] refid string 32 required a unique content identifier defined by the content provider data[] state string 16 required wallet card state for example, active, updated, expired, redeemed, held, deleted, suspended * see send card state for details data[] fields string 128 optional wallet cards attributes which has been updated can be specified using commas , as separators it is used when 'data[] state' is updated e g balance,barcode value* supported wallet card types generic [example] post /wltex/cards/12584806754/notification [headers] authorization eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] case 1 in general cases { "card" { "type" "ticket", "data" [ { "refid" "ref-ticket-0001", "state" "updated" } ] } } case 2 in case of deletion { "card" { "type" "boardingpass", "data" [ { "refid" "ref-boardingpass-0001", "state" "deleted" } ] } } case 3 when a specific field is updated { "card" { "type" "idcard", "data" [ { "refid" "ref-idcard-0001", "state" "updated", "fields" "balance" } ] } } [response] type value description http status 200 ok204 no content payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request cancel notification allows partners to inform samsung wallet when a card such as for performances, sports, movies, or journeys needs to be cancelled when a cancellation occurs, this api enables partners to set the related card s to an expired status this ensures that users no longer have valid access to events or services that have been cancelled, such as a concert, flight, or movie screening [request] type value description method post url {cc2}/wltex/cards/{cardid}/cancels headers authorization string 1024 required credential token the token can have prefix "bearer" as an authorization type, e g , bearer <credentials> *see authorization token x-smcs-partner-id string 32 required partner id x-request-id string 32 required request identifier randomly generated uuid string path parameters cc2 string 2 conditional country code cc2 from send card state * required if using public domain cardid string 32 required wallet card identifier granted from the partners portal payload card object required wallet card object card type string 16 required wallet card type * see wallet cards card data[] array of object required wallet card data container data[] eventid string 32 conditional required if card type has been set as ‘ticket’ data[] vehicle number string 32 conditional required if "card type" has been set as "boardingpass" data[] estimated oractualstartdate long 13 data[] state string 16 required wallet card state e g , canceled* see card states for details [example] post /wltex/cards/12584806754/notification [headers] authorization eyjjdhkioijuvrlliwidmvyijoxlcjwyxj0bmvyswqioiixmjg1o x-smcs-partner-id partner-id-0001 x-request-id req-202303140003 [payload] * a movie ticket has been canceled { "card" { "type" "ticket", "data" [ { "refid" "event-722164a1a7", "state" "canceled" } ] } } [response] type value description http status 200 ok payload n/a example 200 ok [result] http status code description 200 ok success 204 no content card doesn’t exist 400 bad request requests cannot or will not be processed the request due to something that is perceived to be a client error 401 unauthorized authorization token is invalid or expired 500 internal server error server encountered an unexpected condition that prevented it from fulfilling the request 503 service unavailable server is not ready to handle the request
Develop Samsung Wallet
webdesign guideline for samsung wallet & pay samsung wallet is a mobile wallet service that allows people to access their virtual wallet from anywhere with a simple swipe up, providing them with a convenient and innovative lifestyle. samsung wallet samsung wallet samsung pay samsung pay stickers samsung wallet samsung pay samsung pay stickers assets for samsung wallet we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. logo asset logo toolkit logo buttons partnership logo use the service logo lock-up for advertisements, marketing materials and webpages that are promoting samsung pay. you must not lock up an icon with the lettermark. type basic - horizontal basic - vertical alternate - horizontal alternate - vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not violate the spacing rules do not lock up in any other way. do not change the typeface. do not change the lock-up color. do not distort or change the shape. do not lock up basic logo with the icon. do not add drop shadows. do not outline. do not place the logo on busy backgrounds with insufficient contrast. buttons the samsung wallet buttons are for adding or registering tickets and travel passes to the app. type in-app & online - horizontal in-app & online - vertical cta - horizontal cta - vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not use a white button on white backgrounds or with a black stroke. do not use a black button on black backgrounds or with a white stroke. do not change the color of the button. do not alter the height ratio of the button. do not add drop shadows or other effects. do not abbreviate. do not change the typeface of the button. do not use the samsung wallet app icon as a button. do not use lower case for text-only buttons. usage example partnership for partnerships, the horizontal logo lock-up is the preferred choice.※ before using a partnership logo, please confirm with your local samsung partnership representative to ensure the appropriate format. type horizontal vertical lock-up format a horizontal partnership lock-up fromat a horizontal partnership lock-up fromat a vertical partnership lock-up fromat do nots do not create a lock-up with the icon. do not use any alignment other than centered. do not use a lock-up format that is not visually balanced. do not scale the partner logo larger than our logo. do not alter the length of the divider bar. do not use other graphic elements as a divider. do not remove the lettermark. do not alter the line weight of the divider bar. do not change the color of the logo. usage example ooh horizontal lock-up ooh horizontal lock-up common usage vertical lock-up common usage horizontal lock-up assets for samsung pay we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. logo asset logo toolkit logo buttons logo use the service logo lock-up for advertisements, marketing materials and webpages that are promoting samsung pay. you must not lock up an icon with the lettermark. type horizontal vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not violate the spacing rules do not lock up in any other way. do not change the typeface. do not change the lock-up color. do not distort or change the shape. do not lock up basic logo with the icon. do not add drop shadows. do not outline. do not place the logo on busy backgrounds with insufficient contrast. buttons the samsung wallet buttons are for adding or registering tickets and travel passes to the app. type in-app & online cta partner ratio a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. do nots do not use a white button on white backgrounds or with a black stroke. do not use a black button on black backgrounds or with a white stroke. do not change the color of the button. do not alter the height ratio of the button. do not add drop shadows or other effects. do not abbreviate. do not change the typeface of the button. do not use the samsung wallet app icon as a button. do not use lower case for text-only buttons. samsung pay stickers we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. download logo signage we accept decal assets staying true to samsung brand guidelines, we’ll utilize samsung blue in rounded rectangle format for a distinctive look from other brands. for general retail stores horizontal vertical usage example entry decals a horizontal type decal on the entrance entry decals a vertical type decal on the entrance register decals a vertical type decal on the register checkout kiosk for ses / partnership sotres horizontal vertical usage example open/closed an open signage on the entrance open/closed an closed signage on the entrance push/pull a vertical push signage on the entrance push/pull a vertical pull signage on the entrance push/pull a horizontal push signage on the entrance push/pull a horizontal pull signage on the entrance we accept decals horizontal vertical usage example
Develop Samsung Pay
webdesign guideline for samsung wallet & pay samsung wallet is a mobile wallet service that allows people to access their virtual wallet from anywhere with a simple swipe up, providing them with a convenient and innovative lifestyle. samsung wallet samsung wallet samsung pay samsung pay stickers samsung wallet samsung pay samsung pay stickers assets for samsung wallet we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. logo asset logo toolkit logo buttons partnership logo use the service logo lock-up for advertisements, marketing materials and webpages that are promoting samsung pay. you must not lock up an icon with the lettermark. type basic - horizontal basic - vertical alternate - horizontal alternate - vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not violate the spacing rules do not lock up in any other way. do not change the typeface. do not change the lock-up color. do not distort or change the shape. do not lock up basic logo with the icon. do not add drop shadows. do not outline. do not place the logo on busy backgrounds with insufficient contrast. buttons the samsung wallet buttons are for adding or registering tickets and travel passes to the app. type in-app & online - horizontal in-app & online - vertical cta - horizontal cta - vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not use a white button on white backgrounds or with a black stroke. do not use a black button on black backgrounds or with a white stroke. do not change the color of the button. do not alter the height ratio of the button. do not add drop shadows or other effects. do not abbreviate. do not change the typeface of the button. do not use the samsung wallet app icon as a button. do not use lower case for text-only buttons. usage example partnership for partnerships, the horizontal logo lock-up is the preferred choice. type horizontal vertical lock-up format a horizontal partnership lock-up fromat a horizontal partnership lock-up fromat a vertical partnership lock-up fromat do nots do not create a lock-up with the icon. do not use any alignment other than centered. do not use a lock-up format that is not visually balanced. do not scale the partner logo larger than our logo. do not alter the length of the divider bar. do not use other graphic elements as a divider. do not remove the lettermark. do not alter the line weight of the divider bar. do not change the color of the logo. usage example ooh horizontal lock-up ooh horizontal lock-up common usage vertical lock-up common usage horizontal lock-up assets for samsung pay we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. logo asset logo toolkit logo buttons logo use the service logo lock-up for advertisements, marketing materials and webpages that are promoting samsung pay. you must not lock up an icon with the lettermark. type horizontal vertical ratio & alignment a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. a vertical logo lock-up may be used in cases where horizontal space is limited or where there is a corner or other element to clearly align with. do nots do not violate the spacing rules do not lock up in any other way. do not change the typeface. do not change the lock-up color. do not distort or change the shape. do not lock up basic logo with the icon. do not add drop shadows. do not outline. do not place the logo on busy backgrounds with insufficient contrast. buttons the samsung wallet buttons are for adding or registering tickets and travel passes to the app. type in-app & online cta partner ratio a horizontal logo lock-up should be used in cases where there is plenty of horizontal space or where vertical space is limited. do nots do not use a white button on white backgrounds or with a black stroke. do not use a black button on black backgrounds or with a white stroke. do not change the color of the button. do not alter the height ratio of the button. do not add drop shadows or other effects. do not abbreviate. do not change the typeface of the button. do not use the samsung wallet app icon as a button. do not use lower case for text-only buttons. samsung pay stickers we encourage you to learn and follow the rules and guidelines suggested in this toolkit to ensure message consistency and drive brand awareness. download logo signage we accept decal assets staying true to samsung brand guidelines, we’ll utilize samsung blue in rounded rectangle format for a distinctive look from other brands. for general retail stores horizontal vertical usage example entry decals a horizontal type decal on the entrance entry decals a vertical type decal on the entrance register decals a vertical type decal on the register checkout kiosk for ses / partnership sotres horizontal vertical usage example open/closed an open signage on the entrance open/closed an closed signage on the entrance push/pull a vertical push signage on the entrance push/pull a vertical pull signage on the entrance push/pull a horizontal push signage on the entrance push/pull a horizontal pull signage on the entrance we accept decals horizontal vertical usage example
Develop Samsung Pay
doc3 1 android sdk 3 1 1 introduction the samsung pay sdk allows android-based partner apps—such as merchant apps and issuer banking apps—to securely integrate features of integration wallet, enabling in-app payments, push provisioning, and more the following major operations are supported in-app payment - gives customers the option of paying for products and services with samsung wallet push provisioning - allows customers add a bank card to samsung wallet from the issuer app by providing the required card details to integrate your partner application with the samsung pay sdk, the following components are included your sdk download samsungpay jar - contains classes and interfaces of the samsung pay sdk which need to be integrated to partner apps javadoc - provides descriptions of the apis included in the samsung pay sdk, along with sample code showing how to use them sample merchant app and sample issuer app showing how samsung pay apis can be coded in a finished android project all major operations of samsung pay sdk are implemented for demonstration purposes 3 1 2 samsung pay sdk architecture the following diagram shows a high-level architecture revealing the general interactions between the samsung pay sdk and a partner app viewed at this level, the partner apps leverage the samsung pay sdk to perform the operations shown ― push provisioning and opening favorite cards for issuers; online payments for merchants ― with samsung pay the key components involved are partner app - merchant- or issuer-developed app for making online/offline payments and provisioning payment cards through samsung wallet samsung pay sdk - sdk integrated into the partner app for direct communication with samsung wallet samsung wallet app - wallet app that the samsung pay sdk communicates with financial network - comprises the payment gateways, acquirers, card associations, and issuers that participate in transaction processing under agreement with the merchant the main classes comprising the samsung pay sdk include samsungpay – used by the partner app to get the samsung pay sdk information and the status of samsung wallet app on the device paymentmanager – provides payment/transaction functionality cardmanager – manages card list get, add, update functionality watchmanager – manages all functions related to samsung pay watch cardinfolistener – interface for requestcardinfo result from samsung wallet customsheettransactioninfolistener – interface for transaction success/failure callbacks from samsung wallet 3 1 3 uses cases in-app payment the most common in-app online payment use case take the following form merchant app presents user with the option of making payment with samsung wallet upon the user selecting the samsung pay option, the merchant app calls the apis included in the samsung pay sdk to initiate a transaction with samsung wallet app samsung wallet app responds with the tokenized payment information necessary to complete the transaction 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 normal transaction processing app-to-app push provisioning the push provisioning use case ― adding payment cards to samsung wallet from the card issuer’s app ― typically takes this form the user logs into the issuer app the issuer app checks if samsung wallet is activated on the device and ready to use if it is in the ready status, the issuer app displays an add button for cards not currently registered/enrolled with the samsung wallet app if the add card option is selected, the issuer app calls an api to push the proper payload data to samsung wallet while the card is being provisioned, samsung wallet stays in background 3 1 4 setting up sdk development environment the importance of maintaining a good development environment cannot be overstated for integrating the samsung pay sdk with your partner app, the following prerequisites and recommendations help ensure a successful sdk implementation system requirements the samsung pay sdk is designed exclusively for samsung mobile devices supporting samsung pay and running android lollipop 5 1 android api level 22 or later versions of the android os the sdk’s in-app payments functionality requires android 6 0 m android api level 23 or later versions of the android os note as of sdk version 1 5, if the device runs android lollipop 5 1 android api level 22 or an earlier version, the getsamsungpaystatus api method returns a spay_not supported status code merchant apps still using samsung pay sdk 1 4 or earlier not recommended must check the android version running their app use the following snippet to determine the os version running on a device and whether or not to display the samsung pay button in your partner app import android os build; // in-app payment supported on android m or above // check android version of the device if build version sdk_int < build version_codes m { //hide samsung pay button} service registration to develop a samsung pay sdk service, merchants and issuers need to register for an account with samsung pay developers in order to create the appropriate service type for their applications here are some helpful links inside the portal become a member https //pay samsung com/developers/tour/memberguide create services https //pay samsung com/developers/tour/svcguide register apps https //pay samsung com/developers/tour/appsguide manage services and apps https //pay samsung com/developers/tour/svcnappsguide add samsung pay sdk to your project be sure to do the following before attempting to use the sdk if not already part of your environment, download and install an ide android studio is recommended download the samsung pay sdk the sdk package has the following directory structure folder contents docs javadoc – api reference documentation libs samsungpay jar sdk java archive file – contains the samsung pay apis to be used by your partner app samples sample apps configure your ide to integrate the samsung pay sdk with your partner app a add samsungpay jar to the libs folder of your android project b go to gradle scripts > build gradle and enter the following dependency dependencies { compile files 'libs/samsungpay jar' } c import the sdk package into your code import com samsung android sdk samsungpay v2; d proguard rules - if your app s have any issue with proguard, the following rules are recommended to enter in debug mode dontwarn com samsung android sdk samsungpay ** -keep class com samsung android sdk ** { *; } -keep interface com samsung android sdk ** { *; } -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level -keepresourcexmlelements manifest/application/meta-data@name=debug_mode -keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key dontwarn com samsung android sdk samsungpay ** -keep class com samsung android sdk ** { *; } -keep interface com samsung android sdk ** { *; } -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level -keepresourcexmlelements manifest/application/meta-data@name=debug_mode -keepresourcexmlelements manifest/application/meta-data@name=spay_debug_api_key e when dexguard is employed, the following additional rules apply -keepresourcexmlelements manifest/application/meta-data@name=spay_sdk_api_level android r os targetsdkversion 30 informationfrom android r os if the target sdk version is 30 , you must include the following <queries> element in the androidmanifest <?xml version="1 0" encoding="utf-8"?> <manifest xmlns android="http //schemas android com/apk/res/android" xmlns tools="http //schemas android com/tools" package="xxx xxx xxx xxx"> <queries> <package android name="com samsung android spay" /> <package android name="com samsung android samsungpay gear" /> </queries> 3 1 5 configuring api level api level attributes 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 22―but continues to use apis based in level 1 4, the partner app remains compatible with samsung wallet apps supporting api level 1 4 without the necessity of upgrading the samsung pay app the chief characteristics and properties of the api level include every api starting from version 1 4 has an api level assigned based on the sdk version number in which it is introduced the sdk’s javadoc reference can be filtered by api level so you can determine the minimum api level you need to configure in the metadata section of your app’s androidmanifest file the earliest possible version is 1 4 this lets you use the api level defined in your androidmanifest without having to trigger an upgrade of the samsung wallet app on the user’s device implement the following usage in your androidmanifest <application <meta-data android name="spay_sdk_api_level" android value="2 22" /> // most recent sdk version is recommended to leverage the latest apis but it need to be set to 2 17 for russia </application> partner app verification in partner verification process samsung pay sdk verify your registered app, version in samsung pay portal and service it also determines device and app compatibility your app needs to verify the presence of the samsung wallet app on the device, its status, and whether or not its version is sufficient to support your implementation of the sdk 3 1 6 common terminology terminology description aavs automatic add value service aidl android interface definition language for communication merchant a business entity engaged in retail e-commerce that provides an online checkout service for purchasing its products and/or services to registered end users issuer financial institution empowered to issue credit and/or debit payment cards to qualified consumers and businesses payment gateway pg e-commerce app service provider equipped to authorize credit card payments for e-businesses, online retailers, bricks and clicks, or traditional brick and mortar payment token secure method for payment ensuring that a cardholder’s information is not exploited by unauthorized parties samsung pay samsung’s proprietary mobile wallet app and payment system samsung pay service the server and service components of samsung pay samsung pay watch samsung pay app on samsung galaxy watches to support payment system eligibility check a query by third-party apps to check whether or not samsung pay is supported/activated/ready-to-use on a samsung device mst magnetic secure transmission tui trusted user interface 3 1 7 api common flow once setup is complete, you’re ready to add the sdk code within your partner app for calling the sdk’s apis and receiving callbacks when a partner app calls one of the sdk’s apis, the following interaction flow is processed to check whether the caller is authenticated and authorized before responding to the request the steps of the interaction are enumerated below step 1 the partner app calls a samsung pay sdk api the partner app initiates a call to the samsung pay sdk this could be to request in-app payment push provisioning status checks, etc step 2 sdk validates the preconditions the sdk performs initial checks before proceeding is samsung wallet installed on the device? is the integrity of the samsung pay system intact e g , no tampering or missing files ? step 3 sdk initiates communication with samsung wallet if preconditions are met, the sdk uses aidl android interface definition language to securely open a communication channel with the samsung wallet app step 4 samsung wallet app status validation samsung wallet app checks has the samsung pay setup been completed on the device? does the app require a mandatory update? is the samsung pay sdk api level used by the partner app compatible? step 5 partner app eligibility verification sdk triggers a backend verification with the samsung pay server to confirm the app’s package name, service id, and csr match what’s registered on the samsung pay developers portal the app is authorized to use the requested samsung pay functionality step 6 samsung wallet responds to sdk based on the above validations samsung wallet responds via aidl to the sdk it sends status codes, eligibility results, or additional prompts if needed e g , update required step 7 sdk triggers callback in the partner app the sdk invokes a callback function in the partner app this informs the app whether it can proceed with payment/provisioning an error or restriction has occurred step 8 partner app executes business logic based on sdk callback if successful initiate samsung pay payment ui or push provisioning complete transaction or card enrollment via the wallet app if unsuccessful inform the user offer fallback payment options provide guidance on enabling/updating samsung wallet 3 1 8 checking samsung pay status the first step in integrating the samsung pay sdk into your partner app is to create a samsung pay instance and check the status of samsung pay on the user's device this check determines whether the device supports samsung pay and if the samsung pay button should be shown as a payment or provisioning option the samsung pay button serves two key purposes for merchant apps, it enables users to select samsung pay for in-app payments for issuer apps, it allows users to add a card directly to samsung pay via push provisioning setting partnerinfo for verification before checking the status, the partner app must configure and pass a valid partnerinfo object to the samsungpay instance this is essential for verifying the calling app and enabling further sdk functionality the partnerinfo must include serviceid sid a unique identifier assigned by the samsung pay developer portal servicetype defines the type of service e g , merchant or issuer this value is also assigned during service registration samsung pay uses partnerinfo for validating the app’s identity and registration performing sdk version and api compatibility checks verifying allowlist/blocklist status note servicetype is required without it, you cannot call other samsung pay apis once partnerinfo is set correctly, you can proceed to call getsamsungpaystatus to check if samsung pay is available and ready for use on the device val serviceid = "partner_app_service_id" val bundle = bundle bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle after setting partnerinfo, your partner app can now call getsamsungpaystatus this method of the samsungpay class must be called before using any other feature in the samsung pay sdk noteif you want to get the status of samsung pay watch, you have to use the watchmanager class instead of the samsungpay class fun getsamsungpaystatus callback statuslistener copy the result is delivered to statuslistener and provides the following events onsuccess ‒ called when the requested operation is successful it provides the status of the request, as well as extra bundle data related to the request onfail ‒ called when the request operation fails it returns the error code and extra bundle data related to the request the samsung pay status code returned is one of the following spay_not_supported - indicates samsung wallet is not supported on this device; typically returned if the device is incompatible with samsung pay or if the samsung wallet app is not installed spay_not_ready - indicates samsung wallet is not completely activated; usually returned if the user did not complete a mandatory update or if the user has not signed in with a valid samsung account in which case, the partner app can activate or update the samsung wallet app on the device according to the 'extra_error_reason' bundle keys below error_spay_setup_not_complete - tells the partner app to display a popup message asking if the user wishes to activate samsung pay if the user agrees, the partner app calls activatesamsungpay to activate the samsung wallet app error_spay_app_need_to_update - tells the partner app to display a popup message asking if the user wishes to update samsung pay if user agrees, the partner app calls gotoupdatepage to open the app update page error_partner_info_invalid - indicates that partner app information is invalid; typically, the partner app is using a sdk version that is not allowed, an invalid service type, or the wrong api level error_partner_sdk_api_level - tells the partner app it is using the wrong api level to resolve the error condition, the partner app must set a valid api level error_partner_service_type - tells the partner app that it did not set a service type, or that the service type it did set is invalid service type is set in partnerinfo spay_ready - indicates that samsung pay is activated and ready to use; typically returned after the user completes all mandatory updates and signs in extra bundle data can have the following values extra_country_code - for both onsuccess and onfail , this is the current device’s country code iso 3166-1 alpha-2 set by samsung pay if the partner app is not supported in this particular country, the partner app can decide not to display samsung pay button extra_error_reason - for onfailure , this is the reason for failure set by samsung pay when the returned status code is spay_ready, the partner app can safely display the samsung pay button for user selection as a payment option, push provisioning, and so on the following sample code shows how to use the getsamsungpaystatus api method val serviceid = "partner_app_service_id" val bundle = bundle bundle putstring samsungpay partner_service_type, samsungpay servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle val samsungpay = samsungpay context, partnerinfo /* * method to get the samsung pay status on the device * partner issuers, merchants applications must call this method to * check the current status of samsung pay before doing any operation */ samsungpay getsamsungpaystatus object statuslistener { override fun onsuccess status int, bundle bundle { when status { samsungpay spay_not_supported -> // samsung pay is not supported samsungpaybutton setvisibility view invisible samsungpay spay_not_ready -> { // activate samsung pay or update samsung pay, if needed samsungpaybutton setvisibility view invisible val errorreason = bundle getint samsungpay extra_error_reason if errorreason == samsungpay error_setup_not_completed { // display an appropriate popup message to the user samsungpay activatesamsungpay } else if errorreason == samsungpay error_spay_app_need_to_update { // display an appropriate popup message to the user samsungpay gotoupdatepage } else { toast maketext context, "error reason $errorreason", toast length_long show } } samsungpay spay_ready -> // samsung pay is ready samsungpaybutton setvisibility view visible else -> // not expected result samsungpaybutton setvisibility view invisible } } override fun onfail errorcode int, bundle bundle { samsungpaybutton setvisibility view invisible log d tag, "checksamsungpaystatus onfail $errorcode" } } 3 1 9 activating the samsung wallet app the samsungpay class provides the following api method to activate the samsung wallet app on a device fun activatesamsungpay activatesamsungpay is called to activate the samsung wallet app on the same device on which the partner app is running first, however, the partner app must check the samsung pay status with a getsamsungpaystatus call see section 4 2 above if the status is spay_not_ready and extra_error_reason is error_spay_setup_not_complete, the partner app needs to display an appropriate message to user, then call activatesamsungpay to launch the samsung wallet app so the user can sign in here’s an example of how to code this val serviceid = "partner_app_service_id" val bundle = bundle bundle putstring samsungpay partner_service_type, spaysdk servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle val samsungpay = samsungpay context, partnerinfo samsungpay activatesamsungpay 3 1 10 updating the samsung wallet app the samsungpay class provides the following api method to update the samsung wallet app on the device fun gotoupdatepage gotoupdatepage is called to update samsung wallet app on the same device on which the partner app is running as with all api calls, the partner app must first check the samsung pay status with getsamsungpaystatus if this returns spay_not_ready and extra_error_reason is error_spay_app_need_to_update, then the partner app needs to display an appropriate message to the user and call gotoupdatepage , which launches the samsung pay update page the following code sample reflects how to update samsung pay val serviceid = "partner_app_service_id" val bundle = bundle bundle putstring samsungpay partner_service_type, spaysdk servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle val samsungpay = samsungpay context, partnerinfo samsungpay gotoupdatepage 3 1 11 in-app online the main classes and interfaces involved here are samsungpay– class for a merchant app to get samsung pay sdk information and the status of samsung pay on the device paymentmanager – class to provide payment/transaction functionality cardinfolistener – interface for requestcardinfo result callbacks from samsung wallet customsheettransactioninfolistener – interface for transaction success/failure callbacks from samsung wallet; payment information is provided with a success callback and must be used by the merchant app for processing the payment the flow pictured next captures the essential online payment api process between merchant apps integrated with the samsung pay sdk and samsung wallet and the merchant’s payment gateway pg 3 1 12 api flow for in-app payments the api flow for samsung pay in-app payments involves a series of operations that ensure secure, seamless, and verified payment processing between the merchant app, samsung wallet, and the payment gateway pg these steps are illustrated in the flow diagram above and described below check the ready status of samsung pay use samsungpay getsamsungpaystatus to verify whether samsung pay is installed and supported on the device samsung pay is activated and ready for transactions the user has completed mandatory updates and account setup start the payment manager to establish the service binding and verify the merchant app establish a binding between your app and the samsung wallet app validate that the merchant app is authorized and registered prepare the sdk to handle payment operations get payment card information and the payment amount, including updates this step also includes displaying eligible cards to the user allowing the user to select a card for the transaction collecting or updating the payment amount get/update the user’s billing and shipping addresses, including an updated payment amount if shipping charges will be incurred if required by the transaction retrieve or update the user’s billing and shipping address recalculate and update the total payment amount e g , shipping cost impact authenticate the user trigger authentication via trusted user interface tui , using biometrics or other secure methods supported by samsung wallet submit payment information to pg this ensures the user has authorized the transaction send the tokenized payment data received from samsung pay to your designated payment gateway pg for transaction processing this can be done via a direct merchant server-to-pg connection, or samsung pg interface server if applicable verify transaction success or failure receive confirmation of transaction success or failure from the payment gateway communicate the result back to the user and update your app's ui and backend accordingly 3 1 13 token modes network vs gateway to complete the payment, the merchant’s designated payment gateway pg handles one of two types of tokens gateway tokens indirect or network tokens direct the samsung pay sdk supports both types the essential difference between the two types is who decrypts the token information network tokens require that the merchant app handles decryption of the token bundle or work with the pg to handle decryption, whereas gateway token decryption is handled by the pg via the samsung-pg interface server network token mode direct user selects samsung pay as the payment method at checkout in the merchant app 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 app through its pg sdk gateway token mode indirect user selects samsung pay as the payment method at checkout in the merchant app 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 reference id is passed to merchant app via sdk callback merchant app then passes the reference id to the pg for payment process execution samsung-pg interface server returns the payment token to the pg i e , gateway token it received from 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 app on the device for display to the user check with your pg to determine its specific requirements for payment processing regardless of the pg model employed, direct or indirect, the goal is to offer samsung pay as a secure payment method within your merchant app the most common use case involves the following general steps to make a purchase, the user selects to “buy” or got to checkout after adding items to a shopping cart now in checkout, the user selects a payment option; for example, either the merchant’s “standard” method or samsung pay upon selecting samsung pay, the user is presented with a payment sheet that allows for card selection and shipping address confirmation with the option to add/modify information for this order, whereupon the user makes payment card selection from the list of enrolled cards chooses to change or add the delivery address enters required address information in the form presented and saves it authenticates the payment method, amount, and delivery with a biometric verification fingerprint, iris… or pin 3 1 14 checking registered/enrolled card information before displaying the samsung pay button, a partner app can query card brand information for the user’s currently enrolled payment cards in samsung wallet to determine if payment is supported with the enrolled card for example, if a merchant app accepts one card brand exclusively but the user has not registered any cards matching this brand in samsung wallet, the merchant app needs to determine whether or not to display the samsung pay button for this purchase checkout to query the card brand, use the requestcardinfo api method of the paymentmanager class the requestfilter is optional bundle data reserved for future use the merchant app does not need to set a value for it now however, before calling this method, cardinfolistener must be registered so its listener can provide the following events onresult - called when the samsung pay sdk returns card information from samsung wallet; returns information about enrolled cards or is empty if no card is registered onfailure - called when the query fails; for example, if sdk service in the samsung wallet app ends abnormally the following snippet shows how to retrieve the list of supported card brands from samsung pay val serviceid = "partner_app_service_id" val bundle = bundle bundle putstring samsungpay partner_service_type, spaysdk servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle val paymentmanager = paymentmanager context, partnerinfo paymentmanager requestcardinfo bundle , cardinfolistener // get card brand list //cardinfolistener is for listening requestcardinfo callback events val cardinfolistener cardinfolistener = object cardinfolistener { // this callback is received when the card information is received successfully override fun onresult cardresponse list<cardinfo> { var visacount = 0 var mccount = 0 var amexcount = 0 var dscount = 0 var brandstrings = "card info " var brand spaysdk brand? for i in cardresponse indices { brand = cardresponse[i] brand when brand { spaysdk brand americanexpress -> amexcount++ spaysdk brand mastercard -> mccount++ spaysdk brand visa -> visacount++ spaysdk brand discover -> dscount++ else -> { /* other card brands */ } } } brandstrings += " vi = $visacount, mc = $mccount, ax = $amexcount, ds = $dscount" log d tag, "cardinfolistener onresult $brandstrings" toast maketext context, "cardinfolistener onresult" + brandstrings, toast length_long show } /* * this callback is received when the card information cannot be retrieved * for example, when sdk service in the samsung wallet app dies abnormally */ override fun onfailure errorcode int, errordata bundle { //called when an error occurs during in-app cryptogram generation toast maketext context, "cardinfolistener onfailure " + errorcode, toast length_long show } } 3 1 15 creating a transaction request upon successful initialization of the samsungpay class, the merchant app needs to create a transaction request with payment information note as of sdk v2 0 00, the normal payment sheet is deprecated all merchant apps must now use the custom payment sheet, which offers more dynamic controls for tailoring the ui look and feel with additional customer order and payment data merchant app developers choosing to temporarily continue offering the normal sheet will need to configure their android manifest to reflect the pre-2 0 00 version of the sdk used to implement their app’s existing normal sheet, although this is not recommended in all cases, merchant app developers should update their apps with the latest version of the sdk as soon as possible to avoid timing out using an earlier version of the sdk when responding to samsung pay callbacks using the custom payment sheet to initiate a payment transaction with samsung pay’s custom payment sheet, your merchant app must populate the following mandatory fields in customsheetpaymentinfo merchant name - as it will appear in samsung pay’s payment sheet, as well as the user's card account statement amount - the constituent transaction properties currency, item price, shipping price, tax, total price which together determine the total amount the user is agreeing to pay the merchant cautionnot populating the mandatory fields throws an illegalargumentexception optionally, the following fields can be added to the payment information merchant id- can be used for the merchant’s own designated purpose at its discretion unless the merchant uses an indirect pg like stripe or braintree if an indirect pg is used, this field must be set to the merchant’s payment gateway id fetched from the samsung pay developers portal merchant id is mandatory if a merchant requests with a mada token, this field should be included in the payload order number - usually created by the merchant app via interaction with a pg this number is required for refunds and chargebacks in the case of visa cards, the value is mandatory the allowed characters are [a-z][a-z][0-9,-] and the length of the value can be up to 36 characters address - the user’s billing and/or shipping address see applying an addresscontrol for details allowed card brands - specifies card brands accepted by the merchant if no brand is specified, all brands are accepted by default if at least one brand is specified, all other card brands not specified are set to "card not supported’ on the payment sheet here’s the 'customsheetpaymentinfo' structure class customsheetpaymentinfo parcelable { private val version string? = null private val merchantid string? = null private val merchantname string? = null private val ordernumber string? = null private val addressinpaymentsheet addressinpaymentsheet = addressinpaymentsheet do_not_show private val allowedcardbrand list<spaysdk brand>? = null private val cardinfo cardinfo? = null private val iscardholdernamerequired = false private val isrecurring = false private val merchantcountrycode string? = null private val customsheet customsheet? = null private val extrapaymentinfo bundle? = null } your merchant app sends this customsheetpaymentinfo to samsung wallet via the applicable samsung pay sdk api methods upon successful user authentication in direct mode, samsung wallet returns the above "payment info" structure and a result string the result string is forwarded to the pg by your merchant app to complete the transaction it will vary based on the pg you’re using note if you want to add any other information for any card brand, you can add them in the extrapaymentinfo bundle the following example demonstrates how to populate customsheet in the customsheetpaymentinfo class see sample merchant app using custom payment sheet below for example usage of each customsheet control /* * make user's transaction details * the merchant app should send customsheetpaymentinfo to samsung wallet via * the applicable samsung pay sdk api method for the operation being invoked */ private fun makecustomsheetpaymentinfo customsheetpaymentinfo { val brandlist = arraylist<spaysdk brand> // if the supported brand is not specified, all card brands in samsung wallet are // listed in the payment sheet brandlist add paymentmanager brand visa brandlist add paymentmanager brand mastercard brandlist add paymentmanager brand americanexpress /* * make the sheetcontrols you want and add them to custom sheet * place each control in sequence with amountboxcontrol listed last */ val customsheet = customsheet customsheet addcontrol makebillingaddresscontrol customsheet addcontrol makeshippingaddresscontrol customsheet addcontrol makeplaintextcontrol customsheet addcontrol makeshippingmethodspinnercontrol customsheet addcontrol makeamountcontrol val extrapaymentinfo = bundle /* * you can add transaction type for mada card brand * the supported values are purchase and preauthorization * if you don't set any value, the default value is purchase */ extrapaymentinfo putstring spaysdk extra_online_transaction_type, spaysdk transactiontype preauthorization tostring val customsheetpaymentinfo = customsheetpaymentinfo builder setmerchantid "123456" setmerchantname "sample merchant" // merchant requires billing address from samsung wallet and // sends the shipping address to samsung wallet // show both billing and shipping address on the payment sheet setaddressinpaymentsheet customsheetpaymentinfo addressinpaymentsheet need_billing_send_shipping setallowedcardbrands brandlist setcardholdernameenabled true setrecurringenabled false setcustomsheet customsheet setextrapaymentinfo extrapaymentinfo build return customsheetpaymentinfo } 3 1 16 requesting 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 wallet the two methods are defined as follows startinapppaywithcustomsheet - initiates the payment request with a custom payment sheet the payment sheet persists for 5 minutes after the api is called if the time limit expires, the transaction fails updatesheet - must be called to update current payment sheet as of api level 1 5, a merchant app can update the custom sheet with a custom error message refer to updating sheet with custom error message when you call the startinapppaywithcustomsheet method, a custom payment sheet is displayed on the merchant app screen from it, the user can select a registered card for payment and change the billing and shipping addresses, as necessary the result is delivered to customsheettransactioninfolistener, which provides the following events onsuccess - called when samsung pay confirms payment it provides the customsheetpaymentinfo object and the paymentcredential json string customsheetpaymentinfo is used for the current transaction it contains amount, shippingaddress, merchantid, merchantname, ordernumber api methods exclusively available in the onsuccess callback comprise getpaymentcardlast4dpan – returns the last 4 digits of the user's digitized personal/primary identification number dpan getpaymentcardlast4fpan – returns the last 4 digits of the user's funding personal/primary identification number fpan getpaymentcardbrand – returns the brand of the card used for the transaction getpaymentcurrencycode – returns the iso currency code in which the transaction is valued getpaymentshippingaddress – returns the shipping/delivery address for the transaction getpaymentshippingmethod – returns the shipping method for the transaction for pgs using the direct model network tokens , the paymentcredential is a json object containing encrypted cryptogram which can be passed to the pg pgs using the indirect model gateway tokens like stripe, it is a json object containing reference card reference – a token id generated by the pg and status i e , authorized, pending, charged, or refunded refer to payment credential sample for details oncardinfoupdated - called when the user changes the payment card in this callback, updatesheet method must be called to update current payment sheet onfailure - called when the transaction fails; returns the error code and errordata bundle for the failure here’s how to call the startinapppaywithcustomsheet method of the paymentmanager class /* * customsheettransactioninfolistener is for listening callback events of 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 transactionlistener = object 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 wallet * newly selected cardinfo is passed so merchant app can update transaction amount * based on different card if needed , */ val amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol amountboxcontrol updatevalue product_item_id, 1000 0 //item price amountboxcontrol updatevalue product_tax_id, 50 0 // sales tax amountboxcontrol updatevalue product_shipping_id, 10 0 // shipping fee amountboxcontrol updatevalue product_fuel_id, 0 0, "pending" // additional item status amountboxcontrol setamounttotal 1060 0, amountconstants format_total_price_only // grand total customsheet updatecontrol amountboxcontrol // call updatesheet with amountboxcontrol; mandatory try { paymentmanager updatesheet customsheet } catch e java lang illegalstateexception { e printstacktrace } catch e java lang nullpointerexception { e printstacktrace } } /* * this callback is received when the payment is approved by the user and the transaction payload * is generated payload can be an encrypted cryptogram network token mode or the pg's token * reference id gateway token mode */ override fun onsuccess response customsheetpaymentinfo, paymentcredential string, extrapaymentdata bundle { /* * called when samsung pay creates the transaction cryptogram, which merchant app then sends * to merchant server or pg to complete in-app payment */ try { val dpan = response cardinfo cardmetadata getstring spaysdk extra_last4_dpan, "" val fpan = response cardinfo cardmetadata getstring spaysdk extra_last4_fpan, "" toast maketext context, "dpan " + dpan + "fpan " + fpan, toast length_long show } catch e java lang nullpointerexception { e printstacktrace } toast maketext context, "transaction onsuccess", toast length_long show } override fun onfailure errorcode int, errordata bundle { // called when an error occurs during cryptogram generation toast maketext context, "transaction onfailure $errorcode", toast length_long show } } private fun startinapppaywithcustomsheet { // show custom payment sheet try { val bundle = bundle bundle putstring samsungpay partner_service_type, spaysdk servicetype inapp_payment tostring val partnerinfo = partnerinfo serviceid, bundle paymentmanager = paymentmanager context, partnerinfo // request payment using samsung wallet paymentmanager startinapppaywithcustomsheet makecustomsheetpaymentinfo , transactionlistener } catch e illegalstateexception { e printstacktrace } catch e numberformatexception { e printstacktrace } catch e nullpointerexception { e printstacktrace } catch e illegalargumentexception { e printstacktrace } } when an address is provided by samsung wallet, onaddressupdated is called whenever address information is updated in the custom payment sheet you can use the updatesheet method to update the shipping fee or any other relevant information in the payment sheet set the errorcode to determine if the address provided by samsung wallet app is invalid, out of delivery, or does not exist for example, when the merchant does not support the product delivery to the designated location billing address from samsung wallet is not valid for tax recalculation for all such cases, the merchant app should call updatesheet with one of the following error codes error_shipping_address_invalid error_shipping_address_unable_to_ship error_shipping_address_not_exist error_billing_address_invalid error_billing_address_not_exist the sample code included below under applying the address control demonstrates how to use the updatesheet method for 'addresscontrol' in the payment sheet 3 1 17 payment credential sample the paymentcredential is the resulting output of the startinapppaywithcustomsheet method the structure varies depending on the pg you’re using and the integration model—direct or indirect the following paymentcredential is for a visa card for pg using direct network token mode – e g first data, adyen, visa cybersourse sample paymentcredential json output using jwe-only { "billing_address" {"city" "billingcity","country" "usa","state_province" "ca","street" "billingaddr1","zip_postal_code" "123456"}, "card_last4digits" "1122", "3ds" {"data" "eyjhbgcioijsu0exxzuilcjrawqioijcak91a1h2afv4wu5wofiwvgs2y25oactzwwfqzxhiehrvz0vfdhlhyy9npsisinr5cci6ikppu0uilcjjagfubmvsu2vjdxjpdhldb250zxh0ijoiulnbx1blssisimvuyyi6ikexmjhhq00ifq fg2oouvhdgkkivyba2s5kturpwueujkzeyxz7n6kalhqahszv3p5jabaoj-rokcznfjdg3qierzjktu7zxst9gwv4oclahpfdw64w0x6ttaxeyjiivkjug-edxxtwajeyeikgc68wehf1cltsqg4zlwi6upvcaywdppbn0hl0c5wcf5az4wabytv_fda5ahguypne70keqrtwdlacw9mzejx2xth7msd9ohoulr8luq-7gha17jhoobwgmoq9q0haocnm0ljwiuhkoryyu-njulnbkk8fzus_aiumgdv2yn9ygfqilmculb0vwuf0yekx6isgaxi0zqhliusjkcz_w auzzxog46lnrtk3q qe2llws30vzh-zduue8b045cnfrm2p-rjzgbnzchels3v26n64cfg1av5mtp5f-fswbj3ntp5x4v1nk8fmdy0uspxzemfvl5badgac7w9frxt6x5xv1fqu6-q-zkbxcb9bygownt983bckoe1bd5djxfbodlrc4j68ikdjc5m3lebdx6hv0aqzkmilch-jevl3awqykbny4vj7m3fizw7u1prli2zfwukxdfs4vwv3bpm4qudemvnhxj qtymdmn4ne93juljnmwkjg","type" "s","version" "100"}, "merchant_ref" "merchantid", "method" "3ds", "recurring_payment" false } decrypt using the merchant’s private key below is sample private key -----begin rsa private key----- miieowibaakcaqea4lzyjqr+dqd/xleoxct9jwtjxhd2ptjke9djtmijki0h2oc2ghow4ujhhy/1jvft2+zcnjtoxuvlp+76/dwa3bcwfrj+fpp6x5kkylpb+djdyo1ttumltnqcwymjb3u7jbc+xr4vkfrzqjxke7xhn/sbb82ue8c3smzvkynuji<…> -----end rsa private key----- the decrypted output will be similar to this { "amount" "1000", "currency_code" "usd", "utc" "1490266732173", "eci_indicator" "5", "tokenpan" "1234567890123456", "tokenpanexpiration" "0420", //the format is **mmyy** "cryptogram" "ak+zkbpmcorcabcd3agraoacfa==" } note for amex, it needs to be displayed in the format “yymmdd”, so i would like to add this processing the payload depending on the structure of the payment processing api provided by your pg, your merchant app can send either of these directly to the pg entire paymentcredential output extracted “3ds” part only consult your pg documentation for specific guidance when using indirect model e g stripe in indirect gateway token mode, paymentcredential is the pg’s token reference id and its status here’s a sample of the json output { "reference" "tok_18rje5e6szui23f2mefakep7", "status" "authorized" } for stripe, your merchant app should be able to pass this token object directly to charge or another appropriate payment processing api provided by the pg 3 1 18 push provisioning the following diagram illustrates the flows of the app-to-app apis for payment card push provisioning the main classes involved are samsung pay – for fetching samsung wallet app status and wallet information on the device paymentmanager – for push provisioning and invoking favorite cards payment functionalities cardmanager – for payment card management watchmanager – for all functions related to samsung pay watch 3 1 19 requesting registered card list in the samsung pay the getallcards method of the cardmanager class is used to request a list of all cards currently registered/enrolled in samsung wallet on the same device running the issuer’s app to succeed, the issuer app must pass valid partnerinfo to 'cardmanager' for caller verification 'cardfilter' narrows the card list returned by samsung wallet to the issuername specified please be noted that getsamsungpaystatus must be called before getallcards getallcards could not return a cards list when getsamsungpaystatus responds with a code other than spay_ready noteto get the cards list of samsung pay watch, you have to use the watchmanager class instead of the cardmanager class as of api level sdk version 1 4, cardfilter retrieves this information from the samsung pay developers portal certain issuers may need to register multiple issuer name s with the portal, depending on their app and/or the requirements of their token service provider tsp the getallcards parameter cardfilter matches the issuer name s specified with those registered in the portal only complete matches are returned this method is typically called when your partner app wants to check the card status it does not need to be called every time the partner app resumes therefore, you should create the card list with the 'oncreate ' method, rather than the 'onresume ' method the result of a getallcards call is delivered to getcardlistener, which provides the following events onsuccess - called when the operation succeeds; provides the list of all filtered cards and their status card information includes cardid, cardstatus, and extra cardinfo data onfail - called when the operation fails here’s an example of how to use the 'getallcards ' api method in your issuer app val cardfilter = bundle // since api level 1 4, cardfilter param is ignored partner does not need to use it here // it is retrieved from the samsung pay developers portal cardfilter putstring cardmanager extra_issuer_name, issuername cardmanager getallcards null, object getcardlistener{ override fun onsuccess cards mutablelist<card>? { // 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 s in cards { log d tag, "cardid " + s cardid + "cardstatus " + s cardstatus // get extra card data if s cardinfo != null { val cardid = s cardid // since api level 2 13, id from card network val last4fpan = s cardinfo getstring cardmanager extra_last4_fpan val last4dpan = s cardinfo getstring cardmanager extra_last4_dpan val cardtype = s cardinfo getstring cardmanager extra_card_type val cardissuername = s cardinfo getstring cardmanager extra_issuer_name log d tag, "last4fpan $last4fpan last4dpan $last4dpan cardid $cardid" } } } } override fun onfail errorcode int, errordata bundle? { // getting card status is failed } } 3 1 20 getting wallet information the samsungpay class provides the getwalletinfo api method, which is called to request wallet information from the samsung wallet app prior to calling the addcard api, when you want to avoid duplicate provisioning your issuer app uses this information to uniquely identify the user and the samsung wallet app on a particular device wallet device management id, device id, and wallet user id note to get wallet information of samsung pay watch, you have to use the watchmanager class instead of the cardmanager class fun getwalletinfo list<string> keys, statuslistener callback the following example demonstrates how to use it // set the serviceid assigned by the samsung pay developers portal during service creation val serviceid = "sampleserviceid" val bundle = bundle bundle putstring samsungpay extra_issuer_name, "issuer name" bundle putstring samsungpay partner_service_type, servicetype app2app tostring val pinfo = partnerinfo serviceid, bundle val samsungpay = samsungpay context, pinfo // add bundle keys to get wallet information from samsung pay // this information can be delivered to the partner server for an eligibility check val keys = arraylist<string> keys add samsungpay wallet_user_id keys add samsungpay device_id samsungpay getwalletinfo keys, object statuslistener{ override fun onsuccess status int, walletdata bundle { // log d tag, "dowalletinfo onsuccess callback is called" ; // for visa, deviceid can be set to "clientdeviceid" as defined by visa val deviceid = walletdata getstring samsungpay device_id // for visa, walletuserid can be set to "clientwalletaccountid" as defined by visa val walletuserid = walletdata getstring samsungpay wallet_user_id } override fun onfail errorcode int, errordata bundle? { log e tag, "onfail callback is called, errorcode " + errorcode ; // check the extra error codes in the errordata bundle for all the reasons in // samsungpay extra_error_reason, when provided } } 3 1 21 adding a card to samsung pay your issuer app calls the 'addcard ' api method of cardmanager to add a card to samsung wallet by providing the required card details, your app can make it convenient and easy for users to add their bank-issued debit/credit cards to samsung wallet directly from your app without additional steps, like switching between apps note if you want to add a card to samsung pay watch, you have to use the 'watchmanager' class instead of the cardmanager class for most issuers, getwalletinfo suffices for requesting current wallet information the response from samsung wallet tells the issuer app whether or not the user’s card has already been added to samsung wallet or is ineligible for provisioning it is therefore recommended that you call getwalletinfo before displaying the add to samsung pay button if the card is eligible, display the “add” button and, if the user taps it, call addcard important remember to obtain the governing issuer implementation guide s and specifications from the respective card network and implement each network’s required handling in your partner app and server the 'addcard ' result is delivered to addcardlistener, which provides the following events onsuccess - called when the operation succeeds; provides information and status regarding the added card onfail - called when the operation fails; returns the error code and extra bundle data such as extra_error_reason or extra_request_id if provided onprogress - called to indicate the current progress of the 'addcard ' operation; can be used to show a progress bar to the user in the issuer app this callback is supported for tsm solution issuers in china and spain here’s an example of how to use the addcard api method in your issuer app val cardtype = card card_type_credit val tokenizationprovider string = addcardinfo provider_abcd // samsung pay does not provide detailed payload information; generate the provisioning payload in // accordance with your card network specifications val testpayload = "thisistestpayloadcardinfo1234567890" //bin bank identification number can be set to issuerid it is mandatory for some card network val issuerid = "123456" val carddetail = bundle carddetail putstring extra_provision_payload, testpayload carddetail putstring extra_issuer_id, issuerid val addcardinfo = addcardinfo cardtype, tokenizationprovider, carddetail cardmanager addcard addcardinfo, object addcardlistener { override fun onsuccess status int, card card? { log d tag, "onsuccess callback is called" ; } override fun onfail errorcode int, errordata bundle? { log d tag, "onfail callback is called" ; // check some extra error codes in the errordata bundle // such as samsungpay extra_error_reason or samsungpay extra_request_id if provided } override fun onprogress currentcount int, totalcount int, bundledata bundle? { log d tag,"onprogress callback is called " + currentcount + " / " + totalcount ; } } 3 1 22 adding a co-badge card to samsung pay co-badge payment cards combine two payment brands/networks to add a co-badge card through push provisioning, you must provide two different card network details one for the primary card network and another for the secondary card network issuer app calls the addcobadgecard api method of cardmanager to add a co-badge card to samsung pay in most cases, calling getwalletinfo will suffice to request current wallet information the response from samsung pay indicates whether the user's co-badge card has already been added to samsung pay or is ineligible for provisioning therefore, it is advisable to call getwalletinfo before displaying the add to samsung pay button if the co-badge card is eligible, display the "add" button and, upon user tapping, call addcobadgecard important please remember to refer to the relevant issuer implementation guide s and specifications provided by each card network and ensure that your partner app and server adhere to their specific requirements the addcobadgecard result is delivered to addcardlistener, which provides the following events onsuccess - called when the operation succeeds; provides information and status regarding the added card onfail - called when the operation fails; returns the error code and extra bundle data such as extra_error_reason or extra_request_id if provided onprogress - called to indicate the current progress of the 'addcard ' operation; can be used to show a progress bar to the user in the issuer app this callback is supported for tsm solution issuers in china and spain here’s an example of how to use the addcobadgecard api method in your issuer app notesamsung pay does not provide detailed payload information; generate the provisioning payload in accordance with your card networks specifications string cardtype = card card_type_credit; string primarytokenizationprovider = addcardinfo provider_abcd; //provide your primary card network payload string testprimarypayload = "thisistestprimarypayloadcardinfo1234567890"; string secondarytokenizationprovider = addcardinfo provider_efgh; //provide your secondary card network payload string testsecondarypayload = "thisistestsecondarypayloadcardinfo1234567890"; bundle primarycarddetail = new bundle ; primarycarddetail putstring addcardinfo extra_provision_payload, testprimarypayload ; addcardinfo primaryaddcardinfo = new addcardinfo cardtype, primarytokenizationprovider, primarycarddetail ; bundle secondarycarddetail = new bundle ; secondarycarddetail putstring addcardinfo extra_provision_payload, testsecondarypayload ; addcardinfo secondaryaddcardinfo = new addcardinfo cardtype, secondarytokenizationprovider, secondarycarddetail ; cardmanager addcobadgecard primaryaddcardinfo, secondaryaddcardinfo, new addcardlistener { @override public void onsuccess int status, card card { log d tag, "onsuccess callback is called" ; } @override public void onfail int error, bundle errordata { log d tag, "onfail callback is called" ; check some extra error codes in the errordata bundle such as samsungpay extra_error_reason or samsungpay extra_request_id if provided } @override public void onprogress int currentcount, int totalcount, bundle bundledata { log d tag,"onprogress callback is called " + currentcount + " / " + totalcount ; } } ; 3 1 23 sample 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, controlld 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 the workflow for shippingaddresscontrol 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 billing address control zip code billing address control shipping address control applying a plaintextcontrol this control is used for displaying a title with 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 plaintextcontrol flow 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 note the setamounttotal api may accept strings that are not predefined as an argument, but it generates 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 important your 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 note shipping_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 3 1 24 api references
Develop Samsung Blockchain
apipackage class tree deprecated index help com samsung android sdk coldwallet class scwservice java lang object com samsung android sdk coldwallet scwservice public class scwservice extends java lang object class for the proxy to use the samsung blockchain keystore service the keystore's hd wallet seed is bip-39 compatible see also https //github com/bitcoin/bips/blob/master/bip-0039 mediawiki nested class summary nested classes modifier and type class and description static class scwservice scwcheckformandatoryappupdatecallback callback for checkformandatoryappupdate api static class scwservice scwgetaddresslistcallback callback for getaddresslist api static class scwservice scwgetextendedpublickeylistcallback callback for getextendedpublickeylist api static class scwservice scwsignbtctransactioncallback callback for signbtctransaction api static class scwservice scwsignethpersonalmessagecallback callback for signethpersonalmessage api static class scwservice scwsignethtransactioncallback callback for signethtransaction api static class scwservice scwsignklaytransactioncallback callback for signklaytransaction api method summary all methods static methods instance methods concrete methods modifier and type method and description void checkformandatoryappupdate scwservice scwcheckformandatoryappupdatecallback callback checks whether a mandatory update of samsung blockchain keystore is needed or not void getaddresslist scwservice scwgetaddresslistcallback callback, java util arraylist<java lang string> hdpath request to get a list of addresses that corresponds to a list of hd paths void getextendedpublickeylist scwservice scwgetextendedpublickeylistcallback callback, java util arraylist<java lang string> hdpath request to get a list of extended public keys that corresponds to a list of hd paths static scwservice getinstance return the instance of the keystore proxy object int getkeystoreapilevel get api level which the keystore in the device supports java lang string getseedhash get the pseudo seed hash which is randomly generated when the hd wallet created whenever the seed for the wallet is changed, this key shall be changed int[] getsupportedcoins get coin types supported by samsung blockchain keystore void signbtctransaction scwservice scwsignbtctransactioncallback callback, byte[] transaction, java util list<java lang string> hdpathlist, java util list<byte[]> utxotxlist, java lang string changehdpath request to sign bitcoin transaction void signethpersonalmessage scwservice scwsignethpersonalmessagecallback callback, byte[] msg, java lang string hdpath request to sign ethereum typed structured data void signethtransaction scwservice scwsignethtransactioncallback callback, byte[] transaction, java lang string hdpath request to sign ethereum transaction void signklaytransaction scwservice scwsignklaytransactioncallback callback, byte[] transaction, java lang string hdpath, int networkid request to sign klay transaction methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait method detail getinstance public static scwservice getinstance return the instance of the keystore proxy object returns the instance, or null if samsung blockchain keystore is not available on the device getkeystoreapilevel public int getkeystoreapilevel get api level which the keystore in the device supports caution you should check the api level before invoking any apis otherwise, it will return scwapilevelexception if keystore api level is lower than the required level, update the keystore app first via scwdeeplink galaxy_store returns api level since api level 1 getseedhash public java lang string getseedhash get the pseudo seed hash which is randomly generated when the hd wallet created whenever the seed for the wallet is changed, this key shall be changed returns null if keystore does not support wallet key, zero-length string if the wallet is not created otherwise, wallet is created since api level 1 getsupportedcoins public int[] getsupportedcoins get coin types supported by samsung blockchain keystore returns array of coin types, scwcointype throws scwapilevelexception - api level exception since api level 1 see also https //github com/satoshilabs/slips/blob/master/slip-0044 md checkformandatoryappupdate public void checkformandatoryappupdate @nonnull scwservice scwcheckformandatoryappupdatecallback callback checks whether a mandatory update of samsung blockchain keystore is needed or not do not call this method in the background thread if there is a mandatory update, you need to open the app update link, scwdeeplink galaxy_store parameters callback - result callback since api level 1 getextendedpublickeylist public void getextendedpublickeylist @nonnull scwservice scwgetextendedpublickeylistcallback callback, @nonnull java util arraylist<java lang string> hdpath request to get a list of extended public keys that corresponds to a list of hd paths parameters callback - result callback hdpath - the hd path list to bring the public keys the depth of a path should be between 3 and 6 for example, "m/44'/60'", "m/44'/60'/0'/0/0" since api level 1 see also https //github com/bitcoin/bips/blob/master/bip-0032 mediawiki getaddresslist public void getaddresslist @nonnull scwservice scwgetaddresslistcallback callback, @nonnull java util arraylist<java lang string> hdpath request to get a list of addresses that corresponds to a list of hd paths parameters callback - result callback hdpath - the hd path list to bring the addresses the depth of a path should be between 3 and 6 for example, "m/44'/60'", "m/44'/60'/0'/0/0" since api level 1 see also https //github com/bitcoin/bips/blob/master/bip-0032 mediawiki signethtransaction public void signethtransaction @nonnull scwservice scwsignethtransactioncallback callback, @nonnull byte[] transaction, @nonnull java lang string hdpath request to sign ethereum transaction parameters callback - result callback transaction - a byte array of a rlp-encoded unsigned ethereum transaction hdpath - hd path that corresponds to public key needed for signing since api level 1 signethpersonalmessage public void signethpersonalmessage @nonnull scwservice scwsignethpersonalmessagecallback callback, @nonnull byte[] msg, @nonnull java lang string hdpath request to sign ethereum typed structured data parameters callback - result callback msg - a byte array of raw message to be signed the keystore will add "ethereum signed message \n" prefix, so it should not be included in msg hdpath - hd path that corresponds to public key needed for signing since api level 1 see also https //github com/ethereum/eips/blob/master/eips/eip-712 md signklaytransaction public void signklaytransaction @nonnull scwservice scwsignklaytransactioncallback callback, @nonnull byte[] transaction, @nonnull java lang string hdpath, @nonnull int networkid request to sign klay transaction parameters callback - result callback transaction - a byte array of a raw transaction to be signed by samsung blockchain keystore the transaction is same as the sigrlp value mentioned in klaytn's official document hdpath - hd path that corresponds to public key needed for signing networkid - the klaytn network id, or the integer to identify the network "8217" is klaytn cypress mainnet and "1001" is klaytn baobab testnet since api level 2 see also https //docs klaytn com/node/en/installation/config signbtctransaction public void signbtctransaction @nonnull scwservice scwsignbtctransactioncallback callback, @nonnull byte[] transaction, @nonnull java util list<java lang string> hdpathlist, @nonnull java util list<byte[]> utxotxlist, @nonnull java lang string changehdpath request to sign bitcoin transaction parameters callback - result callback transaction - a byte array of a serialized unsigned bitcoin transaction to be signed by samsung blockchain keystore hdpathlist - a list of hd paths that corresponds to utxo's public key utxotxlist - a list of byte array of the serialized transaction which contain the utxo used in this transaction changehdpath - hd path that corresponds to the change address since api level 2 see also https //github com/bitcoin/bips/blob/master/bip-0044 mediawiki, https //github com/bitcoin/bips/blob/master/bip-0049 mediawiki, https //github com/bitcoin/bips/blob/master/bip-0084 mediawiki
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.