Search | Samsung Developer

Implementing the Purchase Process

implementing the purchase process this topic describes how to implement a billing system for managing products, sales, and payments, by using samsung checkout in your application related info tizen tv service billing namespace tizen tv service sso namespace implementing the purchase process for web applications samsung checkout dpi portal guide samsung checkout dpi portal samples samsung checkout net application samsung checkout web application implement a billing system for in-app purchases in your application, by using samsung checkout through the dpi service apis and the purchase api and gui prerequisites to implement in-app purchases before you start implementing samsung checkout in your application, start registering your application at the samsung apps tv seller office you do not need to complete the registration with your source code at this point to be able to use the dpi portal, you need to proceed to the second step of the app registration page and set the "billing" field to "use" and the "samsung checkout on tv" field to "yes" you can save the registration at this point and return to it later when your source code is complete for more information, see the samsung checkout dpi portal guide noteto manage your product for billing, go to the samsung checkout dpi portal install the following nuget packages tizen tv tizen tv service billing tizen tv service sso to access the device and user information, and use the methods of the tizen tv service billing and tizen tv service sso namespaces, the application has to request permission by adding the following privileges to the "tizen-manifest xml" file <tizen privilege name="http //developer samsung com/privilege/sso partner"/> <tizen privilege name="http //developer samsung com/privilege/productinfo"/> <tizen privilege name="http //developer samsung com/privilege/billing"/> initialize the required variables retrieve the user id using tizen tv service sso; string uniqueid = "abc";// set an unique id that you can identify your user "abc" is a one of the example for unique custom id you can assign id managed by your service retrieve the country code using tizen tv; string country = environment smarthubconfig country; retrieve the server type using tizen tv; smarthubconfig servertype tvservertype = environment smarthubconfig server; set the service environment using tizen tv; smarthubconfig servertype tvservertype = environment smarthubconfig server; billingrequestservertype servertype; string securitykey; switch tvservertype { case smarthubconfig servertype operating servertype = billingrequestservertype prd; securitykey = "***********"; break; case smarthubconfig servertype developement servertype = billingrequestservertype dev; securitykey = "***********"; break; } dpi service apis the tizen tv service billing namespace enables you to access the apis provided by the dpi service, to manage products and sales generating check values the check value is used by the dpi service to verify purchase list and products list api requests it is a base64 hash generated by applying the hmac sha256 algorithm on a concatenated string of parameters using the dpi security key the application can also use the check value to verify that api response data from the dpi server is legitimate to ensure the data integrity of requests and responses in real time, generate and verify the check value for api requests and responses during runtime notethe dpi security key is used only by samsung smart tv applications for samsung checkout features do not expose this key you can use a key management server for greater security to generate the check value, the following 2 items are used as parameters concatenation of the required parameters for example, "12345"+"123"+"us"+"2"+"1" is concatenated to "12345123us21" the required parameters vary depending on the api dpi security key the dpi security key is issued at the dpi portal to generate the hmac sha256 hash using system; using system security cryptography; private string getcheckvalue string strmsg, string strkey { var encoding = new system text asciiencoding ; byte[] bytekey = encoding getbytes strkey ; byte[] datatohmac = encoding getbytes strmsg ; hmacsha256 hmac = new hmacsha256 bytekey ; return convert tobase64string hmac computehash datatohmac ; } requesting user purchases the purchase list api requests the list of purchased items for a specific user, usually the currently logged-in user the api response identifies whether purchased products have been applied or have been refunded notefor subscription products, the default value of the "appliedstatus" parameter is "true", but the "cancelstatus" parameter does not indicate the refund status in purchase history instead, it indicates the cancellation status for the next subscription cycle the "subsstatus" and "subsendtime" parameters detail the subscription expiration status to call the purchase list api, use the getpurchaselist method using system; using system security cryptography; using tizen tv service billing; using tizen tv service sso; using tizen tv; public void request_purchase_list { billingplugin pibilling = new billingplugin ; pibilling requestapieventhandler += new billingrequestapicallbackeventhandler requestpurchaselistcallbackevent ; string strappid = "**********"; // your application id string struniquecustomid = "abc"; // unique customer id "abc" is a one of the example for unique custom id you can assign id managed by your service string strcountrycode = environment smarthubconfig country; string stritemtype = "2"; string strsecuritykey = "**********"; // your security key issued by dpi portal int ipagenumber = 1; string strcheckvalue = getcheckvalue strappid + struniquecustomid + strcountrycode + stritemtype + ipagenumber, strsecuritykey ; bool bret = pibilling getpurchaselist strappid, struniquecustomid, strcountrycode, ipagenumber, strcheckvalue, servertype ; if bret { // api call success } else { // api call fail } } private string getcheckvalue string strmsg, string strkey { var encoding = new system text asciiencoding ; byte[] bytekey = encoding getbytes strkey ; byte[] datatohmac = encoding getbytes strmsg ; hmacsha256 hmac = new hmacsha256 bytekey ; return convert tobase64string hmac computehash datatohmac ; } private void requestpurchaselistcallbackevent object sender, billingrequestapicallbackeventargs e { // do something } the following tables describe the purchase list api parameters the response data is in json format purchase list api request parameters parameter type mandatory description "appid" string true application id "customid" unique customer idsame value as the "ordercustomid" parameter for the buyitem method "countrycode" country codethe country code must be retrieved from the tv "pagenumber" number requested page numberrange 1~neach purchase record page has up to 100 entries to receive the complete purchase record, post purchase list api requests while increasing the "pagenumber" value, until "eof" is returned in the "cpresult" parameter "checkvalue" string security check valuerequired parameters "appid" + "customid" + "countrycode" + "itemtype" + "pagenumber" "servertype" possible values "dev" staging zone"prd" operating zone table 1 purchase list api request parameters purchase list api response parameters parameter type mandatory description "cpstatus" string true result code “100000” success“errorcode” failure "cpresult" false result message "eof" last page of the purchase history"hasnext true" purchase history has further pages other message corresponding to the "cpstatus" error code "totalcount" number true total number of invoices sum of all purchase history pages, or sum of purchase history in the specified time period "checkvalue" string security check valuerequired parameters "cpstatus" + "cpresult" + "totalcount" + "invoicedetails[0] itemid" + … + "invoicedetails[totalcount] itemid" "invoicedetails" json false invoice information "seq" number true sequence numberrange 1 ~ totalcount "invoiceid" string invoice id "itemid" product id "itemtitle" product name "itemtype" number product type "1" consumable "2" non-consumable "3" limited-period "4" subscription the response "itemtype" value differs from the request "itemtype" value the response value contains more detail "ordertime" string payment time, in 14-digit utc time, for example, "20140314175900" "period" number false limited period product duration, in minutes "price" true product price, in "xxxx yy" format "ordercurrencyid" string currency code "cancelstatus" boolean cancellation status "true" sale canceled "false" sale ongoing for subscription products, indicates the cancellation status for the next subscription cycle "appliedstatus" product application status "true" applied "false" not applied for subscription products, the default value is "true" "appliedtime" string false time product applied, in 14-digit utc time "limitendtime" limited period product end time, in 14-digit utc time for limited period products only "limitendtime" = "appliedtime" + "period" "remaintime" limited period product time remaining, in secondsfor limited period products only "remaintime" = "limitendtime" – request time "subscriptioninfo" json subscription information mandatory for subscription products "subscriptionid" string true subscription id "subsstarttime" subscription start time, in 14-digit utc time "subsendtime" subscription expiry time, in 14-digit utc time "subsstatus" subscription status "00" active"01" subscription expired"02" canceled by buyer"03" canceled for payment failure"04" canceled by cp"05" canceled by admin table 2 purchase list api response parameters requesting products for sale the products list api requests product information from the dpi server when the api is in "show" status, it returns the information for the products on sale this api is generally used to generate a list of buyable products in the application to call the products list api, use the getproductslist method using system; using system security cryptography; using tizen tv service billing; using tizen tv; public void request_product_list { billingplugin pibilling = new billingplugin ; pibilling requestapieventhandler += new billingrequestapicallbackeventhandler requestproductlistcallbackevent ; string strappid = "**********"; // your application id string strcountrycode = environment smarthubconfig country; string strsecuritykey = "**********"; // your security key issued by dpi portal string strcheckvalue = getcheckvalue strappid + strcountrycode, strsecuritykey ; int ipagesize = 100; int ipagenumber = 1; bool bret = pibilling getproductslist strappid, strcountrycode, ipagesize, ipagenumber, strcheckvalue, servertype ; if bret { // api call success } else { // api call fail } } private string getcheckvalue string strmsg, string strkey { var encoding = new system text asciiencoding ; byte[] bytekey = encoding getbytes strkey ; byte[] datatohmac = encoding getbytes strmsg ; hmacsha256 hmac = new hmacsha256 bytekey ; return convert tobase64string hmac computehash datatohmac ; } private void requestproductlistcallbackevent object sender, billingrequestapicallbackeventargs e { // do something after parsing e result jobject productlistobj = jobject parse e result ; jarray jarray = jarray parse productlistobj getvalue "itemdetails" tostring ; productinfos = jarray select p => new productinfo { itemtype = string p["itemtype"], price = string p["price"], itemtitle = string p["itemtitle"], itemid = string p["itemid"], currencyid = string p["currencyid"] } tolist ; } the following tables describe the products list api parameters the response data is in json format products list api request parameters parameter type mandatory description "appid" string true application id "countrycode" country codethe country code must be retrieved from the tv "pagesize" number false requested page sizerange 1~n maximum 100 number of products retrieved per page "pagenumber" requested page numberrange 1~neach purchase record page has a number of entries equal to the "pagesize" value to receive the complete purchase record, post purchase list api requests while increasing the "pagenumber" value, until "eof" is returned in the "cpresult" parameter "checkvalue" string true security check valuerequired parameters "appid" + "countrycode" "servertype" possible values "dev" staging zone"prd" operating zone table 3 products list api request parameters products list api response parameters parameter type mandatory description "cpstatus" string true result code “100000” success“errorcode” failure "cpresult" false result message "eof" last page of the purchase history "hasnext true" purchase history has further pages other message corresponding to the "cpstatus" error code "totalcount" number true total number of invoices sum of all purchase history pages, or sum of purchase history in the specified time period "checkvalue" string security check valuerequired parameters "cpstatus" + "cpresult" + "totalcount" + "invoicedetails[0] itemid" + … + "invoicedetails[totalcount] itemid" "itemdetails" json false invoice information "seq" number true sequence numberrange 1 ~ totalcount "itemid" string product id "itemtitle" product name "itemtype" number product type "1" consumable "2" non-consumable "3" limited-period "4" subscription "period" false limited period product duration, in minutes "price" true product price, in "xxxx yy" format "currencyid" string currency code "subscriptioninfo" json false subscription information mandatory for subscription products "paymentcycleperiod" string true subscription payment period "d" days"w" weeks"m" months "paymentcyclefrq" number payment cycle frequency "paymentcycle" number of payment cycles table 4 products list api response parameters verifying purchases the verify purchase api checks whether a purchase, corresponding to the requested "invoiceid", was successful to call the verify purchase api, use the verifyinvoice method using system; using tizen tv service billing; using tizen tv service sso; using tizen tv; public void request_verify_purchase string strinvoiceid { billingplugin pibilling = new billingplugin ; pibilling requestapieventhandler += new billingrequestapicallbackeventhandler requestverifyinvoicecallbackevent ; string strappid = "**********"; // your application id struniquecustomid = "abc"; // unique customer id "abc" is a one of the example for unique custom id you can assign id managed by your service // strinvoiceid = issued by getpurchaselist string strcountrycode = environment smarthubconfig country; bool bret = pibilling verifyinvoice m_strappid, struniquecustomid, strinvoiceid, strcountrycode, servertype ; if bret { // api call success } else { // api call fail } } private void requestverifyinvoicecallbackevent object sender, billingrequestapicallbackeventargs e { // do something } the following tables describe the verify purchase api parameters the response data is in json format verify purchase api request parameters parameter type mandatory description "appid" string true application id "invoiceid" invoice id "customid" unique customer idsame value as the "ordercustomid" parameter for the buyitem method "countrycode" country codethe country code must be retrieved from the tv "servertype" possible values "dev" staging zone"prd" operating zone table 5 verify purchase api request parameters verify purchase 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 "appid" true requested application id "invoiceid" requested invoice id table 6 verify purchase api response parameters applying products the apply product api supports product management to help guarantee secure sales of your products normally, the dpi service is notified that the purchased product has been successfully applied the apply product api is used in situations where purchase result delivery to the application encounters issues and is not successful for example, if the network connection is interrupted, the application can fail to receive the "payment complete" message, even though the payment was completed in this situation, the product is not applied to the application you can check for unapplied products using the "appliedstatus" parameter of the purchase list api response and apply the product at that time for subscription products, the product is considered applied at the time of purchase and the "appliedstatus" is set to "true" by default consequently, it is not necessary to check whether a subscription product purchase corresponding to the requested "invoiceid" was successful noteto avoid applying the same product more than once in error, after 3 failed attempts to request the apply product api, wait until the network is reconnected before trying again to call the apply product api, use the applyinvoice method using system; using tizen tv service billing; using tizen tv service sso; using tizen tv; public void request_apply_purchase string strinvoiceid { billingplugin pibilling = new billingplugin ; pibilling requestapieventhandler += new billingrequestapicallbackeventhandler requestapplyinvoicecallbackevent ; string strappid = "**********"; // your application id string struniquecustomid = "abc"; // unique customer id "abc" is a one of the example for unique custom id you can assign id managed by your service // strinvoiceid = issued by getpurchaselist string strcountrycode = environment smarthubconfig country; bool bret = pibilling applyinvoice strappid, struniquecustomid, strinvoiceid, strcountrycode, servertype ; if bret { // api call success } else { // api call fail } } private void requestapplyinvoicecallbackevent object sender, billingrequestapicallbackeventargs e { // do something } the following tables describe the apply product api parameters the response data is in json format apply product api request parameters parameter type mandatory description "appid" string true application id "invoiceid" invoice id "customid" unique customer idsame value as the "ordercustomid" parameter for the buyitem method "countrycode" country codethe country code must be retrieved from the tv "servertype" possible values "dev" staging zone"prd" operating zone table 7 apply purchase api request parameters apply product 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 "appliedtime" true time product applied, in 14-digit utc time, for example, "20140314175900" table 8 apply product api response parameters canceling subscriptions you can only use the subscription cancel api 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, use the cancelsubscription method using system; using tizen tv service billing; using tizen tv service sso; using tizen tv; public void request_cancel_subscription string strsubscriptionid { billingplugin pibilling = new billingplugin ; pibilling requestapieventhandler += new billingrequestapicallbackeventhandler requestcancelsubscriptioncallbackevent ; string strappid = "**********"; // your application id string struniquecustomid = "abc"; // unique customer id "abc" is a one of the example for unique custom id you can assign id managed by your service // strsubscriptionid = issued by getpurchaselist string strcountrycode = environment smarthubconfig country; bool bret = pibilling cancelsubscription strappid, struniquecustomid, strsubscriptionid, strcountrycode, servertype ; if bret { // api call success } else { // api call fail } } private void requestcancelsubscriptioncallbackevent object sender, billingrequestapicallbackeventargs e { // do something } the following tables describe the subscription cancel api parameters the response data is in json format subscription cancel api request parameters parameter type mandatory description "appid" string true application id "subscriptionid" subscription id "customid" unique customer idsame value as the "ordercustomid" parameter for the buyitem method "countrycode" country codethe country code must be retrieved from the tv "servertype" possible values "dev" staging zone"prd" operating zone table 9 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, for example, "20140314175900" "subsstatus" subscription status "00" active"01" subscription expired"02" canceled by buyer"03" canceled for payment failure"04" canceled by cp"05" canceled by admin table 10 subscription cancel 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 11 dpi result codes and messages for explanations of additional dpi result codes, at the dpi portal, go to "help > error code" purchase api and gui when the user wants to make a purchase, authenticate the user and show the common purchase gui with the buyitem method of the tizen tv service billing namespace 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 12 display your own product image to show the common purchase gui, call the buyitem method using system text; using system io; using newtonsoft json; using tizen tv service billing; using tizen tv service sso; using tizen tv; public void request_buy_item { billingplugin pibilling = new billingplugin ; pibilling buyitemeventhandler += new billingclientclosedeventhandler buyitemcallbackevent ; stringbuilder sb = new stringbuilder ; stringwriter sw = new stringwriter sb ; string appid = "**********"; // your application id string uniquecustomid = "abc"; // unique customer id "abc" is a one of the example for unique custom id you can assign id managed by your service billingrequestservertype servertype = getbillingservertype ; using jsonwriter writer = new jsontextwriter sw { writer formatting = formatting indented; writer writestartobject ; writer writepropertyname "ordertotal" ; writer writevalue price ; // issued by getproductlist writer writepropertyname "orderitemid" ; writer writevalue itemid ; // issued by getproductlist writer writepropertyname "ordertitle" ; writer writevalue itemtitle ; // issued by getproductlist writer writepropertyname "ordercurrencyid" ; writer writevalue currencyid ; // issued by getproductlist writer writepropertyname "ordercustomid" ; writer writevalue uniquecustomid ; writer writeendobject ; } bool bret = pibilling buyitem appid, servertype, sb tostring ; if bret { // api call success } else { // api call fail } } private void buyitemcallbackevent object sender, billingclientclosedeventargs e { // do something } private billingrequestservertype getbillingservertype { var tvservertype = environment smarthubconfig server; billingrequestservertype servertype; switch tvservertype { case smarthubconfig servertype operating servertype = billingrequestservertype prd; break; case smarthubconfig servertype developement servertype = billingrequestservertype dev; break; default servertype = billingrequestservertype prd; break; } return servertype; } the buyitem method request and response data are in json format buyitem method request parameters parameter type mandatory description "appid" string true application id "paymentserver" possible values "dev" staging zone "dummy" staging zone with dummy payment "prd" operating zone "paymentdetails" json payment details orderitemid" string true purchase item id, for example, "dp123400000000" "itemid" issued by the products list api "ordertitle" purchase item title"itemtitle" issued by the products list api the length must not exceed 100 characters "ordertotal" total purchase price"price" issued by the products list api when converting the number to string type, pay attention to the unit separators "ordercurrencyid" purchase currency unit"currencyid" issued by the products list api "orderid" false management id for purchases managed by third-party applications "ordercustomid" true unique customer id "orderitempath" false item image uri the image must be in jpeg, jpg, or png format "dynmcproductid" true dynamic products only unique id for dynamic product from a third-party application "dynmcproductinfo" dynamic product item type, such as rental or permanent purchase "dynmcsharecategory" dynamic product share category "dynmctaxcategory" dynamic product tax category "stltappid" false settlement application idfor samsung internal use only do not use table 13 buyitem method 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", this value is only available when payresult is "success" otherwise, you will not get any value for "invoiceid" table 14 buyitem response parameters note "invoiceid" in paydetail is available since tizen 5 0 the “dynamic product” type is also supported on 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 country and currency codes the following table lists countries with their corresponding country code, currency, and currency code country name country code currency currency code aland islands ax euro eur argentina ar argentine peso ars australia au australian dollar aud austria at euro eur belgium be euro eur 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 croatia hr croatian kuna hrk czech republic cz czech koruna czk denmark dk danish krone dkk 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 india in indian rupee inr indonesia id indonesian rupiah idr 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 latvia lv euro eur lithuania lt euro eur luxembourg lu euro eur malaysia my malaysian ringgit myr mexico mx mexican peso mxn netherlands nl euro eur new zealand nz new zealand dollar nzd norway no norwegian krone nok panama pa us dollar usd peru pe peruvian sol pen philippines ph philippine peso php poland pl polish zloty pln portugal pt euro eur romania ro euro eur russia ru russian ruble rub saudi arabia sa saudi riyal sar 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 thailand th thai baht thb turkey tr turkish lira try united arab emirates ae emiriti dirham aed ukraine ua ukrainian hryvnia uah united kingdom gb british pound gbp united states of america us us dollar usd vietnam vn vietnamese dong vnd table 15 country and currency codes

Implementing the Purchase Process

implementing the purchase process this topic describes how to implement a billing system for managing products, sales, and payments, by using samsung checkout in your application related info billing api productinfo api sso api implementing the purchase process for tizen net samsung checkout dpi portal guide samsung checkout dpi portal samples samsung checkout web application samsung checkout net application implement a billing system for in-app purchases in your application, by using samsung checkout through the dpi service apis and the billing api prerequisites to implement in-app purchases before you start implementing samsung checkout in your application, start registering your application at the samsung apps tv seller office you do not need to complete the registration with your source code at this point to be able to use the dpi portal, you need to proceed to the second step of the app registration page and set the "billing" field to "use" and the "samsung checkout on tv" field to "yes" you can save the registration at this point and return to it later when your source code is complete for more information, see the samsung checkout dpi portal guide noteto manage your product for billing, go to the samsung checkout dpi portal to use the dpi, billing, productinfo, and sso apis, the application has to request permission by adding the following privileges to the "config xml" file <tizen privilege name="http //developer samsung com/privilege/sso partner"/> <tizen privilege name="http //developer samsung com/privilege/productinfo"/> <tizen privilege name="http //developer samsung com/privilege/billing"/> to use the methods of the billing, productinfo, and sso apis, include the "webapis js" library in the "index html" file <script type='text/javascript' language='javascript' src='$webapis/webapis/webapis js'></script> initialize the required variables retrieve the user id var uniquecustomid = "123"; // unique id for this user "123" is an example value it can be an id managed by your service retrieve the country code var countrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; retrieve the server type var strtvserver = webapis productinfo getsmarttvservertype ; set the dpi url and service environment depending on the server type strurldpi = "https //checkoutapi samsungcheckout com/openapi"; strserver = "prd"; strsecuritykey = "********"; dpi service apis you can use the apis provided by the dpi service to manage products and sales the dpi service apis communicate data in json format, using the post method generating check values the check value is used by the dpi service to verify api requests it is a base64 hash generated by applying the hmac sha256 algorithm on a concatenated string of parameters using the dpi security key the application can also use the check value to verify that api response data from the dpi server is legitimate to ensure the data integrity of requests and responses in real time, generate and verify the check value for api requests and responses during runtime notethe dpi security key is used only by samsung smart tv applications for open api calls do not expose this key you can use a key management server for greater security to generate the check value, the following 2 items are used as parameters concatenation of the required parameters for example, "12345"+"123"+"us"+"2"+"1" is concatenated to "12345123us21" the required parameters vary depending on the api dpi security key the dpi security key is issued at the dpi portal you can use any open library to generate the hmac sha256 hash the following example uses the cryptojs library var appid = "1234567890"; // your application id var uniquecustomid = "youruniqueid"; // retrieved during initialization var countrycode = "us"; // retrieved during initialization var itemtype = "2"; // request value for "invoice/list" api var pagenumber = 1; // request value for "invoice/list" api var detailobj = new object ; detailobj appid = appid; // your application id detailobj customid = uniquecustomid; // same value as ordercustomid parameter for buyitem detailobj countrycode = countrycode; // tv country code detailobj itemtype = itemtype; // "2" all items detailobj pagenumber = pagenumber; var reqparams = detailobj appid + detailobj customid + detailobj countrycode + detailobj itemtype + detailobj pagenumber; /* required parameters [invoice/list] request appid + uniquecustomid + countrycode + itemtype + pagenumber [cont/list] request appid + countrycode response cpstatus, cpresult, totalcount, itemid seq */ var hash = cryptojs hmacsha256 reqparams , securitykey ; var checkvalue = cryptojs enc base64 stringify hash ; requesting user purchases the purchase list api "invoice/list" requests the list of purchased items for a specific user, usually the currently logged-in user the api response identifies whether purchased products have been applied or have been refunded notefor subscription products, the default value of the "appliedstatus" parameter is "true", but the "cancelstatus" parameter does not indicate the refund status in purchase history instead, it indicates the cancelation status for the next subscription cycle the "subsstatus" and "subsendtime" parameters detail the subscription expiration status to call the purchase list api // generate checkvalue var reqparams = detailobj appid + detailobj customid + detailobj countrycode + detailobj itemtype + detailobj pagenumber; /* required parameters [invoice/list] request appid + uniquecustomid + countrycode + itemtype + pagenumber [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 urldpi + "/invoice/list", 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 purchase list 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 1 purchase list api request headers the purchase list api request and response data are in json format purchase list api request parameters parameter type mandatory description "appid" string true application 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 "itemtype" product type "1" non-consumable and limited-period items"2" all items "pagenumber" number requested page number range 1~n each purchase record page has up to 100 entries to receive the complete purchase record, post purchase list api requests while increasing the "pagenumber" value, until "eof" is returned in the "cpresult" parameter "checkvalue" string security check value required parameters "appid" + "customid" + "countrycode" + "itemtype" + "pagenumber" table 2 purchase list api request parameters purchase list api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" false result message "eof" last page of the purchase history "hasnext true" purchase history has further pages other message corresponding to the "cpstatus" error code "totalcount" number true total number of invoices sum of all purchase history pages, or sum of purchase history in the specified time period "checkvalue" string security check value required parameters "cpstatus" + "cpresult" + "totalcount" + "invoicedetails[0] itemid" + … + "invoicedetails[totalcount] itemid" "invoicedetails" json false invoice information "seq" number true sequence number range 1 ~ totalcount "invoiceid" string invoice id for products with recurring payments, use the subscription id "itemid" product id "itemtitle" product name "itemtype" number product type "1" consumable "2" non-consumable "3" limited-period "4" subscriptionthe response "itemtype" value differs from the request "itemtype" value the response value contains more detail "ordertime" string payment time, in 14-digit utc time "period" number false limited period product duration, in minutes "price" true original product price, in "xxxx yy" format this is price without promotion "ordercurrencyid" string currency code "cancelstatus" boolean cancelation status "true" sale canceled "false" sale ongoing for subscription products, indicates the cancelation status for the next subscription cycle "appliedstatus" product application status "true" applied "false" not applied for subscription products, the default value is "true" "appliedtime" string false time product applied, in 14-digit utc time "limitendtime" true for limited period products only limited period product end time, in 14-digit utc time if the product has not been applied, "limitendtime" is an empty string "remaintime" limited period product time remaining, in seconds "remaintime" = "limitendtime" – request time if the product has not been applied, "remaintime" is an empty string "subscriptioninfo" json false subscription information mandatory for subscription products "subscriptionid" string true subscription id "subsstarttime" subscription start time, in 14-digit utc time "subsendtime" subscription expiry time, in 14-digit utc time "subsstatus" subscription status "00" active"01" subscription expired"02" canceled by buyer"03" canceled for payment failure"04" canceled by cp"05" canceled by admin"06" canceled by gdpr restriction"07" canceled by withdrawn account"08" canceled by unused account"09" canceled by misused blocked account"10" canceled by banned blocked account "lastpaymentamount" latest payment amount, in "xxxx yy" format "lastpaymenttaxamount" tax amount in the latest payment amount, in "xxxx yy" format "lastpaymenttime" latest payment time, in 14-digit utc time "nextcycletime" next payment time, in 14-digit utc time this is the time calculated based on the billing cycle of the subscription and the subscription start time "nextpaymenttime" next actual payment time, in 14-digit utc time this is the time when the payment is charged to the user's payment method "isfreetrialperiod" boolean whether the subscription is currently in the free trial period "true" in free trial period"false" not in free trial periodif the first payment after the free trial period fails, a second attempt is made the next day, in accordance with samsung policy during this grace period, the value of "isfreetrialperiod" is "true" "countrycode" string base country code for the subscription the value is the country set on the tv when the subscription was started "isflexibleofferapplied" boolean whether the subscription has a flexible offer applied for the next payment "true" has a flexible offer applied"false does not have a flexible offer applied "flexibleofferprice" string false flexible offer price, in "xxxx yy" format "flexibleofferremainingcycle" number number of remaining cycles of a flexible offer applied to current subscription table 3 purchase list api response parameters note14-digit utc time is a time representation format based on utc time it uses the following format yyyymmddhh24miss for example, 20181113095011 requesting products for sale the products list api "cont/list" requests product information from the dpi server when the api is in "show" status, it returns the information for the products on sale this api is generally used to generate a list of buyable products in the application to call the products list api // generate checkvalue var reqparams = detailobj appid + detailobj countrycode; /* required parameters [cont/list] request appid + countrycode [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 + "/cont/list", 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 products list 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 4 products list api request headers the products list api request and response data are in json format products list api request parameters parameter type mandatory description "appid" string true application id "countrycode" country code the country code must be retrieved from the tv "productidlist" string[] false list of product ids products in this list are always included in the response even when the product value is "optional" and the product is otherwise not included "pagesize" number false requested page size range 1~n maximum 100 number of products retrieved per page "pagenumber" requested page number range 1~n each purchase record page has a number of entries equal to the "pagesize" value to receive the complete purchase record, post purchase list api requests while increasing the "pagenumber" value, until "eof" is returned in the "cpresult" parameter "checkvalue" string true security check value required parameters "appid" + "countrycode" table 5 products list api request parameters product list api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" false result message "eof" last page of the purchase history "hasnext true" purchase history has further pages other message corresponding to the "cpstatus" error code "totalcount" number true total number of invoices sum of all purchase history pages, or sum of purchase history in the specified time period "checkvalue" string security check value required parameters "cpstatus" + "cpresult" + "totalcount" + "invoicedetails[0] itemid" + … + "invoicedetails[n] itemid" "itemdetails" json false invoice information "seq" number true sequence number range 1 ~ totalcount "itemid" string product id "itemtitle" product name "itemtype" number product type "1" consumable "2" non-consumable "3" limited-period "4" subscription "ordertime" string payment time, in 14-digit utc time "period" number false limited period product duration, in minutes "price" number true product price, in "xxxx yy" format if the product is running a flexible offer, the promotion price is shown during the promotion period, otherwise, the original price is shown "originalprice" original product price, in "xxxx yy" format this field enables you to keep track of the original price during a flexible offer, when the "price" field is changed to the promotion price during the promotion period, if buyitem is called using the original price, eligible users still pay the promotion price "currencyid" string currency code "subscriptioninfo" json false subscription information mandatory for subscription products "paymentcycleperiod" string true subscription payment period "w" weeks"m" months"y" years "paymentcyclefrq" number payment cycle frequency "paymentcycle" number of payment cycles "freetrialdaycount" number of free trial days for the product table 6 products list api response parameters verifying purchases the verify purchase api "invoice/verify" checks whether a purchase, corresponding to the requested "invoiceid", was successful to call the verify purchase api /* required parameters [invoice/verify] 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 + "/invoice/verify", 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 verify purchase 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 7 verify purchase api request headers the verify purchase api request and response data are in json format verify purchase 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 8 verify purchase api request parameters verify purchase 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 "appid" true requested application id "invoiceid" requested invoice id table 9 verify purchase api response parameters applying products the apply product api "invoice/apply" supports product management to help guarantee secure sales of your products normally, the dpi service is notified that the purchased product has been successfully applied the apply product api is used in situations where purchase result delivery to the application encounters issues and is not successful for example, if the network connection is interrupted, the application can fail to receive the "payment complete" message, even though the payment was completed in this situation, the product is not applied to the application you can check for unapplied products using the "appliedstatus" parameter of the purchase list api response and apply the product at that time for subscription products, the product is considered applied at the time of purchase and the "appliedstatus" is set to "true" by default consequently, it is not necessary to check whether a subscription product purchase corresponding to the requested "invoiceid" was successful noteto avoid applying the same product more than once in error, after 3 failed attempts to request the apply product api, wait until the network is reconnected before trying again to call the apply product api /* required parameters [invoice/apply] 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 + "/invoice/apply", 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 apply product api 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 10 apply purchase api request headers the apply product api request and response data are in json format apply product 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 11 apply purchase api request parameters apply product 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 "appliedtime" true time product applied, in 14-digit utc time table 12 apply product api response parameters modifying subscription plans retrieve changeable products the subscription plan changeable products api "/subscription/plan-change/changeable-products" retrieves the list of products that a user's subscription can be changed to to call the subscription plan changeable products api // generate checkvalue var reqparams = detailobj appid + detailobj subscriptionid + detailobj timestamp; /* required parameters [subscription/plan-change/changeable-products] 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/changeable-products", 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 changeable products api has the following request 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 13 subscription plan changeable products api request headers the subscription plan changeable products api request and response data are in json format subscription plan changeable products api request parameters parameter type mandatory description "appid" string true application id "subscriptionid" subscription id "productidlist" string[] false list of product ids products in this list are always included in the response even when the product value is "optional" and the product is otherwise not included "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" + "subscriptionid" + "timestamp" table 14 subscription plan changeable products api request parameters subscription plan changeable products api response parameters parameter type mandatory description "cpstatus" string true result code "100000" success"errorcode" failure "cpresult" false result message "eof" last page of the purchase history "hasnext true" purchase history has further pages other message corresponding to the "cpstatus" error code "changeableproducts" json true list of changeable products "seq" number true sequence number range 1 ~ totalcount "itemid" string product id "itemtitle" product name "itemtype" number product type "1" consumable "2" non-consumable"3" limited-period "4" subscription the response "itemtype" value differs from the request "itemtype" value the response value contains more detail "period" number false limited period product duration, in minutes "price" true product price, in "xxxx yy" format if the product is running a flexible offer, the promotion price is shown during the promotion period, otherwise, the original price is shown "originalprice" original product price, in "xxxx yy" format this field enables you to keep track of the original price during a flexible offer, when the "price" field is changed to the promotion price "currencyid" string currency code "subscriptioninfo" json false subscription product information "productgroupid" string true subscription product group id "productlevel" number product level in the subscription product group "paymentcycleperiod" string subscription payment period "w" weeks"m" months"y" years "paymentcyclefrq" number payment cycle frequency "paymentcycle" number of payment cycles "freetrialdaycount" number of free trial days for the product table 15 subscription plan changeable products api response parameters pre-check subscription plan changes the subscription plan change pre-check api "subscription/plan-change/pre-check" allows you to preview the impact of switching subscription products to call the subscription plan change pre-check api // generate checkvalue var reqparams = detailobj appid + detailobj subscriptionid + detailobj afterproductid + detailobj timestamp; /* required parameters [subscription/plan-change/pre-check] request appid + subscriptionid + afterproductid + 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/pre-check", 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 pre-check api has the following request 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 16 subscription plan change pre-check api request headers the subscription plan change pre-check api request and response data are in json format subscription plan change pre-check api request parameters parameter type mandatory description "appid" string true application id "subscriptionid" subscription id "afterproductid" product id of the new product "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" + "afterproductid" + "timestamp" table 17 subscription plan change pre-check api request parameters subscription plan change pre-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 "currentproductname" name of the current subscription product "currentbenefit" json false information about the current benefit mandatory if a benefit is active "type" string true benefit type free_trialcoupon "freetrialdays" integer number of free trial days for the product if a free trial is not active, the value is '0' "couponname" string false name of the coupon applied to the product "enddate" true end date of the free trial or coupon benefit format "yyyy-mm-dd" "afterproductname" string true name of the new product "afterproductprice" price of the new product "afterproductpricetaxincluded" boolean whether the new product price includes tax "true" includes tax"false" does not include tax "afterproductfirstpaymentdate" string estimated date for the first payment on the new product format "yyyy-mm-dd" the date takes into account any free trial days for the new product and, except for subscription upgrades, any benefit period currently active "productcurrencycode" currency code "daysuntilfirstpaymentdate" integer false number of days the upgraded product can be used without additional payment incudes any free trial days for the upgraded product if a free trial period is currently active, the value is '0' and no free trial benefits of the upgraded product are returned mandatory for subscription upgrades "afterproductflexibleofferprice" string flexible offer price of the new product "afterproductflexibleoffercycle" integer number of benefit cycles a flexible offer is applied to the new product "currentproductflexibleofferapplied" boolean true whether the current product has a flexible offer applied "true" has a flexible offer applied"false" does not have a flexible offer applied "currentproductflexibleofferremainingcycle" integer false number of remaining benefit cycles of the current product's flexible offer mandatory when "currentproductflexibleofferapplied" is "true" table 18 subscription plan change pre-check api response parameters reserve subscription plan changes you can use the subscription plan change reserve api "subscription/plan-change/reserve" to request changing the customer's subscription plan to call the subscription plan change reserve api // generate checkvalue var reqparams = detailobj appid + detailobj subscriptionid + detailobj afterproductid + detailobj timestamp; /* required parameters [subscription/plan-change/reserve] request appid + subscriptionid + afterproductid + 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/reserve", 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 reserve 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 19 subscription plan change reserve api request headers the subscription plan change reserve api request and response data are in json format subscription plan change reserve api request parameters parameter type mandatory description "appid" string true application id "subscriptionid" subscription id "afterproductid" product id of the new product "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" + "afterproductid" + "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 20 subscription plan change reserve api request parameters subscription plan change reserve 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 "currentproductname" name of the current subscription product "currentbenefit" json false information about the current benefit mandatory if a benefit is active "type" string true benefit type free_trialcoupon "freetrialdays" integer number of free trial days for the product if a free trial is not active, the value is '0' "couponname" string false name of the coupon applied to the product "enddate" true end date of the free trial or coupon benefit format "yyyy-mm-dd" "afterproductname" string true name of the new product "afterproductprice" price of the new product "afterproductpricetaxincluded" boolean whether the new product price includes tax "true" includes tax"false" does not include tax "afterproductfirstpaymentdate" string estimated date for the first payment on the new product format "yyyy-mm-dd" the date takes into account any free trial days for the new product and, except for subscription upgrades, the benefit period currently active "productcurrencycode" currency code "daysuntilfirstpaymentdate" integer false number of days the upgraded product can be used without additional payment includes any free trial days for the upgraded product if a free trial period is currently active, the value is '0' and no free trial benefits of the upgraded product are returned mandatory for subscription upgrades "afterproductflexibleofferprice" string flexible offer price of the new product "afterproductflexibleoffercycle" integer number of benefit cycles a flexible offer is applied to the new product "currentproductflexibleofferapplied" boolean true whether current product has a flexible offer applied "true" has a flexible offer applied"false" does not have a flexible offer applied "currentproductflexibleofferremainingcycle" integer false number of remaining benefit cycles of the current product's flexible offer mandatory when "currentproductflexibleofferapplied" is "true" table 21 subscription plan change reserve api response parameters retrieve subscription plan change 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

Implementing the Purchase Process

Implementing the Purchase Process

Didn’t find what you were looking for?

FAQ

Join the Forum

Get Support

Implementing the Purchase Process

Implementing the Purchase Process

Didn’t find what you were looking for?

FAQ

Join the Forum

Get Support

Manage Your Cookies

Essential Cookies

Analytical/Performance Cookies

Functionality Cookies

Advertising Cookies

Preferences Submitted