In-App (Online)
initiate in-app payment 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 reflected in the diagram above are the following operations check the ready status of samsung pay start the payment manager to establish the service binding and verify the merchant app get payment card information and the payment amount, including updates get/update the user’s billing and shipping addresses, including an updated payment amount if shipping charges will be incurred authenticate the user submit payment information to pg verify transaction success or failure 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 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 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 } } creating a transaction request upon successful initialization of the samsungpay class, the merchant app needs to create a transaction request with payment information noteas 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 request mada token, this filed 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 noteif 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 } 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 persist 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 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, cybs 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", "cryptogram" "ak+zkbpmcorcabcd3agraoacfa==" } 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