Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials mobile
blogsamsung wallet is a fast and secure digital wallet application bundled with millions of samsung galaxy devices worldwide. its streamlined functionality allows users to add and store various passes, tickets, and credentials all in one place. you can design custom wallet cards, such as for boarding passes, tickets, coupons, gift cards and loyalty cards, for your service and issue them to users who can add them to the samsung wallet application on their device. samsung wallet cards are signed with the rs256 asymmetric algorithm. the rs256 signing algorithm requires a private key, which is a personal credential that must never be shared in the application. consequently, a separate server application is needed to store the key and sign the wallet card data (cdata). when the user taps the "add to samsung wallet" button in the application, the server application creates and signs the wallet card data, then returns a jwt token that is used to add the wallet card to the user's samsung wallet application. figure 1: "add to wallet" flow this tutorial uses kotlin to demonstrate how to implement the "add to wallet" feature in an android mobile application that adds movie tickets to samsung wallet. it also shows how to generate the wallet cards using a spring boot server. you can follow along with the tutorial by downloading the sample code files. develop the mobile application to implement the "add to wallet" button in the mobile application, you must configure the application, implement the application ui, and define the application logic for the button. configuring the mobile application project create an application project and configure it to connect to and communicate with the server through rest api requests: in android studio, create a new project. to implement rest api support in the application, add the following retrofit library dependencies to the application's "build.gradle" file: 'com.squareup.retrofit2:retrofit:2.11.0' 'com.squareup.retrofit2:converter-gson: 2.11.0' to enable communication with the server, add the following permissions to the "androidmanifest.xml" file: <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_network_state"/> <uses-permission android:name="android.permission.access_wifi_state"/> to enable testing with a local non-https server, add the following attribute to the "application" element in the "androidmanifest.xml" file: android:usescleartexttraffic="true" implementing the application ui the application ui consists of two screens: the movie tickets list and a ticket detail page. in the application code, define a movie data class that contains details for the movie tickets that can be added to samsung wallet. data class movie( val name:string, val studio:string, val ticketnumber:string, ) create a recyclerview that displays the list of movie tickets as buttons on the main screen. each button has a listener that opens the detail page for the ticket. you can study the implementation details in the sample code. to check whether the device supports samsung wallet, send an http get request to the following endpoint, where build.model is the model of the device: https://api-us3.mpay.samsung.com/wallet/cmn/v2.0/device/available?servicetype=wallet&modelname=${build.model} create the ticket detail page layout in the "activity_movie_detail.xml" file. the "add to wallet" button is implemented on this page. figure 2: detail page layout implement the ticket detail page functionality in the moviedetailactivity activity class in the application code. for this demonstration, the movie ticket data is predefined in the application code. in a real application, the data is usually retrieved in real time from an external database. val movielists = listof<movie>( movie("the wallet", "samsung studios", "a-01"), movie("crying sea", "laplace studio","h-07"), movie("canoe", "terra productions", "r-03") ) val position:int = intent.getintextra("movieposition", 0) val movie:movie = movielists[position] binding.mvnametext.text = movie.name binding.mvstudiotext.text = movie.studio binding.mvticketnumber.text = "ticket: ${movie.ticketnumber}" binding.addtowalletbutton.setonclicklistener { // request server to generate card data // retrieve signed card data from server // add card to samsung wallet application } when the user taps the "add to wallet" button, onclicklistener() is triggered. its functionality is defined later in this tutorial. connecting to the server to communicate with the server: in the tokenresponse class, define the structure of the json response to be received from the server. the status field indicates whether the token generation request was successful, and the jwt field contains the generated cdata in the form of a jwt token. data class tokenresponse( val status: string, val jwt:string ) in the "apiclient.kt" file, define a retrofitclient object that is used to establish the connection with the server. define the apiinterface interface, which defines the api request and response: the api endpoint url is base_url/movie/{id}, where {id} is the movie ticket id to be added the expected response from the endpoint is a tokenresponse object. define an apiclient object that extends apiinterface and creates a retrofitclient instance to establish the server connection. object retrofitclient { private const val base_url = "http://192.xxx.xxx.xxx:8080" // define your server url val retrofit: retrofit by lazy { retrofit.builder() .baseurl(base_url) .addconverterfactory(gsonconverterfactory.create()) .build() } } interface apiinterface { @get("/movie/{id}") suspend fun getmovie(@path("id") movieid:int): response<tokenresponse> } object apiclient { val apiservice: apiinterface by lazy { retrofitclient.retrofit.create(apiinterface::class.java) } } adding card data to samsung wallet to request cdata generation from the server and add the wallet card to samsung wallet: in the addtowalletbutton.setonclicklistener() method within the moviedetailactivity class, send a request to the server to generate cdata for the selected movie ticket. if cdata generation is successful, to add the movie ticket to samsung wallet, send an http request containing the cdata token to the following endpoint url: https://a.swallet.link/atw/v1/{card id}#clip?cdata={cdata token} for more information about this endpoint, see data transmit link. binding.addtowalletbutton.setonclicklistener { coroutinescope(dispatchers.main).launch { val response = apiclient.apiservice.getmovie(position) if(response.issuccessful && response.body()!=null){ startactivity(intent( intent.action_view, uri.parse("http://a.swallet.link/atw/v1/3aabbccddee00#clip?cdata=${response.body()!!.jwt}"))) // replace '3aabbccddee00' part with your card id } } } notethe generated cdata is valid for 30 seconds, so it is recommended to generate the cdata only when the "add to samsung wallet" button is clicked. if the cdata has expired by the time the token is sent to samsung wallet, the user can receive a "request timed out" error. generate signed wallet card data the server application must be configured to receive the card data request from the mobile application and return a signed jwt token. this part of the tutorial uses the spring boot framework. configuring the server project to create and configure a server application to generate and sign wallet card data: in the spring initializr tool or any supported java ide, create a spring boot project and open the sample code. to configure the server to receive rest api requests from the mobile application, add the "spring web" dependency to the project. define a token data class. make sure it has the same attributes as the tokenresponse data class defined in the mobile application. data class token(val status:string, val jwt:string initialize a tokencontroller class that receives the incoming requests and returns a token object in response. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { return token("success", "{dummy_cdata}") // cdata generation logic } } the cdata generation and signing logic is described in the next section. implementing card data signing logic for easier understanding, this section describes a simplified implementation of the cdata generation sample code. in the server application project, copy the following credential files to the "sample/securities/" directory. samsung public key from the samsung certificate ("samsung.crt") partner public key from your partner certificate ("partner.crt") partner private key from the private key file ("partner.key") to handle the certificate files and signing algorithms, add the following dependencies to the server application's "build.gradle" file: implementation 'com.nimbusds:nimbus-jose-jwt:9.37.3' implementation 'org.bouncycastle:bcprov-jdk18on:1.77' in a new "jwtgen.kt" file, define a readcertificate() method that reads the public keys from the certificates and a readprivatekey() method that reads the private key from the key file. private val partner_id = "4048012345678912345" // replace with your partner id private val samsungpublickey = readcertificate(getstringfromfile("sample/securities/samsung.crt")) private val partnerpublickey = readcertificate(getstringfromfile("sample/securities/partner.crt")) private val partnerprivatekey = readprivatekey(getstringfromfile("sample/securities/partner.key")) fun readprivatekey(key: string): privatekey { val keybyte = readkeybyte(key) lateinit var privatekey: privatekey val pkcs8spec = pkcs8encodedkeyspec(keybyte) try { val kf = keyfactory.getinstance("rsa") privatekey = kf.generateprivate(pkcs8spec) } catch (e: invalidkeyspecexception) { e.printstacktrace() } catch (e: nosuchalgorithmexception) { e.printstacktrace() } return privatekey } fun readcertificate(cert: string): publickey { lateinit var certificate: certificate val keybyte = readkeybyte(cert) val `is`: inputstream = bytearrayinputstream(keybyte) try { val cf = certificatefactory.getinstance("x.509") certificate = cf.generatecertificate(`is`) } catch (e: certificateexception) { e.printstacktrace() } return certificate.publickey } private fun readkeybyte(key: string): bytearray { val keybyte: bytearray val bais = bytearrayinputstream(key.tobytearray(standardcharsets.utf_8)) val reader: reader = inputstreamreader(bais, standardcharsets.utf_8) val pemreader = pemreader(reader) var pemobject: pemobject? = null try { pemobject = pemreader.readpemobject() } catch (e: ioexception) { e.printstacktrace() } keybyte = if (pemobject == null) { base64.getdecoder().decode(key) } else { pemobject.content } return keybyte } fun getstringfromfile(path: string?): string { try { val file = file(objects.requirenonnull(classloader.getsystemclassloader().getresource(path)).file) return string(files.readallbytes(file.topath())) } catch (e: ioexception) { throw runtimeexception(e) } } generating card data cdata token generation is implemented in the "jwtgen.kt" file: read the file containing raw json data that defines the ticket data structure. for this demonstration, use the "ticket.json" file in the "sample/payload/" directory of the cdata generation sample code. generate or fill in the required ticket details. for example, the "{title}" and "{seatnumber}" fields are replaced with the movie title and seat number. for information about the complete json structure, see wallet cards. convert the json data to a jwe object. encrypt the jwe object with the samsung public key. build the custom jws header for samsung wallet cards. sign and validate the complete jws object with your partner private and public key using the rs256 asymmetric algorithm. this is the cdata token. private val currenttimemillis = system.currenttimemillis() private val plaindata:string = getstringfromfile("sample/payload/ticket.json") .replace("{refid}", uuid.randomuuid().tostring()) .replace("{language}", "en") .replace("{createdat}", currenttimemillis.tostring()) .replace("{updatedat}", currenttimemillis.tostring()) .replace("{issuedate}", currenttimemillis.tostring()) .replace("{startdate}", (currenttimemillis + timeunit.days.tomillis(1)).tostring()) .replace("{enddate}", (currenttimemillis + timeunit.days.tomillis(1) + +timeunit.hours.tomillis(2)).tostring()) fun generatecdata(moviename: string, movieticktno:string): string{ // modify data as needed val data = plaindata.replace("{title}", "\"$moviename\"") .replace("{seatnumber}","\"$movieticktno\"") //print(data) return generate(partner_id, samsungpublickey, partnerpublickey, partnerprivatekey, data) } private fun generate(partnerid: string, samsungpublickey: publickey, partnerpublickey: publickey, partnerprivatekey: privatekey, data: string): string { val jweenc = encryptionmethod.a128gcm val jwealg = jwealgorithm.rsa1_5 val jweheader = jweheader.builder(jwealg, jweenc).build() val encryptor = rsaencrypter(samsungpublickey as rsapublickey) val jwe = jweobject(jweheader, payload(data)) try { jwe.encrypt(encryptor) } catch (e: joseexception) { e.printstacktrace() } val payload = jwe.serialize() val jwsalg = jwsalgorithm.rs256 val utc = system.currenttimemillis() val jwsheader = jwsheader.builder(jwsalg) .contenttype("card") .customparam("partnerid", partnerid) .customparam("ver", "2") .customparam("utc", utc) .build() val jwsobj = jwsobject(jwsheader, payload(payload)) val rsajwk = rsakey.builder(partnerpublickey as rsapublickey) .privatekey(partnerprivatekey) .build() val signer: jwssigner try { signer = rsassasigner(rsajwk) jwsobj.sign(signer) } catch (e: joseexception) { e.printstacktrace() } return jwsobj.serialize() } returning the signed token in the server application code, when the server receives a request at the movie/{movieid} endpoint, the tokencontroller class calls the jwtgen.generatecdata() method with the movie id, which generates and returns the cdata jwt token in the api response. in this tutorial, since the movie ticket list was predefined in the mobile application project, make sure the same movie data class and list are defined here too. @restcontroller @requestmapping("movie") class tokencontroller { @getmapping(path = ["/{movieid}"]) fun getmovie(@pathvariable movieid:int): token { val movielists = listof<movie>( movie("the wallet", "samsung studios", "a-01"), movie("crying sea", "laplace studio","h-07"), movie("canoe", "terra productions", "r-03") ) if( movieid>2){ // implement your verification logic return token("failure", "") } else{ val cdata = jwtgen.generatecdata(movielists[movieid].name, movielists[movieid].ticketnumber) return token("success", cdata) } } } testing the application to test your "add to wallet" integration: connect the server and the mobile device to the same network. launch the server and mobile applications. in the mobile application, tap a movie ticket in the list. its detail page opens. tap add to samsung wallet. the server generates and returns the cdata token. the samsung wallet application launches on the device and the movie ticket information is added to it. figure 3: ticket added to samsung wallet summary implementing the "add to wallet" feature enables your users to add your digital content, such as tickets, passes, and loyalty cards, to the samsung wallet application on their mobile device as wallet cards. in addition to implementing the "add to samsung wallet" button in your mobile application, you must also create a server application that securely generates and signs the wallet card data and returns it to the mobile application for transmitting to samsung wallet. for more information about adding "add to wallet" to your application, see implementing atw button. you can also study the extended sample application (clicking this link downloads the sample code) and the api reference. if you have questions about or need help with the information presented in this article, you can share your queries on the samsung developers forum. you can also contact us directly for more specialized support through the samsung developer support portal. resources click the links below to download the sample code. android app sample code extended android app sample code cdata generation server sample code
Mobassir Ahsan
Develop Samsung Pay
docenable app to app service the following diagram illustrates the flows of the app-to-app apis for payment card push provisioning bank appsamsung wallet apptoken service providerref[checking samsungpay status]section in common flowalt[if neccessary optional ]1cardmanager getallcards 2onsuccess card cardid, card cardstatus 3request card information with card cardid4success5samsungpay getwalletinfo 6onsuccess device_id, wallet_user_id 7create provisioningpayloadwith card information & wallet informationrefer to card networks spec8cardmanager addcard payload 9request token provision10success11onsuccess flows of push provisioning apis the main classes involved are samsung pay – for fetching samsung wallet app status and wallet information on the device paymentmanager – for card provisioning and invoking favorite cards payment functionalities cardmanager – for payment card management watchmanager – for all functions related to samsung pay watch let’s now take a look at how each one works in the context of your bank app requesting registered card list in the samsung pay thegetallcards 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 } } 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 noteto 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 } } 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 noteif 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 importantremember 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" val carddetail = bundle carddetail putstring extra_provision_payload, testpayload 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 ; } } 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 note samsung 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 ; } } ;
Develop Samsung Wallet
docwallet cards & templates overall managing process the following image illustrates the process of managing wallet cards create wallet cards draft status partners can create and manage their wallet cards with this step-by-step guide manage wallet cards you can manage all registered wallet cards you can edit wallet cards and check their status general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet item description testing mode all data generated in testing mode is periodically deleted be sure to turn off the "testing mode" setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name partner app package name partner application package name wallet card template pre-defined partner wallet card template partner get card data url for the partner api call to receive card data if the partner uses this api, enter the url otherwise leave it blank partner send card state url for the partner api call to send a card state notification if the partner uses this api, enter the url otherwise leave it blank samsung server ips samsung wallet server ips which need to be allowed by the partner’s firewall, separately described for inbound and outbound wearable wallet assistance whether to support the wearable wallet service support ‘no network’ status whether to support wallet card opening during the ‘no network’ status description description of the wallet card select template you can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id you can select the type of wallet card from the select wallet card template pop-up window first, select the one you want in the wallet card type drop-down menu and then click wallet card sub type to select one of the templates belonging to the card type wallet card type boarding pass wallet card type tickets wallet card type coupons wallet card type digital id wallet card type gift card wallet card type loyalty membership view wallet card you can view all registered information for a wallet card, as well as edit and delete it launch wallet cards verifying status you can launch and activate cards, at which point they move to verification you can activate a card by clicking the "launch" button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, you can modify the card and re-launch the administrator registers the reason for rejection when rejecting the launched wallet card it is sent to the partner by email from the system, including the reason for rejection partners can apply for launch again by checking the reason for rejection and modifying the wallet card information testing mode you can test a card internally to make sure everything works before you officially expose it to users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to 'active' after administrator approval when the card is activated, it is made visible to the user "add to wallet" integration for wallet integration, you need to insert an "add to wallet" script to your system the "add to wallet" script is available for web, android, and email/mms each system has different script composition to implement an "add to wallet" button, follow the procedure below create the tokenized card data cdata card data is the actual content data of wallet card and it has several formats based on the card type refer to cdata generation sample code for details copy the sample "add to wallet" script from the partners portal’s wallet card page and replace "cdata" with the data token created above apply the script to your system see partners portal’s wallet card and android integration sample code for details below is the "add to wallet" script guide in the partners portal for "add to wallet" integration, you may need some base data you can find that and other necessary information on partners portal and wallet api spec you can also add image beacon in the script for tracking effect analysis merchant push notification partners can create a message template for sending pushes on each of their wallet cards type partners can only choose the merchant push type message type you can choose a message type from marketing or others rejected comment if the merchant push notification is rejected after request approval, you can modify the message template the administrator registers the reason for rejection when rejecting the merchant push notification it is sent to the partner by email from the system, including the reason for rejection partners can request for approval again by checking the reason for rejection and modifying the message template approved date displays the date and time when the push message is approved by the administrator message template you can create the contents of the push, and it is also possible to put the available variables in '{{}}' after configuring the content, click harmfulness verification to verify whether there is a harmful expression in the content the verified result is displayed as pass or fail, and if it is fail, it shows the filtered harmful expression together even if the verified result is fail, an approval request can be made, but it can be rejected by the administrator if a different language is added to the default language in general information, the message template must also be entered for each added language request approval button after completing the message template, click this button to send an e-mail requesting approval to the administrator
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 payment class customsheetpaymentinfo builder java lang object com samsung android sdk samsungpay v2 payment customsheetpaymentinfo builder enclosing class customsheetpaymentinfo public static class customsheetpaymentinfo builder extends object this is builder class for constructing customsheetpaymentinfo object since api level 1 3 constructor summary constructors constructor description builder method summary all methodsinstance methodsconcrete methods modifier and type method description customsheetpaymentinfo build api to build customsheetpaymentinfo object customsheetpaymentinfo builder enableenforcepaymentsheet api to enforce the payment sheet if partner wants to show payment sheet even though fast checkout is enabled, they can show payment sheet using this api method customsheetpaymentinfo builder setaddressinpaymentsheet customsheetpaymentinfo addressinpaymentsheet addressinpaymentsheet api to set the address display option for payment sheet customsheetpaymentinfo builder setallowedcardbrands list<spaysdk brand> brands api to set the card brands list supported by merchant customsheetpaymentinfo builder setcardholdernameenabled boolean iscardholdernamerequired api to set the flag if merchant wants to display card holder's name customsheetpaymentinfo builder setcustomsheet customsheet customsheet api to set customsheet customsheetpaymentinfo builder setextrapaymentinfo android os bundle extrapaymentinfo api to set the extra payment information data customsheetpaymentinfo builder setmerchantcountrycode string merchantcountrycode api to set the merchant country code customsheetpaymentinfo builder setmerchantid string merchantid api to set the merchant reference id customsheetpaymentinfo builder setmerchantname string merchantname api to set the merchant name customsheetpaymentinfo builder setordernumber string ordernumber api to set the order number customsheetpaymentinfo builder setpaymentcardbrand spaysdk brand cardbrand api to set the card brand for payment transaction this api can be used with setpaymentcardlast4dpan string or setpaymentcardlast4fpan string api method to designate specific card for the transaction customsheetpaymentinfo builder setpaymentcardlast4dpan string last4digits api to set the last 4 digits of dpan for payment transaction this api can be used with setpaymentcardbrand spaysdk brand api method to designate specific card for the transaction customsheetpaymentinfo builder setpaymentcardlast4fpan string last4digits api to set the last 4 digits of fpan for payment transaction this api can be used with setpaymentcardbrand spaysdk brand api method to designate specific card for the transaction customsheetpaymentinfo builder setpaymentshippingmethod string shippingmethod api to set the shipping method for payment transaction customsheetpaymentinfo builder setrecurringenabled boolean isrecurring api to set if payment is recurring methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait constructor details builder public builder method details setmerchantid @nonnull public customsheetpaymentinfo builder setmerchantid string merchantid api to set the merchant reference id parameters merchantid - merchant reference id which can be used for merchant's own purpose for example, if merchant uses a payment gateway which requires payment gateway user id, then merchantid field can be set with a payment gateway user id returns customsheetpaymentinfo builder since api level 1 3 setmerchantname @nonnull public customsheetpaymentinfo builder setmerchantname string merchantname api to set the merchant name parameters merchantname - merchant name returns customsheetpaymentinfo builder since api level 1 3 setordernumber @nonnull public customsheetpaymentinfo builder setordernumber string ordernumber api to set the order number parameters ordernumber - order number sent by merchant for records the allowed characters are [a-z][a-z][0-9,-] & up to 36 characters this field is mandatory for visa returns customsheetpaymentinfo builder since api level 1 3 setaddressinpaymentsheet @nonnull public customsheetpaymentinfo builder setaddressinpaymentsheet customsheetpaymentinfo addressinpaymentsheet addressinpaymentsheet api to set the address display option for payment sheet parameters addressinpaymentsheet - address ui to display on the payment sheet returns customsheetpaymentinfo builder since api level 1 3 see also customsheetpaymentinfo addressinpaymentsheet setallowedcardbrands @nonnull public customsheetpaymentinfo builder setallowedcardbrands list<spaysdk brand> brands api to set the card brands list supported by merchant parameters brands - card brands supported by merchant for payment returns customsheetpaymentinfo builder since api level 1 3 setcardholdernameenabled @nonnull public customsheetpaymentinfo builder setcardholdernameenabled boolean iscardholdernamerequired api to set the flag if merchant wants to display card holder's name set to true if card holder's name should be displayed with card information on the payment sheet if issuer does not provide card holder's name, it will not be displayed parameters iscardholdernamerequired - true, if merchant wants to display card holder's name on the payment sheet returns customsheetpaymentinfo builder since api level 1 3 setrecurringenabled @nonnull public customsheetpaymentinfo builder setrecurringenabled boolean isrecurring api to set if payment is recurring parameters isrecurring - true, if payment is recurring returns customsheetpaymentinfo builder since api level 1 3 setmerchantcountrycode @nonnull public customsheetpaymentinfo builder setmerchantcountrycode @nullable string merchantcountrycode api to set the merchant country code this api internally verifies and sets two-letter merchant country code, if it is a valid country code parameters merchantcountrycode - country code, where merchant is operating returns customsheetpaymentinfo builder throws illegalargumentexception - if merchantcountrycode is invalid since api level 1 3 setcustomsheet @nonnull public customsheetpaymentinfo builder setcustomsheet customsheet customsheet api to set customsheet parameters customsheet - customsheet configured by merchant returns customsheetpaymentinfo builder since api level 1 3 setextrapaymentinfo @nonnull public customsheetpaymentinfo builder setextrapaymentinfo android os bundle extrapaymentinfo api to set the extra payment information data parameters extrapaymentinfo - extra paymentinfo data returns customsheetpaymentinfo builder since api level 1 3 enableenforcepaymentsheet @nonnull public customsheetpaymentinfo builder enableenforcepaymentsheet api to enforce the payment sheet if partner wants to show payment sheet even though fast checkout is enabled, they can show payment sheet using this api method returns customsheetpaymentinfo builder since api level 1 7 setpaymentcardlast4dpan @nonnull public customsheetpaymentinfo builder setpaymentcardlast4dpan string last4digits api to set the last 4 digits of dpan for payment transaction this api can be used with setpaymentcardbrand spaysdk brand api method to designate specific card for the transaction parameters last4digits - the last 4 digits of dpan for payment transaction returns customsheetpaymentinfo builder since api level 1 7 setpaymentcardlast4fpan @nonnull public customsheetpaymentinfo builder setpaymentcardlast4fpan string last4digits api to set the last 4 digits of fpan for payment transaction this api can be used with setpaymentcardbrand spaysdk brand api method to designate specific card for the transaction parameters last4digits - the last 4 digits of fpan for payment transaction returns customsheetpaymentinfo builder since api level 1 7 setpaymentcardbrand @nonnull public customsheetpaymentinfo builder setpaymentcardbrand @nonnull spaysdk brand cardbrand api to set the card brand for payment transaction this api can be used with setpaymentcardlast4dpan string or setpaymentcardlast4fpan string api method to designate specific card for the transaction parameters cardbrand - card brand returns customsheetpaymentinfo builder since api level 1 7 see also spaysdk brand setpaymentshippingmethod @nonnull public customsheetpaymentinfo builder setpaymentshippingmethod string shippingmethod api to set the shipping method for payment transaction parameters shippingmethod - shipping method returns customsheetpaymentinfo builder since api level 1 7 build @nonnull public customsheetpaymentinfo build api to build customsheetpaymentinfo object returns customsheetpaymentinfo object since api level 1 3 samsung electronics samsung pay sdk 2 22 00 - nov 19 2024
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 payment class customsheetpaymentinfo java lang object com samsung android sdk samsungpay v2 payment customsheetpaymentinfo all implemented interfaces android os parcelable public class customsheetpaymentinfo extends object implements android os parcelable this class provides apis to fetch payment information details with custom payment sheet information that is, transaction details set by the merchant app since api level 1 3 see also paymentmanager startinapppaywithcustomsheet customsheetpaymentinfo, paymentmanager customsheettransactioninfolistener nested class summary nested classes modifier and type class description static class customsheetpaymentinfo address this class provides apis to create address parcel object static enum customsheetpaymentinfo addressinpaymentsheet this enumeration provides types of address ui on the payment sheet, based on merchant requirement static class customsheetpaymentinfo builder this is builder class for constructing customsheetpaymentinfo object nested classes/interfaces inherited from interface android os parcelable android os parcelable classloadercreator<t extends object>, android os parcelable creator<t extends object> field summary fields inherited from interface android os parcelable contents_file_descriptor, parcelable_write_return_value method summary all methodsinstance methodsconcrete methods modifier and type method description customsheetpaymentinfo addressinpaymentsheet getaddressinpaymentsheet api to return the address display option on the payment sheet list<spaysdk brand> getallowedcardbrands api to return the brand of cards supported by merchant cardinfo getcardinfo api to return the selected card information in samsung pay customsheet getcustomsheet api to return customsheet android os bundle getextrapaymentinfo api to return the configured extra paymentinfo boolean getiscardholdernamerequired api to return whether card holder's name should be displayed on the card list on the payment sheet boolean getisrecurring api to return whether the payment is recurring or not string getmerchantcountrycode api to return the country code, where merchant is operating string getmerchantid api to return the merchant reference id string getmerchantname api to return the merchant name string getordernumber api to return the order number for transaction spaysdk brand getpaymentcardbrand api to return the card brand which was used in the current transaction partner can get this information if needed string getpaymentcardlast4dpan api to return the last 4 digits of dpan which was used in the current transaction partner can get this information if needed string getpaymentcardlast4fpan api to return the last 4 digits of fpan which was used in the current transaction partner can get this information if needed string getpaymentcurrencycode api to return the iso currency code which was used in the current transaction partner can get this information if needed customsheetpaymentinfo address getpaymentshippingaddress api to return the shipping/delivery address which was used in the current transaction partner can get this information if needed string getpaymentshippingmethod api to return the shipping method which was used in the current transaction partner can get this information if needed string getversion api to return the version name of the samsung pay package methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait method details getversion public string getversion api to return the version name of the samsung pay package returns sdk version name since api level 1 3 getmerchantid public string getmerchantid api to return the merchant reference id returns merchant reference id which can be used for merchant's own purpose for example, if merchant uses a payment gateway which requires payment gateway user id, then merchantid field can be set with a payment gateway user id since api level 1 3 getmerchantname public string getmerchantname api to return the merchant name returns merchant name since api level 1 3 getordernumber public string getordernumber api to return the order number for transaction returns order number which is sent by merchant for records since api level 1 3 getaddressinpaymentsheet public customsheetpaymentinfo addressinpaymentsheet getaddressinpaymentsheet api to return the address display option on the payment sheet returns one of the following values to indicate if the address needs to be displayed on the payment sheet or not customsheetpaymentinfo addressinpaymentsheet need_billing_and_shipping customsheetpaymentinfo addressinpaymentsheet need_billing_send_shipping customsheetpaymentinfo addressinpaymentsheet need_billing_spay customsheetpaymentinfo addressinpaymentsheet need_shipping_spay customsheetpaymentinfo addressinpaymentsheet send_shipping customsheetpaymentinfo addressinpaymentsheet do_not_show since api level 1 3 getallowedcardbrands public list<spaysdk brand> getallowedcardbrands api to return the brand of cards supported by merchant returns list of card brands supported since api level 1 3 getcardinfo public cardinfo getcardinfo api to return the selected card information in samsung pay returns cardinfo object since api level 1 3 getiscardholdernamerequired public boolean getiscardholdernamerequired api to return whether card holder's name should be displayed on the card list on the payment sheet returns true, if card holder's name is to be displayed on the payment sheet else, returns false since api level 1 3 getisrecurring public boolean getisrecurring api to return whether the payment is recurring or not returns true, if payment is recurring else, returns false since api level 1 3 getmerchantcountrycode public string getmerchantcountrycode api to return the country code, where merchant is operating returns country code for region where merchant is operating since api level 1 3 getextrapaymentinfo public android os bundle getextrapaymentinfo api to return the configured extra paymentinfo returns extra paymentinfo configured by merchant app since api level 1 3 getcustomsheet public customsheet getcustomsheet api to return customsheet returns customsheet configured by merchant app since api level 1 3 getpaymentcardlast4dpan public string getpaymentcardlast4dpan api to return the last 4 digits of dpan which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns the last 4 digits of dpan which was used in the current transaction since api level 1 7 getpaymentcardlast4fpan public string getpaymentcardlast4fpan api to return the last 4 digits of fpan which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns the last 4 digits of fpan which was used in the current transaction since api level 1 7 getpaymentcardbrand @nonnull public spaysdk brand getpaymentcardbrand api to return the card brand which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns card brand which was used in the current transaction since api level 1 7 see also spaysdk brand getpaymentcurrencycode public string getpaymentcurrencycode api to return the iso currency code which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns currency code which was used in the current transaction since api level 1 7 getpaymentshippingaddress public customsheetpaymentinfo address getpaymentshippingaddress api to return the shipping/delivery address which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns shipping address which was used in the current transaction since api level 1 7 see also customsheetpaymentinfo address getpaymentshippingmethod public string getpaymentshippingmethod api to return the shipping method which was used in the current transaction partner can get this information if needed they can use this for their own purpose this api method can be used in paymentmanager customsheettransactioninfolistener onsuccess customsheetpaymentinfo, string, bundle callback only this api is available only with us samsung pay app returns shipping method which was used in the current transaction since api level 1 7 samsung electronics samsung pay sdk 2 22 00 - nov 19 2024
Develop Samsung Wallet
docstatistics performance monitoring the samsung wallet service is monitored to get an effective measure of the wallet performance overview wallet card total number of wallet cards registered in the portal wallet card type total number of wallet card types registered in the portal wallet card template total number of templates registered in the portal recent trends provides key indicators and trend charts for the selected period you can change the period and wallet card type being reviewed item description registered registration by wallet card category impressions count when the coupon or banner is displayed on each screen page click count of click on a specific link to the number of total users who view a coupon or banner click through rate percentage of clicks against impressions in the coupon or banner[ctr % = clicks/impressions] stats of wallet cards provides detailed statistical information for the selected wallet card you can change the period, template, and wallet card type you can check detailed information and charts for each indicator item description registered registration by wallet card category number of registrations by wallet card category and registrations by template number of registrations by template , registered number of registrations for the specified wallet card category/template , registration by partner number of registrations by partner active device number of device registering cards in the wallet max number of unique device ids dmid the max number means the maximum value during the statistical period - the hourly graph shows the maximum time's value - the daily graph shows the maximum date's value top 10 of all templates statistics on top 10 templates based on number of registrations or clicks & ctr add to wallet - impressions number of impressions counts for 'add to wallet' button add to wallet - clicks number of clicks for 'add to wallet' button add to wallet – click through rate ratio of clicks against impressions for 'add to wallet' button[ctr % = clicks/impressions] wallet cards - impressions number of exposures of registered content wallet cards – clicks number of clicks on registered content wallet cards – click through rate click through rate of registered content age & gender age & gender statistics for impression/click/ctr data by wallet card / wallet category registered by end user push notification – impressions number of exposures of push notification content push notification – clicks number of clicks of push notification content
Develop Samsung Wallet
docwallet portal on-boarding information please review the attached partner on-boarding guide for the samsung wallet portal the rp partner needs registration information on the wallet portal wallet portal currently offers 'add to wallet' & ‘verify with wallet’ functionality to rp partners please proceed with the registration by referring to the url of the developer site below connect to partner portal the wallet partners portal access is via url below connect to the wallet partners portal partner onboarding partner on-boarding details are accessed via url below partner onboarding manage wallet cards to use the online rp function, you need to create a card as a relying party type refer to the manage wallet cards overall managing process the following image illustrates the process of managing samsung wallet cards create wallet cards draft status partners can create and manage their wallet cards with this step-by-step guide manage wallet cards partners can manage all registered wallet cards partners can edit wallet cards and check their status general information the general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the samsung wallet item description testing mode all data generated during testing mode is periodically deleted be sure to turn off the 'testing mode' setting after the test is over wallet card name representative title of the wallet card wallet card id unique wallet card domain name automatically generated partner app package name partner app package name wallet card template pre-defined partner’s wallet card template type > sub type > design type wallet card custom setting type authentication issuer set the authentication issuer for the relying party service to be provided as this wallet card please select authentication issuers from the identity provider groups only authentication issuers with the same “service location” as the relying party service are displayed ※ the identity provider of the “authentication issuer”is supported depending on the "service location" set partner rp get request data url through which a partner receives a card data inquiry api callin case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/key ※ the attribute could be activated with the approval of a manager partner rp send authentication data url through which a partner receives a card data inquiry api callin case of web2app method, the partner should provide this api /rp/v1 0/{cardid}/{refid}/auth ※ the attribute could be activated with the approval of a manager samsung server ips samsung wallet server ips which need to be allowed at the partner’s firewall separately described for inbound and outbound calls service location select a regional limit for the wallet card if there was no selected location, the wallet card is shown in all locations if the specified location was selected, the wallet card is shown only in the selected location users can 'verify with samsung wallet' only in service locations where the wallet service is provided ※ the identity provider of the “authentication issuer” is supported depending on the "service location" set main headquarters location check to set it as a 'main location' as the company's main service country head office for creating and proceeding with wallet cards, notification e-mails such as wallet card approval requests are sent only to the selected main location wallet card data save in server set whether to store wallet card data in the server to protect personal information if the card has sensitive information, you can contact the developer support team not to save it description description of the wallet card select template partners can choose from various types of wallet card templates optimized for partners such as boarding pass, ticket, coupon, and digital id ※ for rp partners select "relying party type > other sub type" to set the relying party wallet card partners can select the type of wallet card needed to register from the 'select wallet card template' pop-up first, select the wallet card type and then select the wallet card sub type to select one of the templates belonging to it wallet card custom setting you must set the attributes of the "wallet card custom setting" according to the wallet card ttype you selected ※ for rp partners the "authentication issuer" attribute is a unique property of the relying party card the identity provider of the authentication issuer is supported depending on the "service location" set e g if service location is in the us, the authentication issuer field only supports an identity provider belonging to the us when the parent hierarchy value is checked, its children values created later are automatically checked in the united states, the authentication issuer is the state government, and the driver's license can be understood as an mdl mobile driver's license view wallet card partners can view all the registered information, edit and delete the wallet card launch wallet cards verifying status partners can launch and activate cards you can activate a card by clicking the launch button once a card is launched, the button text changes to 'launched' the activation cannot be canceled when a card is launched, its status changes to 'verifying', and then to ‘active’ after administrator approval launch wallet cards rejected status if the wallet card is rejected after launching, partners can modify and re-launch the administrator registers the reason for rejection when rejecting a launched wallet card partners will receive an email from the system, including the reason for rejection partners can apply for launching again by checking the reason for rejection and modifying the wallet card information testing mode partners can test a card internally to make sure everything works before officially release to the users by default, the ‘testing mode’ option is enabled all data generated in testing mode is periodically deleted card exposure is not affected even when the testing mode is enabled be sure to turn off the testing mode after the test is over testing mode on → testing mode off admin approval active status all launched cards are activated after the administrator's approval when a card is launched, its status changes to 'verifying' and then to ‘active’ after administrator approval when the card is activated, it becomes visible to the user verify with samsung wallet integration to integrate the wallet, you need to run the ‘verify with samsung wallet’ script into your system the verify with samsung wallet script is available for both web and android platforms each system has a different composition to implement the verify with samsung wallet button, follow the steps below in order create tokenized card data cdata card data is the actual content data of wallet card and it has several format based on card type please refer to generate_cdata sample code for detail copy the sample verify with samsung wallet script from partner portal’s wallet card page and replace cdata with the data token created above apply the script to your system please see web_integration sample code and app_integration sample code for detail below are ‘verify with samsung wallet’ script guide in partner portal to integrate the ‘verify with samsung wallet’ you may need some base data you can find this base data and other necessary information on the partner portal and the wallet api spec you can also add image beacon in the script for tracking effect analysis
Develop Samsung Pay
docinitiate in-app payment merchant applications can use apis to fetch payment information details with custom payment sheet the following functionalities are ready to perform a variety of payment operations checking registered/enrolled card information creating a transaction request requesting payment with a custom payment sheet 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 to query the card brand, use the requestcardinfo api method of the samsungpaysdkflutter class 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 onresult and onfailure events the following snippet shows how to retrieve the list of supported card brands from samsung wallet samsungpaysdkflutterplugin requestcardinfo cardinfolistener {onresult paymentcardinfo showcardlist paymentcardinfo ; }, onfailure errorcode, bundle { showerror errorcode, bundle ; } ; creating a transaction request upon successful initialization of the samsungpaysdkflutter class, the merchant app needs to create a transaction request with payment information using the custom payment sheet to initiate a payment transaction with samsung wallet’s custom payment sheet, your merchant app must populate the following mandatory fields in customsheetpaymentinfo merchant name - as it will appear in samsung wallet’s payment sheet, as well as the user's card account statement customsheet - is called when the user changes card on the custom payment sheet in samsung wallet 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 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 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 string? merchantid; string merchantname; string? ordernumber; addressinpaymentsheet? addressinpaymentsheet; list<brand>? allowedcardbrand; paymentcardinfo? cardinfo; bool? iscardholdernamerequired; bool? isrecurring; string? merchantcountrycode; customsheet customsheet; map<string,dynamic>? extrapaymentinfo; your merchant app sends this customsheetpaymentinfo to samsung wallet via the applicable samsung pay sdk flutter plugin 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 the following example demonstrates how to populate customsheet in the customsheetpaymentinfo class list<brand> brandlist = []; brandlist add brand visa ; brandlist add brand mastercard ; brandlist add brand americanexpress ; customsheetpaymentinfo customsheetpaymentinfo= customsheetpaymentinfo merchantname "merchantname", customsheet customsheet ; customsheetpaymentinfo setmerchantid "123456" ; customsheetpaymentinfo setmerchantname "sample merchant" ; customsheetpaymentinfo setaddressinpaymentsheet addressinpaymentsheet need_billing_send_shipping ; customsheetpaymentinfo setcardholdernameenabled true ; customsheetpaymentinfo setrecrringenabled false ; customsheetpaymentinfo setcustomsheet customsheet ; customsheetpaymentinfo allowedcardbrand = brandlist; return customsheetpaymentinfo; requesting payment with a custom payment sheet the startinapppaywithcustomsheet method of the samsungpaysdkflutter 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 persist for 5 minutes after the api is called if the time limit expires, the transaction fails updatesheet - updates the custom payment sheet if any values on the sheet are changed 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 wallet 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 samsungpaysdkflutter class class customsheettransactioninfolistener{ function paymentcardinfo paymentcardinfo, customsheet customsheet oncardinfoupdated; function customsheetpaymentinfo customsheetpaymentinfo, string paymentcredential, map<string, dynamic>? extrapaymentdata onsuccess; function string errorcode, map<string, dynamic> bundle onfail; customsheettransactioninfolistener {required this oncardinfoupdated, required this onsuccess, required this onfail} ; } void oncardinfoupdated cardinfo selectedcardinfo, customsheet customsheet { amountboxcontrol amountboxcontrol = customsheet getsheetcontrol amount_control_id as amountboxcontrol; amountboxcontrol updatevalue product_item_id, 1000 ; amountboxcontrol updatevalue product_tax_id, 50 ; amountboxcontrol updatevalue product_shipping_id, 10 ; amountboxcontrol updatevalue product_fuel_id, 0, "pending" ; amountboxcontrol setamounttotal 1060, amountconstants format_total_price_only ; customsheet updatecontrol amountboxcontrol ; } } void startinapppaywithcustomsheet customsheetpaymentinfo customsheetpaymentinfo,customsheettransactioninfolistener? customsheettransactioninfolistener { try{ methodchannelsamsungpaysdkflutter? startinapppaywithcustomsheet customsheetpaymentinfo, customsheettransactioninfolistener ; }on platformexception catch e { print e ; } } override fun onsuccess response customsheetpaymentinfo, paymentcredential string, extrapaymentdata bundle {} override fun onfailure errorcode int, errordata bundle? {}
Develop Samsung Pay
apioverview package class tree index help package com samsung android sdk samsungpay v2 payment class cardinfo builder java lang object com samsung android sdk samsungpay v2 payment cardinfo builder enclosing class cardinfo public static class cardinfo builder extends object this is builder class for constructing cardinfo object which is passed to samsung pay from merchant since api level 1 1 see also paymentmanager startsimplepay cardinfo, statuslistener constructor summary constructors constructor description builder method summary all methodsinstance methodsconcrete methods modifier and type method description cardinfo build builds the cardinfo object cardinfo builder setcardid string cardid api to set unique identification of a card in samsung pay cardinfo builder setcardmetadata android os bundle cardmetadata api to set extra card information if any related to the card methods inherited from class java lang object equals, getclass, hashcode, notify, notifyall, tostring, wait, wait, wait constructor details builder public builder method details setcardid @nonnull public cardinfo builder setcardid string cardid api to set unique identification of a card in samsung pay parameters cardid - unique id to refer a card in samsung pay returns cardinfo details builder since api level 1 1 see also paymentmanager startsimplepay cardinfo, statuslistener setcardmetadata @nonnull public cardinfo builder setcardmetadata android os bundle cardmetadata api to set extra card information if any related to the card returns extra card information since api level 1 1 see also paymentmanager startsimplepay cardinfo, statuslistener build @nonnull public cardinfo build builds the cardinfo object returns cardinfo object since api level 1 1 samsung electronics samsung pay sdk 2 22 00 - nov 19 2024
Develop Samsung Pay
docapi reference this page describes the data structures used in the samsung pay web checkout api integration paymentmethods the paymentmethods object defines the payment methods that the merchant supports key type required description version string required samsung pay api versionthe supported value is 2 serviceid string required merchant id that is assigned after onboarding protocol string required payment protocol typethe supported value is protocol_3ds allowedbrands list<string> required list of supported card brandsthe possible values are visamastercardamexdiscoverelo tbd mada tbd cb tbd isrecurring boolean optional value if payment is recurringthe default value is false iscpfcardrequired boolean optional value if payment must be including cpfthe default value is false merchantchoicebrands object optional data structure containing configuration information for a co-badged card merchantchoicebrands type string required co-badged card display option for the payment sheetthe possible values are mandatory = only the brand defined in merchantchoicebrands brands is enabledpreference = the brand defined in merchantchoicebrands brands is selected by default but the user can change it merchantchoicebrands brands list<string> required list of supported brands for the co-badged cardthe possible values are madacb extrapaymentinfo object optional data structure containing additional supported features extrapaymentinfo id string required feature id for the additional featurethe possible values are combocard = combo carddsrp = digital secure remote payment extrapaymentinfo type string optional feature type, if the value of extrapaymentinfo id is dsrpthe possible values are ucaf = universal cardholder authentication fieldicc = integrated circuit cardthe default value is ucaf table 1 "paymentmethods" data structure elements transactiondetail the transactiondetail object contains the transaction information for the user's purchase key type required description ordernumber string required order number of the transactionthe following characters are allowed [a-z][a-z][0-9,-] merchant object required data structure containing merchant information merchant name string required merchant name merchant url string required merchant domain urlthe maximum length is 100 characters merchant id string optional merchant referencethis is the id value registered with your pg required for gateway token mode the maximum length is 45 characters it should be set in the request parameter for mada token if a merchant request mada token, this field is mandatory as this field should be included in the payload for mada token, there is a 15-character length limit merchant countrycode string required merchant country codeiso-3166-1 alpha-2 amount object required data structure containing the payment amount amount option string required display format for the total amount on the payment sheetthe possible values are format_total_estimated_amount = display "total estimated amount " and total amountformat_total_price_only = display the total amount only amount currency string required currency codethe maximum length is 3 characters amount total string required total payment amount in the currency specified by amount currencythe amount must be an integer for example, 300 or in a format valid for the currency such as 2 decimal places after a separator, for example, 300 50 type string optional transaction typethis value is specifically supported for mada tokens and will not apply to other token types the possible values are purchasepreauthorizationthe default value is purchase table 2 "transactiondetail" data structure elements paymentcredential the paymentcredential object contains the payment credential information generated by the samsung wallet application on the user's mobile device key type required description card_brand string required brand of the payment card card_last4digit object required last 4 digits of the card number 3ds object required data structure containing the generated 3ds data 3ds type string optional 3ds typethe value is s for samsung pay 3ds version string required 3ds versionthe value for the current version is 100 3ds data string required encrypted payment credential data recurring_payment boolean required value if credential is enabled for recurringthe default value is false cpf string optional brazilian cpfthis value is jwe encrypted with registered csr encrypted value included below information { "name" "joao", "number" "12345678900"} table 3 "paymentcredential" data structure elements paymentresult the paymentresult object contains the payment result information during transaction processing, and after the payment is processed with pg network key type required description status string required payment statusthe possible values are charged = payment was charge successfullycanceled = payment was canceled by either user, merchant, or acquirerrejected = payment was rejected by acquirererred = an error occurred during the payment process provider string optional payment provider pg name table 4 "paymentresult data structure elements
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.