Implementing the Purchase Process
reservation status the subscription plan change reservation status api "subscription/plan-change/reserve-status" retrieves the status of any requested subscription changes for a list of subscriptions or customers to call the subscription plan change reservation status api // generate checkvalue var reqparams = detailobj appid; for let subscriptionid of detailobj subscriptionidlist { reqparams += subscriptionid; } for let customid of detailobj customidlist { reqparams += customid; } reqparams += detailobj timestamp; /* required parameters [subscription/plan-change/reserve-status] request appid + subscriptionidlist[0] + + subscriptionidlist[n] + customidlist[0] + + customidlist[n] + timestamp [checkvalue] required */ var hash = cryptojs hmacsha256 reqparams, securitykey ; var checkvalue = cryptojs enc base64 stringify hash ; detailobj checkvalue = checkvalue; var paymentdetails = json stringify detailobj ; // call api $ ajax { url strurldpi + "/subscription/plan-change/reservation-status", type "post", contenttype "application/json;charset=utf-8", datatype "json", data paymentdetails, timeout 10000, success function res { // for implementation details, see the samsung checkout sample application console log "success " + json stringify res ; }, error function jqxhr, ajaxoptions, thrownerror, request, error { console log "[error] thrownerror "+thrownerror+";error "+error+";[message] "+jqxhr responsetext ; }, complete function { console log "complete" ; }, failure function { console log "failure" ; } } ; the subscription plan change reservation status api request has the following headers header mandatory description "content-type" true media type of the message "application/json;charset=utf-8""application/x-www-form-urlencoded"for the "x-www-form-urlencoded" data type, the request body must not contain any spaces ' ' "accept" media type accepted by the client "application/json;charset=utf-8" table 22 subscription plan change reservation status api request headers the subscription plan change reservation status api request and response data are in json format subscription plan change reservation status api request parameters parameter type mandatory description "appid" string true application id "subscriptionidlist" string[] false list of subscription ids at least one of 'subscriptionidlist' or 'customidlist' must be provided "customidlist" list of unique customer ids at least one of 'subscriptionidlist' or 'customidlist' must be provided "timestamp" string true timestamp format "yyyy-mm-dd hh mm ss" the time is in utc time and must be within 10 minutes from the current time "checkvalue" security check value required parameters "appid" + "subscriptionidlist[0]" + … + "subscriptionidlist[n]" + "customidlist[0]" + … + "customidlist[n]" + "timestamp" table 23 subscription plan change reservation status api request parameters subscription plan change reservation status api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" result message "success"other message corresponding to the "cpstatus" error code "reservedsubscriptions" json[] false list of subscriptions with pending changes "subscription id" string true subscription id "customid" unique customer id "afterproductid" product id of the new product "afterproductname" name of the new product "applydate" estimated date when the new product is applied format "yyyy-mm-dd" table 24 subscription plan change reservation status api response parameters cancel subscription plan change reservations the subscription plan change cancel api "subscription/plan-change/cancel" cancels a requested subscription product change to call the subscription plan change cancel api // generate checkvalue var reqparams = detailobj appid + detailobj subscriptionid + detailobj timestamp; /* required parameters [subscription/plan-change/cancel] request appid + subscriptionid + timestamp [checkvalue] required */ var hash = cryptojs hmacsha256 reqparams, securitykey ; var checkvalue = cryptojs enc base64 stringify hash ; detailobj checkvalue = checkvalue; var paymentdetails = json stringify detailobj ; // call api $ ajax { url strurldpi + "/subscription/plan-change/cancel", type "post", contenttype "application/json;charset=utf-8", datatype "json", data paymentdetails, timeout 10000, success function res { // for implementation details, see the samsung checkout sample application console log "success " + json stringify res ; }, error function jqxhr, ajaxoptions, thrownerror, request, error { console log "[error] thrownerror "+thrownerror+";error "+error+";[message] "+jqxhr responsetext ; }, complete function { console log "complete" ; }, failure function { console log "failure" ; } } ; the subscription plan change cancel api request has the following headers header mandatory description "content-type" true media type of the message "application/json;charset=utf-8""application/x-www-form-urlencoded"for the "x-www-form-urlencoded" data type, the request body must not contain any spaces ' ' "accept" media type accepted by the client "application/json;charset=utf-8" table 25 subscription plan change cancel api request headers the subscription plan change cancel api request and response data are in json format subscription plan change cancel api request parameters parameter type mandatory description "appid" string true application id "subscriptionid" subscription id "timestamp" timestamp format "yyyy-mm-dd hh mm ss" the time is in utc time and must be within 10 minutes from the current time "checkvalue" security check value required parameters "appid" + "subscriptionid" + "timestamp" "maillang" false iso 639-1 language code in lowercase for the language of messages sent to the user for unsupported languages, use "en" the default value is "en" table 26 subscription plan change cancel api request parameters subscription plan change cancel api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" result message "success"other message corresponding to the "cpstatus" error code table 27 subscription plan change cancel api response parameters canceling subscriptions you can only use the subscription cancel api "subscription/cancel" with subscription products, to request canceling the subscription the dpi server returns the subscription expiry time and the current subscription status to call the subscription cancel api /* required parameters [subscription/cancel] request */ var detailobj = new object ; detailobj appid = appid; // your application id detailobj invoiceid = uncanceleditems [key] invoiceid; // issued by "invoice/list" detailobj customid = uniquecustomid; // same value as ordercustomid parameter for buyitem detailobj countrycode = countrycode; // tv country code var paymentdetails = json stringify detailobj ; // call api $ ajax { url strurldpi + "/subscription/cancel", type "post", contenttype "application/json;charset=utf-8", datatype "json", data paymentdetails, timeout 10000, success function res { // for implementation details, see the samsung checkout sample application console log "success " + json stringify res ; }, error function jqxhr, ajaxoptions, thrownerror, request, error { console log "[error] thrownerror "+thrownerror+";error "+error+";[message] "+jqxhr responsetext ; }, complete function { console log "complete" ; }, failure function { console log "failure" ; } } ; the subscription cancel api request has the following headers header mandatory description "content-type" true media type of the message "application/json;charset=utf-8""application/x-www-form-urlencoded"for the "x-www-form-urlencoded" data type, the request body must not contain any spaces ' ' "accept" media type accepted by the client "application/json;charset=utf-8" table 28 subscription cancel api request headers the subscription cancel api request and response data are in json format subscription cancel api request parameters parameter type mandatory description "appid" string true application id "invoiceid" invoice id "customid" unique customer id same value as the "ordercustomid" parameter for the buyitem method "countrycode" country code the country code must be retrieved from the tv table 29 subscription cancel api request parameters subscription cancel api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" false result message "success"other message corresponding to the "cpstatus" error code "invoiceid" true invoice id "subscanceltime" false time subscription canceled, in 14-digit utc time "subsstatus" subscription status "02" canceled by buyer table 30 subscription cancel api response parameters checking billing service availability the billing service available country check api "/country/checkavailability" retrieves billing service availability information for the specified country codes to call the billing service available country check api /* required parameters [country/checkavailability] request appid + countrycodes + checkvalue */ var detailobj = new object ; detailobj appid = appid; // your application id detailobj countrycodes = countrycodes; // tv country codes to be checked you can check multiple codes var reqparams = detailobj appid + detailobj countrycodes; var hash = cryptojs hmacsha256 reqparams, securitykey ; var checkvalue = cryptojs enc base64 stringify hash ; detailobj checkvalue = checkvalue; var countrycheckdetails = json stringify detailobj ; // call api $ ajax { url strurldpi + "/country/checkavailability", type "post", contenttype "application/json;charset=utf-8", datatype "json", data countrycheckdetails, timeout 10000, success function res { // for implementation details, see the samsung checkout sample application console log "success " + json stringify res ; }, error function jqxhr, ajaxoptions, thrownerror, request, error { console log "[error] thrownerror "+thrownerror+";error "+error+";[message] "+jqxhr responsetext ; }, complete function { console log "complete" ; }, failure function { console log "failure" ; } } ; the billing service available country check api request has the following headers header mandatory description "content-type" true media type of the message "application/json;charset=utf-8" "accept" media type accepted by the client "application/json" table 31 billing service available country check api request headers the billing service available country check api request and response data are in json format billing service available country check api request parameters parameter type mandatory description "appid" string true application id "countrycodes" country codes in uppercase for the regions to be checked you can check multiple regions with a comma-separated list, for example, "de,us,kr" "checkvalue" security check value required parameters "appid" + "countrycodes" for multiple country codes, remove the commas for example, if "countrycodes" is "de,us,kr", use "deuskr" to generate the check value table 32 billing service available country check api request parameters billing service available country check api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" result message "success"other message corresponding to the "cpstatus" error code "countries" json false country information "countrycode" string true country code "isbillingsupported" boolean billing service support status "true" billing service supported"false" billing service not supported table 33 billing service available country check api response parameters billing api to implement the samsung checkout functionality, use the billing api when the user wants to make a purchase, authenticate the user and show the common purchase gui with the buyitem method importantwhen the buyitem method is called, the common purchase gui is shown in the application automatically do not change the purchase gui appearance until the purchase transaction is complete and the application receives the response you can customize the product image in samsung checkout by providing the uri to an image on your own content server default image product image table 34 display your own product image to implement samsung checkout var detailobj = new object ; detailobj orderitemid = productslist itemdetails[selecteditem] itemid; // issued by "cont/list" detailobj ordertitle = productslist itemdetails[selecteditem] itemtitle; // issued by "cont/list" detailobj ordertotal = productslist itemdetails[selecteditem] price tostring ; // change data type to string detailobj ordercurrencyid = productslist itemdetails[selecteditem] currencyid; //detailobj orderid = "your_order_id"; // this value is optional var uniquecustomid = "123"; // unique id for this user "123" is an example value it can be an id managed by your service detailobj ordercustomid = uniquecustomid; // same value as "customid" parameter for "invoice/list" var paymentdetails = json stringify detailobj ; webapis billing buyitem appid, servertype, paymentdetails, function data { // for implemention details, see the samsung checkout sample application console log "[billing buyitem] pay_result [" + data payresult + "], pay_detail [" + data paydetail + "]" ; }, function error { console log "[billing buyitem] status [" + error code + "] errorname [" + error name + "] errormessage [" + error message + "]" ; } ; the buyitem method request and response data are in json format buyitem method request parameters parameter type mandatory maximum length characters description "appid" string true 30 application id provided by the samsung apps tv seller office "paymentserver" - possible values "prd" operating zone "paymentdetails" json payment details "orderitemid" string true 30 purchase item id, for example, "dp123400000000" "itemid" issued by the products list api for dynamic products, use this value as "productid" for the verify dynamic product information api "ordertitle" 100 purchase item title "itemtitle" issued by the products list api for dynamic products, use a customized value "ordertotal" 20 total purchase price "price" issued by the products list api when converting the number to string type, pay attention to the unit separators for dynamic products, use a customized value and use it as "productprice" for the verify dynamic product information api "ordercurrencyid" 10 purchase currency unit "currencyid" issued by the products list api "orderid" false 50 management id for purchases managed by third-party applications "ordercustomid" true 100 unique customer id "orderitempath" false - item image uri the image must be in jpeg, jpg, or png format "dynmcproductid" true for dynamic products only 100 unique id for the dynamic product from a third-party application use this value as "dynmcproductid" for the verify dynamic product information api "dynmcproductinfo" false dynamic product item type, such as rental or permanent purchase for dynamic products only "dynmcsharecategory" 20 share category for dynamic products only "dynmctaxcategory" 30 tax category for dynamic products only "stltappid" settlement application id for samsung internal use only do not use table 35 buyitem request parameters buyitem method response parameters parameter type mandatory description "payresult" string true possible values "success""failed""cancel" canceled by the user "paydetail" json false payment details "invoiceid" string false purchased invoice id, for example, "do1904us000007153" a value is only returned when "payresult" is "success" table 36 buyitem response parameters note dynamic products are also supported by samsung checkout for more information on offering dynamic products in your application, contact a samsung representative by going to "samsung apps tv seller office > support" and creating a "1 1 q&a" support ticket verifying dynamic product information the verify dynamic product information api "cp/verify" is only available when the product type is dynamic product the api checks the dynamic product information between dpi server and cp cms the dpi server calls this api when "verification" is selected in the dpi portal api url operating zone prd the "verify uri" entered in the dpi portal for the operating zone post https //xxxxxxxx com/xxxx/cp/verify http/1 1 accept-encoding gzip,deflate content-type application/json;charset=utf-8 accept application/json;charset=utf-8 content-length 391 host xxxx com connection keep-alive user-agent apache-httpclient/4 1 1 java 1 5 { "countrycode" "es", "ordertime" "20181017213438", "checkvalue" "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "productdetail" { "appid" "3201505000000", "productid" "rent_prod", "productprice" "1 58", "productcurrencycode" "usd", "ordercustomid" "xxxxxxxx", "dynmcproductid" "rent_option_4537", "dynmcproductinfo" "rent_option_4537" } } verify dynamic product information api request parameters parameter type mandatory maximum length characters description "countrycode" string true 10 country code in uppercase "ordertime" 20 order time utc-0 20140314175900 "checkvalue" 200 security check value required parameters "appid" + "dynmcproductid" + "productid" + "productprice" + "productcurrencycode" "productdetail" json - product details "appid" string true 30 application id same value as the "appid" parameter for the buyitem method "productid" purchase item id same value as the "orderitemid" parameter for the buyitem method "productprice" 10 purchase price unit price same value as the "ordertotal" parameter for the buyitem method "productcurrencycode" currency code same value as the "ordercurrencyid" parameter for the buyitem method "ordercustomid" false 100 unique customer id same value as the "ordercustomid" parameter for the buyitem method "dynmcproductid" true unique id or string to track the product from the third-party application same value as the "dynmcproductid" parameter for the buyitem method "dynmcproductinfo" false dynamic product information same value as the "dynmcproductinfo" parameter for the buyitem method "dynmcsharecategory" 20 share category for the dynamic product same value as the "dynmcsharecategory" parameter for the buyitem method "dynmctaxcategory" 30 tax category for the dynamic product same value as the "dynmctaxcategory" parameter for the buyitem method table 37 verify dynamic product information api request parameters verify dynamic product information api response parameters parameter type mandatory length description "status" string true 9 result code "100000" success"errorcode" failurefor error code details, see the embedded error code file "result" 100 result message to be displayed "success" or other short error message "resultlongmesg" false 200 detailed error message when debug mode is active table 38 verify dynamic product information api response parameters dpi result codes the following table lists result codes and messages that are returned by the dpi service result code result message description 100000 "success" additional messages "hasnext true" product list or purchase history has further pages"eof" last page of the product list or purchase history"your invoice not found" no purchase history exists 400111 "appid not correct" requested application id does not exist table 39 dpi result codes and messages for explanations of additional dpi result codes, at the dpi portal, go to "help > error code" country and currency codes the following table lists countries with their corresponding country code, currency, and currency code country name country code iso3166-1 alpha-2 currency currency code iso 4217 aland islands ax euro eur albania al united states dollar usd algeria dz algerian dinar dzd argentina ar argentinian peso ars australia au australian dollar aud austria at euro eur bahrain bh bahraini dinar bhd belarus by belarusian ruble byn belgium be euro eur bolivia bo united states dollar usd bosnia and herzegovina ba united states dollar usd brazil br brazilian real brl bulgaria bg bulgarian lev bgn canada ca canadian dollar cad chile cl chilean peso clp colombia co colombian peso cop costa rica cr united states dollar usd croatia hr euro eur czechia cz czech koruna czk denmark dk danish krone dkk dominican republic do united states dollar usd ecuador ec united states dollar usd egypt eg egyptian pound egp estonia ee euro eur faroe islands fo danish krone dkk finland fi euro eur france fr euro eur germany de euro eur greece gr euro eur greenland gl danish krone dkk guatemala gt guatemalan quetzal gtq guernsey gg british pound gbp hong kong hk hong kong dollar hkd hungary hu hungarian forint huf iceland is united states dollar usd india in indian rupee inr indonesia id indonesian rupiah idr iraq iq iraqi dinar iqd ireland ie euro eur isle of man im british pound gbp israel il israeli shekel ils italy it euro eur jersey je british pound gbp jordan jo jordanian dinar jod kazakhstan kz kazakhstani tenge kzt korea, republic of kr south korean won krw kuwait kw kuwaiti dinar kwd kyrgyzstan kg united states dollar usd latvia lv euro eur lebanon lb lebanese pound lbp libya ly libya dinar lyd lithuania lt euro eur luxembourg lu euro eur malaysia my malaysian ringgit myr mexico mx mexican peso mxn moldova md united states dollar usd mongolia mn united states dollar usd montenegro me united states dollar usd morocco ma moroccan dirham mad netherlands nl euro eur new zealand nz new zealand dollar nzd north macedonia mk united states dollar usd norway no norwegian krone nok oman om omani rial omr pakistan pk united states dollar usd panama pa united states dollar usd peru pe peruvian sol pen philippines ph philippine peso php poland pl polish zloty pln portugal pt euro eur qatar qa qatari riyal qar romania ro euro eur russian federation ru russian ruble rub saudi arabia sa saudi rial sar serbia rs serbian dinar rsd singapore sg singapore dollar sgd slovakia sk euro eur slovenia si euro eur south africa za south african rand zar spain es euro eur sweden se swedish krona sek switzerland ch swiss franc chf taiwan tw new taiwan dollar twd tajikistan tj united states dollar usd thailand th thai baht thb tunisia tn tunisian dinar tnd türkiye tr turkish lira try turkmenistan tm united states dollar usd ukraine ua ukrainian hryvna uah united arab emirates ae united arab emirates dirham aed united kingdom gb british pound gbp united states us united states dollar usd uzbekistan uz united states dollar usd venezuela ve united states dollar usd vietnam vn vietnamese dong vnd yemen ye yemeni rial yer table 40 country and currency codes