Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Filter
Develop Smart TV
docimplementing 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 ; 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 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 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 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" false 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 34 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 35 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 36 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 37 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 38 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 39 country and currency codes
Develop Samsung IAP
docprogramming guide the samsung in-app purchase iap programming guide explains how to integrate and configure iap, defines the iap sdk and iap server apis, and briefly describes what to do before submitting your app to galaxy store by integrating iap, your apps can sell two types of in-app products item goods and services that charge users on a one-time basis for consumable item purchases for example, coins, special powers, gems , mark the item as consumed by calling the consumepurchaseditems method so that the user can buy the item again after they have consumed it items can be repurchased only after the app reports them as consumed by calling consumepurchaseditems for non-consumable item purchases for example, e-books, game boards , acknowledge delivery of the item by calling the acknowledgepurchases method make sure that the acknowledged items cannot be repurchased notethe distinction between consumable and non-consumable types has been deprecated the ability to register non-consumable types will end on january 14, 2026 after registering the item type, please call either the consumepurchaseditems or acknowledgepurchases method based on if the item can be repurchased or not subscription a set of benefits that charges users on a recurring basis app users can use subscription products as many times as they want during the free trial period or when a paid subscription is active for subscription purchases for example, magazines, e-zines, newspapers acknowledge delivery of the subscription by calling the acknowledgepurchases method see the subscription guide for more information about subscriptions you can beta test your iap integration before you submit your app for review and normal publication in galaxy store see the test guide for more information
Develop Smart TV
docsamsung checkout dpi portal overview the samsung checkout dpi digital product inventory portal https //dpi samsungcheckout com/ is a web service portal designed for the samsung smart tv partners, which samsung helps them sell products and items through smart tv apps from the dpi, partners can register and manage products for sale and access the transaction history logs and sales reports for the applications they own dpi main services product management standard in-app products, subscriptions, paid apps order management purchase history for each user sales reports and financial reports coupon management creation and issuance service initiation process an account for the samsung apps tv seller office is required to use the dpi service once registered, partners can use the dpi service ※ dpi mini guide helps to grasp the overall workflow of samsung checkout service and dpi site - mini guide download step 1 accessing samsung checkout - login create a samsung account register your app in seller office and login to the dpi ① create a samsung account ② register your app in seller office ③ login to the checkout dpi portal noticeat first, only 'manager' in seller office can access dpi portal manager can manage entire menu in dpi portal manager can give permission to 'members' through membership management ※ members cannot access main screen before being given permission by a manager step 2 create group and give permissions only managers can access the member menu and manage groups ① member menu managers can manage and give menu permissions to members this can be done through the membership management and the group management menus ② group management > click create group go to create group menu and configure a group you can click operation, finance, cs or developer buttons to show preset menu permissions these preset menu permissions are for guidance only and can be edited ③ view group management list now you can manage members go to ‘membership management > edit permissions’ menu ④ membership management > edit permissions managers can manage and give menu permissions to members this can be done through the membership management and the group management menus ⑤ select member and group go to create group menu and configure a group you can click operation, finance, cs or developer buttons to show preset menu permissions these preset menu permissions are for guidance only and can be edited ⑥ confirm permissions now you can manage members go to ‘membership management > edit permissions’ menu step 3 issuance of dpi security key the dpi security key must be issued to safely use the service the issued key can be viewed under 'settings > app details setting' the key is a security key to use api calls, and this is a protection mechanism for invalid access from/to the app and dpi the related process is described in the section generating check values importantthe issued security key is a key to be used for open api calls made by a smart tv app please be careful not to reveal this key to others test buyers you can enroll test buyer in settings > test buyer menu checkout does not provide dummy pay anymore therefore, if you’d like to do payment test, please enroll test buyer ① input the test buyer’s samsung account id click [check samsung account registration] and please check the samsung account is available ② input the test buyer’s name ③ contact is not required information after filling in all the required information, click [register] button noticebefore launching your app on tv, only test buyers are allowed to proceed with the payment test importantafter releasing your app on tv, everyone is free to proceed with the payment test ※ after the test, you must manually process the refund it does not provide an automatic refund function product products can be registered for different countries through the add a new product menu configure product ① go to ‘product > add a new product’ menu ② this is where a new product is registered ③ enter product information product id, description, product type, visibility, expiration ④ please note that when you check visibility, the product will become visible from the app product type the following table explains the details of "product type" product type description consumable consumers can purchase this type of product anytime purchase history can be retrieved for 90 days non-consumable consumers can purchase this type of product only once purchase history can be retrieved with no time restriction limited period once this type of product is purchased, repurchase cannot be made during the time when the product effect set by cp lasts purchase history can be retrieved for 90 days if “limited period” product type is chosen, the duration of time for the product effect to last can be entered in the units above minute the duration time for the product effect to last is allowed for the maximum of 90 days subscription dpi system processes automatic payment on a certain designated cycle paid app for paid apps, when you register your app on dpi system you need to select it as paid app dynamic product in case that pater and samsung agree on that products and prices will be managed by cms of partner not samsung’s dpi, partner should select “dynamic product” as a product type even though all the information of actual products are on cms, partner need to register a representative item on dpi once so that our system can display information on samsung smart tv app/game store which is legally required and verify which server we need to call for certain products cms or dpi if dynamic product is chosen, partner does not register each products on dpi that partner sells in their app actuallypartner builds and operates its own cms to manage products information including prices and to verify purchase requestsadditional requirementsverification/no verification ‘verification’ is a recommended option otherwise partner has to handle the verification process by themselves and take all the responsibility for all the error cases related to verification process if ‘verification’ is selected, ‘verify uri’ is also required this uri should serve the function of checking product information such as product itself, price and currencyprice settingprice range information of products that you actually sells in your app is required by country/location it is not used for actual payment for providing the app information on samsung smart tv app/game store which is legally required thus, it has to be updated when the price range of your products is changed subscription it is necessary to make a subscription group before creating subscription item add new subscription group ① go to ‘product > subscription group > add a new group’ menu ② this is where a new subscription group is registered ③ enter subscription group name setting free trial offering ① free trial is able to set per “product group” id ② partner defines whether a free days offer whether it should be offered once per account/device or both notice [free trial offering option] per account only once if a user use a free trial offer with the "a" account once, free experience will be expired, and additional free experience is not possible with the "a" account however, if a cp does not check “ per device only once ”, a user can experience it free of charge when creating a new account with no subscription history per device only once if a user use one free trial offer on "a" device, a user cannot use free experience even if you change your account and create a new "b" account on a device both- per account only once provide free trial offer both based on “ a ” account and “ a ” device case 1 with the “ b ” account that does not have a subscription history, free experience is not available when you first sign up for the “ a ” device case 2 with “ a ” account, which has a history of cancellation after subscription, “ b ” device subscription is not allowed for free configure subscription ① go to ‘product > add a new product’ menu ② select subscription in the product type ③ enter product information product id, description ④ choose billing period, produce level, subscription group ⑤ if you’d like to make free trial subscription, please input the free trial period ⑥ check the duplicate benefit, visibility, expiration subscription plan checkout supports upgrade, downgrade, cross-downgrade subscription plan create a subscription group to set the subscription level in the same group, consumers can upgrade and downgrade freely cross-downgrade api is currently possible, checkout does not provide cross-upgrade api importantif you’d like to use the cross-upgrade function, please use a combination of upgrade api and cross grade api please refer to the details on the sdf site in the near future, we will provide the guide on the sdf site field description the following table explains the details of input fields input field description product name representative product name the name of the product used in the representative country/location must be entered in the country/location product name field this field cannot be left empty product id alphanumeric and two special characters '-', '_' are allowed maximum 20 bytes product description describe the product type following product types are allowed;consumable, non-consumable, limited period, paid app, subscription, dynamic product period if the product type is ‘limited period’, a number fewer than 129,600 in minutes is allowed maximum 90 days billing period if the product type is "subscription" , "weekly","monthly","annualy" is allowed subscription group it is necessary to make a subscription group before creating subscription item free trial period if the product type is "subscription", a number in days is allowed visibility a field indicating whether the product can be shown "show" , "hide" and "optional" is allowed duplication benefit the condition defines whether a free days offer whether it should be offered once per account/device or both expiration if the product type is "subscription" , "not applicable" ,"1 month", "6 month", "1 year" is allowed country/location product name the country/location and product name are separated by ' ' and a maximum of 50 bytes of product name is allowed if more than one country/location is entered, use ' country/location product price the country/location and price information are separated by ' ', and if more than one country/location is input, the use of the ' transaction policy the dpi provides information on the status for the products purchased by users through request purchases list api in case the purchased product is not applied on the real game, the status can be checked on the “product applied status” in case the purchased product was refunded to the user, the status can be checked on the “sales cancellation status” the period of time the above status information is provided through api to the application can be classified by the product type as shown below product type applied purchases purchase history not applied purchases refund/cancellation consumable application date + 90days all products can be viewed with no restrictions in time period refund date+ 90 days subscription subscription expiry date subsendtime + 90days subscription expiry date subsendtime + 90 days subscription expiry date subsendtime + 90 days glossaries term description billing / payment service a service created in order to help monetary transactions between service providers and users partner / app developer be in charge of creating products suitable for consumers of the smart tv paid app a service or app that can be only downloaded after making a payment in-app purchase a method to pay for additional products and features within both free apps and paid apps paypal paypal the global payments company headquartered in the united states that provide the payment service via pre-registered payment method digital product inventory dpi a system provided to developers to enter and manage extra products and items in their own apps it is directly connected to the app store samsung checkout billing client a payment ui module for consumers to add their choice of payment methods and pay for premium apps or special items operating zone/ staging zone operating zone is a live environment where the real users get access to verification system is a test environment where 3rd party development and qa are conducted sandbox zone is regarded as staging zone operating tv / development tv - operating tv tv purchased from on/off-line, tv with the same setting environment as the one in general users - development tv tv that is made in use of a board separately provided by samsung electronics, tv that allows a setting environment for development different from the one for general users cms content management system product catalogue management server or system including price information in this document, this word refers to the server for the type “dynamic product” that has all the information of products and handles verification with its own product catalogue for reference, product information of other product types should be managed in dpi not 3rd party cms dpi will be looking at cms to pull necessary product information as needed cms will be the source of truth regarding content metadata, purchase history which user bought which title at which resolution of purchase/rental, etc whereas dpi will be the source of truth of transactional data i e transaction amount, tax amount both systems will be linked by "invoice id" that is generated by dpi and passed over to cms for every successful transaction ※ dpi user guide full version provides detailed desciptions and examples of new dpi site functions/usages - full guide download
Develop Smart TV
docsamsung checkout dpi portal overview the samsung checkout dpi digital product inventory portal https //dpi samsungcheckout com/ is a web service portal designed for the samsung smart tv partners, which samsung helps them sell products and items through smart tv apps from the dpi, partners can register and manage products for sale and access the transaction history logs and sales reports for the applications they own dpi main services product management standard in-app products, subscriptions, paid apps order management purchase history for each user sales reports and financial reports coupon management creation and issuance service initiation process an account for the samsung apps tv seller office is required to use the dpi service once registered, partners can use the dpi service ※ dpi mini guide helps to grasp the overall workflow of samsung checkout service and dpi site - mini guide download step 1 accessing samsung checkout - login create a samsung account register your app in seller office and login to the dpi ① create a samsung account ② register your app in seller office ③ login to the checkout dpi portal noticeat first, only 'manager' in seller office can access dpi portal manager can manage entire menu in dpi portal manager can give permission to 'members' through membership management ※ members cannot access main screen before being given permission by a manager step 2 create group and give permissions only managers can access the member menu and manage groups ① member menu managers can manage and give menu permissions to members this can be done through the membership management and the group management menus ② group management > click create group go to create group menu and configure a group you can click operation, finance, cs or developer buttons to show preset menu permissions these preset menu permissions are for guidance only and can be edited ③ view group management list now you can manage members go to ‘membership management > edit permissions’ menu ④ membership management > edit permissions managers can manage and give menu permissions to members this can be done through the membership management and the group management menus ⑤ select member and group go to create group menu and configure a group you can click operation, finance, cs or developer buttons to show preset menu permissions these preset menu permissions are for guidance only and can be edited ⑥ confirm permissions now you can manage members go to ‘membership management > edit permissions’ menu step 3 issuance of dpi security key the dpi security key must be issued to safely use the service the issued key can be viewed under 'settings > app details setting' the key is a security key to use api calls, and this is a protection mechanism for invalid access from/to the app and dpi the related process is described in the section generating check values importantthe issued security key is a key to be used for open api calls made by a smart tv app please be careful not to reveal this key to others test buyers you can enroll test buyer in settings > test buyer menu checkout does not provide dummy pay anymore therefore, if you’d like to do payment test, please enroll test buyer ① input the test buyer’s samsung account id click [check samsung account registration] and please check the samsung account is available ② input the test buyer’s name ③ contact is not required information after filling in all the required information, click [register] button noticebefore launching your app on tv, only test buyers are allowed to proceed with the payment test importantafter releasing your app on tv, everyone is free to proceed with the payment test ※ after the test, you must manually process the refund it does not provide an automatic refund function product products can be registered for different countries through the add a new product menu configure product ① go to ‘product > add a new product’ menu ② this is where a new product is registered ③ enter product information product id, description, product type, visibility, expiration ④ please note that when you check visibility, the product will become visible from the app product type the following table explains the details of "product type" product type description consumable consumers can purchase this type of product anytime purchase history can be retrieved for 90 days non-consumable consumers can purchase this type of product only once purchase history can be retrieved with no time restriction limited period once this type of product is purchased, repurchase cannot be made during the time when the product effect set by cp lasts purchase history can be retrieved for 90 days if “limited period” product type is chosen, the duration of time for the product effect to last can be entered in the units above minute the duration time for the product effect to last is allowed for the maximum of 90 days subscription dpi system processes automatic payment on a certain designated cycle paid app for paid apps, when you register your app on dpi system you need to select it as paid app dynamic product in case that pater and samsung agree on that products and prices will be managed by cms of partner not samsung’s dpi, partner should select “dynamic product” as a product type even though all the information of actual products are on cms, partner need to register a representative item on dpi once so that our system can display information on samsung smart tv app/game store which is legally required and verify which server we need to call for certain products cms or dpi if dynamic product is chosen, partner does not register each products on dpi that partner sells in their app actuallypartner builds and operates its own cms to manage products information including prices and to verify purchase requestsadditional requirementsverification/no verification ‘verification’ is a recommended option otherwise partner has to handle the verification process by themselves and take all the responsibility for all the error cases related to verification process if ‘verification’ is selected, ‘verify uri’ is also required this uri should serve the function of checking product information such as product itself, price and currencyprice settingprice range information of products that you actually sells in your app is required by country/location it is not used for actual payment for providing the app information on samsung smart tv app/game store which is legally required thus, it has to be updated when the price range of your products is changed subscription it is necessary to make a subscription group before creating subscription item add new subscription group ① go to ‘product > subscription group > add a new group’ menu ② this is where a new subscription group is registered ③ enter subscription group name setting free trial offering ① free trial is able to set per “product group” id ② partner defines whether a free days offer whether it should be offered once per account/device or both notice [free trial offering option] per account only once if a user use a free trial offer with the "a" account once, free experience will be expired, and additional free experience is not possible with the "a" account however, if a cp does not check “ per device only once ”, a user can experience it free of charge when creating a new account with no subscription history per device only once if a user use one free trial offer on "a" device, a user cannot use free experience even if you change your account and create a new "b" account on a device both- per account only once provide free trial offer both based on “ a ” account and “ a ” device case 1 with the “ b ” account that does not have a subscription history, free experience is not available when you first sign up for the “ a ” device case 2 with “ a ” account, which has a history of cancellation after subscription, “ b ” device subscription is not allowed for free configure subscription ① go to ‘product > add a new product’ menu ② select subscription in the product type ③ enter product information product id, description ④ choose billing period, produce level, subscription group ⑤ if you’d like to make free trial subscription, please input the free trial period ⑥ check the duplicate benefit, visibility, expiration subscription plan checkout supports upgrade, downgrade, cross-downgrade subscription plan create a subscription group to set the subscription level in the same group, consumers can upgrade and downgrade freely cross-downgrade api is currently possible, checkout does not provide cross-upgrade api importantif you’d like to use the cross-upgrade function, please use a combination of upgrade api and cross grade api please refer to the details on the sdf site in the near future, we will provide the guide on the sdf site field description the following table explains the details of input fields input field description product name representative product name the name of the product used in the representative country/location must be entered in the country/location product name field this field cannot be left empty product id alphanumeric and two special characters '-', '_' are allowed maximum 20 bytes product description describe the product type following product types are allowed;consumable, non-consumable, limited period, paid app, subscription, dynamic product period if the product type is ‘limited period’, a number fewer than 129,600 in minutes is allowed maximum 90 days billing period if the product type is "subscription" , "weekly","monthly","annualy" is allowed subscription group it is necessary to make a subscription group before creating subscription item free trial period if the product type is "subscription", a number in days is allowed visibility a field indicating whether the product can be shown "show" , "hide" and "optional" is allowed duplication benefit the condition defines whether a free days offer whether it should be offered once per account/device or both expiration if the product type is "subscription" , "not applicable" ,"1 month", "6 month", "1 year" is allowed country/location product name the country/location and product name are separated by ' ' and a maximum of 50 bytes of product name is allowed if more than one country/location is entered, use ' country/location product price the country/location and price information are separated by ' ', and if more than one country/location is input, the use of the ' transaction policy the dpi provides information on the status for the products purchased by users through request purchases list api in case the purchased product is not applied on the real game, the status can be checked on the “product applied status” in case the purchased product was refunded to the user, the status can be checked on the “sales cancellation status” the period of time the above status information is provided through api to the application can be classified by the product type as shown below product type applied purchases purchase history not applied purchases refund/cancellation consumable application date + 90days all products can be viewed with no restrictions in time period refund date+ 90 days subscription subscription expiry date subsendtime + 90days subscription expiry date subsendtime + 90 days subscription expiry date subsendtime + 90 days glossaries term description billing / payment service a service created in order to help monetary transactions between service providers and users partner / app developer be in charge of creating products suitable for consumers of the smart tv paid app a service or app that can be only downloaded after making a payment in-app purchase a method to pay for additional products and features within both free apps and paid apps paypal paypal the global payments company headquartered in the united states that provide the payment service via pre-registered payment method digital product inventory dpi a system provided to developers to enter and manage extra products and items in their own apps it is directly connected to the app store samsung checkout billing client a payment ui module for consumers to add their choice of payment methods and pay for premium apps or special items operating zone/ staging zone operating zone is a live environment where the real users get access to verification system is a test environment where 3rd party development and qa are conducted sandbox zone is regarded as staging zone operating tv / development tv - operating tv tv purchased from on/off-line, tv with the same setting environment as the one in general users - development tv tv that is made in use of a board separately provided by samsung electronics, tv that allows a setting environment for development different from the one for general users cms content management system product catalogue management server or system including price information in this document, this word refers to the server for the type “dynamic product” that has all the information of products and handles verification with its own product catalogue for reference, product information of other product types should be managed in dpi not 3rd party cms dpi will be looking at cms to pull necessary product information as needed cms will be the source of truth regarding content metadata, purchase history which user bought which title at which resolution of purchase/rental, etc whereas dpi will be the source of truth of transactional data i e transaction amount, tax amount both systems will be linked by "invoice id" that is generated by dpi and passed over to cms for every successful transaction ※ dpi user guide full version provides detailed desciptions and examples of new dpi site functions/usages - full guide download
Develop Samsung IAP
docsamsung iap purchase acknowledgment api the samsung iap purchase acknowledgment api is used to consume or acknowledge a purchased product before you can start using the iap purchase acknowledgment api, you must meet all requirements, use the required authorization header parameters, and use the required url path paremeters in your requests see get started with the iap apis for more information consume or acknowledge a purchased product after your app has granted entitlement of a product to the user with a successful transaction, your app needs to notify samsung iap that the purchase was successfully processed you can report one or more purchased items as consumed, which makes the items available for another purchase the app user may or may not have used the items or, you can acknowledge that the user has been granted entitlement for one or more purchased subscriptions notewe recommend reporting purchased items immediately after verifying their purchase and reporting all unreported products in one call in order to avoid system overload or malfuction request patch /iap/v6/applications/<packagename>/purchases/<purchaseid> notesee url path parameters for more information about the <packagename> and <purchaseid> parameters body parameter name type description action string requiredthe task to perform must be one of the following consume report one or more purchased items as consumed acknowledge acknowledge that the user has been granted entitlement for one or more purchased subscriptions purchasedidlist[] purchaseid string optionalone or more purchase ids of the purchased item or subscription example single item or subscription request body { "action" "consume" } curl curl -i -x patch \ -h "content-type application/json" \ -h "authorization bearer <your-access-token>" \ -h "service-account-id <your-service-account-id>" \ -d '{"action" "consume | acknowledge"}' \ 'https //devapi samsungapps com/iap/v6/applications/<packagename>/purchases/<purchaseid>' example multiple items or subscriptions request body { "action" "consume", "purchasedidlist" [ "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2", "5ed5b555af4ecf4fb756cc32e9cbddd9da15397a26904ff7d1a248eb333d", "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb" ] } curl curl -i -x patch \ -h "content-type application/json" \ -h "authorization bearer <your-access-token>" \ -h "service-account-id <your-service-account-id>" \ -d '{"action" "consume | acknowledge", \ "purchasedidlist" [ \ "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2", \ "5ed5b555af4ecf4fb756cc32e9cbddd9da15397a26904ff7d1a248eb333d", \ "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb" \ ] }' \ 'https //devapi samsungapps com/iap/v6/applications/<packagename>/purchases/<purchaseid>' response name type description totalcount int the number of products for which a response is returned purchaseitemlist[] purchaseid string the purchase id of the transaction purchaseitemlist[] statuscode string response status code purchaseitemlist[] statusstring string response status message statuscode and statusstring values statuscode statusstring consume statusstring acknowledge 0 success success 1 can't find an order with this purchaseid can't find an order with this purchaseid 2 can't consume this purchase because it's not a successful order this is not a successful order 3 this type of product is not a consumable item this type of product is not a subscription 4 this purchase has been consumed already this purchase has been acknowledged already 5 can't consume this purchase because the user is not authorized to consume this order this purchase is not authorized for this order example response { "totalcount" 3, "purchaseitemlist" [ { "purchaseid" "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2", "statuscode" "0", "statusstring" "success " }, { "purchaseid" "81a9be52ab67875acf725bd78fc0bc615eb413ac327bc829fb209100ac", "statuscode" "1", "statusstring" "can't find order with this purchaseid " }, { "purchaseid" "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb", "statuscode" "3", "statusstring" "this type of item is not non-consumable or subscription " } ] } see failure response codes for a list of possible response codes when a request fails failure response codes status code and message 400bad request 102 invalid parameter 401unauthorized 101 failed to verify gateway server authorization
Develop Samsung IAP
dociap configuration and in-app product processing your app code can follow the logic flow below to support your in-app products the scope of each iap sdk api is straightforward and most integrations follow a similar logic flow, which is linear with a few branches after product purchases, iap server apis are typically called to verify purchases notepurchased consumable items not reported as consumed cannot be repurchased requirementyou must call getownedlist whenever launching the application in order to check for unconsumed items or subscription availability
Develop Smart TV
api'tizen tv service billing billingplugin' class reference events billingclientclosedeventhandler buyitemeventhandler the billing transaction event handler, which can be added/removed more billingrequestapicallbackeventhandler requestapieventhandler the billing request api event handler, which can be added/removed more billingshowdeeplinkcallbackeventhandler showdeeplinkeventhandler the billing deep-link feature event handler, which can be added/removed more public functions string getversion gets the billing cs plugin version more bool buyitem string appid, billingrequestservertype servertype, string paydetail launches the billing client more bool isserviceavailable billingrequestservertype eservertype gets the payment service availability more bool getpurchaselist string strappid, string strcustomid, string strcountrycode, int ipagenumber, string strcheckvalue, billingrequestservertype eservertype 'get purchase list' server open api interface more bool showpurchasehistory string strhistoryapp, billingrequestpurchasehistorytype ehistorydetail a billing client deep-link feature launches the billing client's purchasehistory page more bool showregisterpromotionalcode a billing client deep-link feature launches the billing client's promotional codes page more bool showregistercreditcard a billing client deep-link feature launch the billing client's credit card registration page more bool cancelsubscription string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'cancel subscription' server open api interface more bool applyinvoice string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'applyinvoice' server open api interface more bool verifyinvoice string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'verifyinvoice' server open api interface more bool getproductslist string strappid, string strcountrycode, int ipagesize, int ipagenumber, string strcheckvalue, billingrequestservertype eservertype the 'request product list' server open api interface more events billingclientclosedeventhandler buyitemeventhandler the billing transaction event handler, which can be added/removed privilege http //developer samsung com/privilege/billing privilege level public product tv version 4 4 0 sdk support n billingrequestapicallbackeventhandler requestapieventhandler the billing request api event handler, which can be added/removed privilege http //developer samsung com/privilege/billing privilege level public product tv version 4 4 0 sdk support n billingshowdeeplinkcallbackeventhandler showdeeplinkeventhandler the billing deep-link feature event handler, which can be added/removed privilege http //developer samsung com/privilege/billing privilege level public product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n public functions string getversion gets the billing cs plugin version returns billing cs plugin version string value privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool buyitem string appid, billingrequestservertype servertype, string paydetail launches the billing client parameters appid the application id servertype the payment server type paydetail the detailed payment information returns a boolean value returns true if the billing client is launched privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool isserviceavailable billingrequestservertype eservertype gets the payment service availability parameters eservertype the billing server type to check returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool getpurchaselist string strappid, string strcustomid, string strcountrycode, int ipagenumber, string strcheckvalue, billingrequestservertype eservertype 'get purchase list' server open api interface parameters strappid the application id strcustomid unique customer id which can be used to identify the user strcountrycode the country code, such as "us" ipagenumber the page number strcheckvalue the security hash code for more information, see the api guide documentation eservertype the request server type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool showpurchasehistory string strhistoryapp, billingrequestpurchasehistorytype ehistorydetail a billing client deep-link feature launches the billing client's purchasehistory page parameters strhistoryapp the application id to view the payment history for to view the payment history for all applications, use the string "all" ehistorydetail the requested payment history data type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n bool showregisterpromotionalcode a billing client deep-link feature launches the billing client's promotional codes page returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n bool showregistercreditcard a billing client deep-link feature launch the billing client's credit card registration page returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n bool cancelsubscription string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'cancel subscription' server open api interface parameters strappid the application id strcustomid unique customer id which can be used to identify the user strinvoiceid the invoice id for which the subscription is to be cancelled strcountrycode the country code, such as "us" eservertype the request server type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool applyinvoice string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'applyinvoice' server open api interface parameters strappid the application id strcustomid unique customer id which can be used to identify the user strinvoiceid the invoice id to set the invoice status to "apply" strcountrycode the country code, such as "us" eservertype the request server type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool verifyinvoice string strappid, string strcustomid, string strinvoiceid, string strcountrycode, billingrequestservertype eservertype the 'verifyinvoice' server open api interface parameters strappid the application id strcustomid unique customer id which can be used to identify the user strinvoiceid the invoice id whose status is to be checked strcountrycode the country code, such as "us" eservertype the request server type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n bool getproductslist string strappid, string strcountrycode, int ipagesize, int ipagenumber, string strcheckvalue, billingrequestservertype eservertype the 'request product list' server open api interface parameters strappid the application id strcountrycode the country code, such as "us" ipagesize the number of products to show on each page ipagenumber the page number strcheckvalue the security hash code for more information, see the api guide documentation eservertype the request server type for more information, see the api guide documentation returns a boolean value returns true if this api is called successfully privilege http //developer samsung com/privilege/billing privilege level public legal review result this api is already posted at sd product tv version 4 4 0 sdk support n
FAQ game, smarttv
docsamsung checkout q&a this topic solves various issues you may face while creating applications that use samsung checkout service select the applicable section to see the most common questions about a specific subject, and click the section heading to access all the available questions for that subject faq search form search before submitting your application for samsung software quality assurance sqa q1 after developing the application with samsung checkout on the staging environment, i've found that it does not work properly on the operating environment what should i do? there are a few mistakes that are frequently made by the developer, check the list below to ensure that you followed the process correctly check that you have registered your product for the operating zone from the dpi portal your product needs to be registered in both staging and operating zones ensure that the application detects the service environment and sets the dpi api url and server type accordingly you can find more information under "prerequisites > 4 initialize the required variables > 4 4 set the dpi url and service environment depending on the server type" section in implementing the purchase process tv#samsung checkout#staging zone#operating zone#dpi portal#register application development issues q2 my application is getting the following error “[payresult] cancel” how can i send a question to samsung checkout team? below you can find a sample email that you can send to us through the samsung apps tv seller office 1 1 q&a section tv#error#tv seller office q3 i got the following error in response to the api "/billing/service/v2/paymethods/md" as { "status" "0410424", "result" "оформление покупки не поддерживается [da-0219-a7af33]", "resultlongmesg" "unavailable service support country ", "resulttitle" "недоступно" } what's wrong? the "md" at the end is the country code for "md moldova, republic of", which is not a supported country for the samsung checkout service to see all the list of country where samsung checkout is supported, go to the "country and currency codes" section in implementing the purchase process tv#error#country code q4 can i test how samsung checkout client works without registering the product on dpi? yes, you can use the information below in your test application to see how samsung checkout client works on the tv before using this information, set your tv's country setting to a supported country like the us in addition, make sure that the test information is only used at the development stage before setting up your own dpi, it must not be used in any real service parameter value appid 3201504002021 paymentserver dev paymentdetails orderitemid dp111000001962 ordertitle 0708_consumable ordertotal 1 5 ordercurrencyid usd table 1 buyitem method request parameters sample code var appid = "3201504002021"; var paymentserver = "dev"; var detailobj = new object ; detailobj orderitemid = "dp111000001962"; detailobj ordertitle = "0708_consumable"; detailobj ordertotal = "1 5"; detailobj ordercurrencyid = "usd"; detailobj ordercustomid = ""; var paymentdetails = json stringify detailobj ; var onsuccess = function data { }; var onerror = function error { }; webapis billing buyitem appid, paymentserver, paymentdetails, onsuccess, onerror ; tv#samsung checkout#register#dpi portal q5 if a user purchases a product which has only been made available in a single country, can that purchase be returned using the "invoice/list" endpoint even if it is using a different country code than the one the user purchased the product in? yes the response for "invoice/list" does not consider the country code of the api request parameter, it returns all of the purchases what the buyer has purchased regardless of country tv#purchase#refund#country code#endpoint q6 is there a checklist that i can follow in order to check if my application is integrating with samsung checkout api properly? yes, below is the minimum checklist for integration with samsung checkout, you can test each item in the checklist to make sure your application works properly when purchasing the product when the samsung checkout client is launched, it shows the loading by itself, no graphical overlapping should exist in user experiences during the transition for example, a 3rd party application should not show loading when launching the samsung checkout client check the purchase process based on the type of product consumable/dynamic item type the user should be able to use the appropriate payment method to buy the item, and the title and price on the purchase page should be same as intended subscription/free trial item type in addition to the above, the user should be able to see the next payment date or relevant information of the subscription item check the post-purchase process in the 3rd party application does the 3rd party application reflect the result of a purchase in the application properly after completing the purchase process? both the success case for a purchase and other cases should be handled is there any overlap when screen is switched from the samsung checkout client to the 3rd party application? check the purchase history based on the type of product go to the "tv menu > samsung account > payment info" to see the subscription or purchase history the user needs to be able to check the purchase history or subscriptions of the item the user needs to be able to check subscription details check the user purchase history from the user buyer portal to make sure the history is properly updated after making a purchase, go to the samsung checkout website and check whether your status is updated properly test for exceptions turn off the tv while the purchase is in progress and checks if any inappropriate status is observed for example, go to the "tv menu > samsung account > payment info" to see the subscriptions or purchase history after completing the purchase of the item, turn the tv off and on again and run the 3rd party application to see if the previous purchase is still in active status tv#checklist#api integration dpi portal usage guide from the dpi portal, partners can register and manage products for sale and access the transaction history logs and sales reports for the applications they own q7 how do price changes work? if you want to change the price of an existing item, go to the dpi site and select "app > product list on the left side > product id" from there, you can change the product price for countries where it is necessary to select a tax category, you need permission from the samsung administrator to change the price prices you set can be changed after three months and you must notify the consumers of the new price tv#price change#dpi portal q8 can we have a unique product for each country? when a buyer purchases a specific product which is sold in multiple countries, they have the right to access any of those versions therefore, if you want to give a right for the purchase only within a single country, you need to register products separately for each country the product id needs to be different tv#product id#register q9 are security keys tied to the appid value? for example, if we have 2 applications each with their own id, will each one have its own securitykey? this is correct, security keys are bound to the appid tv#security key#application id q10 when we login on the dpi site, our application is not listed on it how can we add it? when you enroll your application on the seller site, you need to check the appropriate options for using samsung checkout refer to the picture below tv#dpi portal#unlisted application q11 how long does it take to get approval to use the dpi site? for the staging zone development , approval takes a maximum of 2 days for the operating zone, contract terms and conditions need to be finalized between you and samsung before approval can be granted tv#approval#staging zone#operating zone operation of your service this section explains the issues related to the operation of your service q12 can i use samsung checkout service for hotel tv applications? no, samsung checkout service is available on only samsung smart tvs htv#hotel tv application#samsung checkout q13 can i use my tv to test samsung checkout? i bought samsung smart tv around 2016 yes, samsung checkout service is available since the 2016 samsung smart tv range however, the latest features are guaranteed to function only for the last three years, and there may be a difference in the functionality of each year tv#samsung checkout testing q14 does samsung send push notifications, e-mail, or any sort of messaging to users throughout the service lifecycle free trial, subscribe, cancel ? samsung sends an e-mail to users who buy items, subscribe, cancel, and refund in addition, samsung sends a notice e-mail to users whose subscription item payment has failed tv#notice emails q15 is there any additional information you can pass along on error response codes for the billing api, such as what the response is if the checkvalue is incorrect? yes, you can find additional information at the following page dpi > support > error code tv#billing api#error code q16 what happens to current users who are in the middle of their subscription, when cp changes the price? will the user get some notification when they renew next time? no the service provider must relay this information to the buyers before the changes are made, because samsung checkout does not send price change notifications to buyers who subscribe to subscription products tv#price change#notification q17 does the samsung checkout charge users based on local currency, or based on the credit card that is used? for example, can you pay with us credit card in columbia? will the card be charged in local currency, or in usd? you will be charged in local currency tv#local currency q18 what are "customid" and "ordercustomid"? "customid" and "ordercustomid" have the same value "customid" also uses the same value as "ordercustomid" when calling buyitem if you have a unique id, use it if not, use the samsung account uid tv#customid#ordercustomid q19 how is the provider's user account data matched with samsung checkout's transaction list? this is done using "ordercustomid" if the provider has a user account, they can put the value in the "ordercustomid" parameter when calling the buyitem api this value is mapped to the transaction list's "order custom id" column tv#ordercustomid#transaction list product type this section includes information related to product types that can be purchased using the samsung checkout service limited period q20 in the response data of the "invoice/list" api, are `period`, `appliedtime`, `limitendtime`, and `remaintime` always present for `invoicedetails` objects that have an `itemtype` of limited period? yes tv#limited period#invoice details#item type q21 in the api spec document for the response data of "invoice/list" api, `limitendtime` is listed as "limited period product end time, in 14-digit utc time" does this mean that the field is not mandatory, that it should either exist and be a 14-digit string, or that it should not exist? no, limitendtime must exist when a limited period product is applied tv#limited period#limited end time q22 from the response data of "invoice/list" api, what is the expected value of the `limitendtime` field when a purchase hasn’t been applied yet? it appears that for limited period item purchases that have not been applied `itemtype` is "3" , the `limitendtime` field is set to "" correct limitendtime is calculated based on the date and time when the purchase is applied tv#limited period#limited end time#item type subscription q23 in the response data of the "invoice/list" api, is `subscriptioninfo` ever present for `invoicedetails` objects that do not have an `itemtype` of subscription? subscriptioninfo is shown only when itemtype is subscription tv#subscription info#invoice details#item type q24 does an invoiceid ever change, or is it static? if a new purchase is made, does it always generate a new invoiceid? the invoiceid is generated when the buyer subscribes to a product for regular payment however, subscriptionid is generated only when the buyer subscribes a product for the first time samsung checkout uses the first invoiceid as the subscriptionid and it is never updated tv#invoiceid#subscriptionid q25 does subscription end date `subsendtime` get updated as soon as a user has been successfully billed for the upcoming period of the subscription? no, the subscription end date subsendtime describes the expiry time of this subscription not nextpaymenttime tv#subscription end time q26 how is a month defined in subscriptions? calendar month or 30/31 days? calendar month the next month's payment is made on the same day of the month as the day the consumer first applied for the subscription for example, if the consumer applied for a subscription on november 14th, the next payment is made on december 14th for months that don't have a day corresponding to the settlement date such as the 31st , payment is made at the end of the month tv#calendar month#subscription q27 would the canceling of a subscription/closing of the account automatically trigger a refund at samsung checkout? no even if the consumer withdraws their samsung account or cancels a subscription to the regular payment, this does not refund any payments already charged on the next settlement date, the subscription status is changed from 'active' to 'expired', and regular payment is stopped tv#subscription#samsung account#cancel#refund
Develop Samsung IAP
docsamsung iap isn payload the samsung in-app purchase iap instant server notification isn contains registered and private claims because event types and content within the payload is continually added content that already exists is not deleted , handling the notifications that are sent to your server requires some flexibility the payload is encoded in base64 format when it is decoded, it is in json format the following events are reported in the notification and are explained in the data claims section below item purchased item refunded subscription started subscription ended subscription upgraded/downgraded subscription refunded subscription renewed resubscription subscription price change accepted subscription in grace period subscription not in grace period order history deleted test example encoded payload eyjpc3mioijpyxauc2ftc3vuz2fwchmuy29tiiwic3viijoirvzftlrftkfnrsisimf1zci6wyjjb20ucgfja2fnzs5uyw1lil0sim5izii6mtcxnziwncwiawf0ijoxnze3mja0lcjkyxrhijp7innlbgxlck5hbwuiom51bgwsimnvbnrlbnroyw1lijoitwfydgluzsj9lcj2zxjzaw9uijoimi4win0 example decoded payload { "iss" "iap samsungapps com", "sub" "event_name", "aud" [ "com package name" ], "nbf" 1717204200, "iat" 1717204200, "data" { }, "version" "2 0" } claims set properties claim name claim type value type description iss registered string always iap samsungapps com sub registered string type of event that occurred item_purchased the user successfully purchased the product item_refunded the purchased product is refunded to the customer ars_subscribed the subscription has started ars_unsubscribed the subscription has ended or is cancelled ars_updowngraded the subscription is upgraded to a more expensive plan or downgraded to a cheaper one ars_refunded the subscription payment, at any point during the current subscription period, is refunded to the subscriber ars_renewed the subscription has been renewed by the subscriber ars_resubscribed the subscription was cancelled but is restored by the subscriber before it expires ars_pricechange_agreed the subscriber has consented or not consented to a subscription price change ars_in_grace_period the subscription is in a grace period, allowing the subscriber time to update their payment method and renew the subscription ars_out_grace_period the subscription is not in a grace period order_history_deleted the listed order details are deleted receipts and subscriptions cannot be retrieved using the specified id test this is a test notification sent using seller portal aud registered string the package name of the content iat registered number the time at which the jwt was issued unix epoch time nbf registered number the time at which the jwt can be accepted for processing unix epoch time data private json detailed payload for each notification based on the event type sub see data claims for more information about the data claims payload version private string the version of the samsung iap isn service the current version, which is jwt-based, is 2 0 data claims the following are the data claims that may be included in the isn, based on the event type item purchased item refunded subscription started subscription ended subscription upgraded/downgraded subscription refunded subscription renewed resubscription subscription price change accepted subscription in grace period subscription not in grace period order history deleted test item purchased the user successfully purchased the item example "data" { "itemid" "one_gallon_gas", "orderid" "s20240601kra0010001", "purchaseid" "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37", "testpayyn" "n", "betatestyn" "n", "obfuscatedaccountid" "b2jmdxnjyxrlzefjy291bnrjza==", "obfuscatedprofileid" "b2jmdxnjyxrlzfbyb2zpbgvjza==" } properties name value description itemid string id of product purchased orderid string order id on the receipt delivered to the user purchaseid string the purchase id you used with the receipt verification api testpayyn string y the product was purchased by a licensed tester in iap test mode n the product was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the product was purchased during a closed beta test n the product was not purchased during a closed beta test see iap test mode conditions for more information passthroughparam string optional transaction id you created as a security enhancement when requesting a payment, and is delivered only when entered when requesting a payment obfuscatedaccountid string optional obfuscated account id which you sent when you called startpayment or changesubscriptionplan obfuscatedprofileid string optional obfuscated profile id which you sent when you called startpayment or changesubscriptionplan item refunded the purchased item is refunded to the customer example "data" { "orderid" "s20240601kra0010001", "purchaseid" "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37", "testpayyn" "n", "betatestyn" "n" } properties name value description orderid string order id on the receipt delivered to the user purchaseid string the purchase id you used with the receipt verification api testpayyn string y the product was purchased by a licensed tester in iap test mode n the product was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the product was purchased during a closed beta test n the product was not purchased during a closed beta test see iap test mode conditions for more information subscription started the subscription has started example "data" { "itemid" "weekly_fuel", "orderid" "s20240601kra0010009", "purchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "paymentplan" "regular", "scheduledtimeofrenewal" 1717809005, "validuntil" 1717809005, "testpayyn" "n", "betatestyn" "n" "obfuscatedaccountid" "b2jmdxnjyxrlzefjy291bnrjza==", "obfuscatedprofileid" "b2jmdxnjyxrlzfbyb2zpbgvjza==" } properties name value description itemid string id of subscription purchased orderid string order id on the receipt delivered to the user purchaseid string the purchase id you used with the receipt verification api paymentplan string product plan applied to the current user for example, freetrial / tieredprice / regular scheduledtimeofrenewal number the next subscription renewal date, in unix epoch time validuntil number the subscription expiration date, in unix epoch time if testpayyn=n and betatestyn=n, scheduledtimeofrenewal and validuntil have the same value if testpayyn=y or betatestyn=y, then scheduledtimeofrenewal and validuntil may have different values testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information obfuscatedaccountid string optional obfuscated account id which you sent when you called startpayment or changesubscriptionplan obfuscatedprofileid string optional obfuscated profile id which you sent when you called startpayment or changesubscriptionplan subscription ended the subscription has ended or is cancelled and is not renewed the subscription is still available until the end of the current subscription period example "data" { "firstorderid" "s20240601kra0010009", "firstpurchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "testpayyn" "n", "betatestyn" "n", "validuntil" 1717809005 } properties name value description firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information validuntil number the subscription expiration date, in unix epoch time subscription upgraded/downgraded the subscription plan has been changed to a more expensive plan upgrade or to a cheaper plan downgrade example "data" { "olditemid" "sample_basic_1", "oldpaymentplan" "regular", "oldorderid" "s20250508kr345251678" "oldpurchaseid" "ae1a28300c91d6687949ce1507f7f99b3d6770ac30e01c1684210531ed7" "newitemid" "sample_premium_1", "newpaymentplan" "regular", "neworderid" "s20250808kr01958723", "newpurchaseid" "e580060396cfeedc951f848dj385h4aff684cb76cce5a21efba3a86efad6d53e", "scheduledtimeofrenewal" 1755217332, "validuntil" 1755217332, "testpayyn" "n", "betatestyn" "n" } properties name value description olditemid string the id of the subscription purchased before the subscription change oldpaymentplan string the payment plan of the product applied to the user before the subscription change for example, freetrial / tieredprice / regular oldorderid string order id of the first purchase of the original product oldpurchaseid string purchase id of the first purchase of the original product newitemid string the id of the subscription purchased after the subscription change newpaymentplan string the subscription plan of the product applied to the user after the subscription change for example, freetrial / tieredprice / regular neworderid string order id for the purchase of the changed product newpurchaseid string purchase id for the purchase of the changed product scheduledtimeofrenewal number the next subscription renewal date, in unix epoch time validuntil number the subscription expiration date, in unix epoch time if testpayyn=y and betatestyn=y, scheduledtimeofrenewal and validuntil have the same value if testpayyn=y or betatestyn=y, then scheduledtimeofrenewal and validuntil may have different values testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information subscription refunded the subscription payment, at any point during the current subscription period, is refunded to the subscriber example "data" { "firstorderid" "s20240601kra0010009", "firstpurchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "refundedorderid" "s20240608kra0110009", "refundedpurchaseid" "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e", "refundedpurchasedate" 1596573209, "testpayyn" "n", "betatestyn" "n" } properties name value description firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api refundedorderid string the order id of the refunded payment refundedpurchaseid string the purchase id of the refunded payment refundedpurchasedate number the purchase date of the refunded payment, in unix epoch time testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information subscription renewed the subscription has been renewed by the subscriber example "data" { "itemid" "weekly_fuel", "firstorderid" "s20240601kra0010009", "firstpurchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "renewedorderid" "s20240608kra0110009", "renewedpurchaseid" "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e", "paymentplan" "regular", "scheduledtimeofrenewal" 1720415824, "validuntil" 1721884624, "testpayyn" "y", "betatestyn" "n" } properties name value description firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api renewedorderid string the order id of the most recent renewal payment renewedpurchaseid string the purchase id of the most recent renewal payment paymentplan string the product plan applied to the current subscriber for example, freetrial / tieredprice / regular scheduledtimeofrenewal number the next subscription renewal date, in unix epoch time validuntil number the subscription expiration date, in unix epoch time if testpayyn=n and betatestyn=n, scheduledtimeofrenewal and validuntil have the same value if testpayyn=y or betatestyn=y, then scheduledtimeofrenewal and validuntil may have different values testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information resubscription the subscription was cancelled but the subscriber restarted it before it expired or revoked the cancellation to maintain the subscription's active status example "data" { "itemid" "sub_sample_1", "resubscribedorderid" "s20250808kr01945643", "resubscribedpurchaseid" "a5f910c979f84cee7c075a496c6a280413rt468ce413904e978a617550296ef2", "paymentplan" "regular", "testpayyn" "n", "betatestyn" "n", "scheduledtimeofrenewal" 1755240697, "validuntil" 1755240697 } properties name value description itemid string the id of the purchased subscription resubscribedorderid string the order id of the resubscription payment resubscribedpurchaseid string the purchase id of the resubscription payment paymentplan string the subscription plan of the product applied to the user after resubscription for example, freetrial / tieredprice / regular testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information scheduledtimeofrenewal number the next subscription renewal date, in unix epoch time validuntil number the subscription expiration date, in unix epoch time if testpayyn=n and betatestyn=n, scheduledtimeofrenewal and validuntil have the same value if testpayyn=y or betatestyn=y, then scheduledtimeofrenewal and validuntil may have different values subscription price change accepted the subscriber has consented or not consented to a subscription price change example "data" { "itemid" "weekly_fuel", "firstorderid" "s20240601kra0010009", "firstpurchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "agreeyn" "y", "testpayyn" "n", "betatestyn" "n" } properties name value description itemid string id of subscription purchased firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api agreeyn string y the subscriber consented to the subscription price increase and the subscription will be renewed at the increased price at the beginning of the subscription period when the price increase is applied n the subscriber did not consent to the subscription price increase and the subscription will be cancelled at the end of the final subscription period that charges the current price testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information subscription is in a grace period there is an issue with the subscriber's payment method and the subscriber is given time to update their payment method before the subscription is cancelled example "payload" { "itemid" "ars_with_tiered", "firstorderid" "s20210126gba1918788", "firstpurchaseid" "5665c5e42e1888fe82cd57111f5f8374a87f96623585ffef9bc03a58cecca508", "testpayyn" "y", "betatestyn" "n", "graceperiodstartdate" 1720415824, "graceperiodenddate" 1721020624 } properties name value description itemid string id of subscription purchased firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information graceperiodstartdate number starting date of the grace period, in unix epoch time graceperiodenddate number ending date of the grace period, in unix epoch time subscription is not in a grace period the subscription is not in a grace period example "payload" { "itemid" "ars_with_tiered", "firstorderid" "s20210126gba1918788", "firstpurchaseid" "5665c5e42e1888ee87cd57111f5f8674a87f96623585ffef9bd03a58cecca508", "renewedorderid" "s20200805kra1910361", "renewedpurchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2", "paymentplan" "regular", "scheduledtimeofrenewal" 1720415824, "validuntil" 1720415824, "testpayyn" "n", "betatestyn" "n" } properties name value description itemid string id of subscription purchased firstorderid string the order id on the first receipt delivered to the subscriber firstpurchaseid string the purchase id you used with the receipt verification api renewedorderid string the order id of the most recent renewal payment renewedpurchaseid string the purchase id of the most recent renewal payment paymentplan string the product plan applied to the current subscriber for example, freetrial / tieredprice / regular scheduledtimeofrenewal number the next subscription renewal date, in unix epoch time validuntil number the subscription expiration date, in unix epoch time if testpayyn=n and betatestyn=n, scheduledtimeofrenewal and validuntil have the same value if testpayyn=y or betatestyn=y, then scheduledtimeofrenewal and validuntil may have different values testpayyn string y the subscription was purchased by a licensed tester in iap test mode n the subscription was purchased in iap production mode see iap test mode conditions for more information betatestyn string y the subscription was purchased during a closed beta test n the subscription was not purchased during a closed beta test see iap test mode conditions for more information order history deleted delete order details when the order details are deleted, receipt and subscription information for the specified order and purchase ids are no longer available example "data" { "count" 3, "orderlist" [ { "orderid" "s20240601kra0010001", "purchaseid" "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37" }, { "orderid" "s20240601kra0010009", "purchaseid" "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2" }, { "orderid" "s20240608kra0110009", "purchaseid" "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e" } ] } properties name value description orderid string order id on the receipt delivered to the user purchaseid string the purchase id you used with the receipt verification api test this is a test notification sent using seller portal example "data" { "sellername" "martine", "contentname" "driving game" } properties name value description sellername string the name of the person selling the product contentname string the name of the product iap test mode conditions the following table describes the conditions status of content in seller portal and the iap operating mode that apply for the testpayyn and betatestyn property values content status in seller portal registering with licensed tester closed beta for sale iap operating mode operation_mode_test operation_mode_production testpayyn y n betatestyn n y n
Distribute Samsung IAP for Galaxy Watch (Tizen)
docnative iap for galaxy watch samsung in-app purchase iap for galaxy watch is a galaxy store service that allows third-party watch applications to sell in-app items iap for galaxy watch only works if your galaxy watch is paired with your phone the iap client for watch communicates with the iap client for phone, which internally manages communication with supporting iap services and the samsung ecosystem such as samsung account, samsung checkout, and samsung rewards in other words, it acts as an intermediary between the watch app and samsung iap phone system you can concentrate on integrating iap api calls and iap server api calls into your watch app to integrate iap for galaxy watch using tizen extension sdk, iap native apis enables you to easily integrate iap functionality into your watch app, such as configuring iaps, getting item details, offering and selling items, and managing purchased items using galaxy watch studio formerly galaxy watch designer , you can make your own watch face that prompts for payment after a free trial period, without the complexity of coding for more details, see the galaxy watch studio online tutorial by integrating iap features, your watch apps can sell these types of in-app items item type description consumable app users can use items only one time for example, coins, special powers, or gems nonconsumable app users can use items any number of times for example, e-books or game boards items cannot be repurchased noteduring iap integration testing, if your application is set to test mode, the purchase record is initialized every 60 minutes to allow repurchase autorecurring subscription these items are purchased automatically at specific intervals app users can access items such as magazines, e-zines, or newspapers any number of times during a free trial or while their paid subscriptions are active app users can cancel at any time after purchase during subscription period app users can repurchase items after cancellation noteduring iap integration testing, if your application is set to test mode, the subscription cycle is automatically renewed every 10 minutes, and the subscription is automatically canceled after 12 renewals integrate iap into your watch app this section explains how to prepare your app to sell in-app items using tizen extension sdk you can use galaxy watch studio to make a watch face that prompts for payment after a free trial period, without the complexity of coding see the galaxy watch studio online tutorial for more information to prepare for integrating iap features and testing the integration, perform the following steps 1 create a project create a project in tizen studio the application api version must be at least 2 3 2 in the tizen-manifest xml file <?xml version="1 0" encoding="utf-8" standalone="no"?> <manifest xmlns="http //tizen org/ns/packages" api-version="4 0 0" package="org tizen nativeiap" version="1 0 0"> </manifest> 2 add permissions to tizen-manifest xml <privileges> <privilege>http //tizen org/privilege/billing</privilege> </privileges> 3 register app and in-app items in seller portal during iap integration, you may need to test iap features samsung iap needs information about your app and in-app items registered in seller portal noteyour app does not need to have iap features integrated in order to register the app and its in-app items as iap integration proceeds, you can upload new versions of your app and new in-app items as needed to register an app and its in-app items sign in to seller portal https //seller samsungapps com using your samsung account click add new application click galaxy watch, select the default language, and click next in the binary tab, upload your app tpk in the app information tab, enter fundamental app details in the country / region & price tab, specify a free or paid app, a paid app price, and countries to sell your items in the in app purchase tab, register one or more in-app items cautiondon't click *submit beta test * or *submit * in this step 4 integrate iap features #include <iap-galaxyapps h> get in-app items available for purchase purchase an in-app item get a list of purchased items operation mode iap supports three operational modes one is for enabling billing for item purchases, and the other two are for testing iap functions without billing app users for item purchases mode description iap_galaxyapps_commercial_mode financial transactions do occur for successful requests, and actual results are returned successful or failed the app gets in-app item information of the app whose status in seller portal is for sale iap_galaxyapps_success_test_mode financial transactions do not occur app users are not billed for item purchases , and successful results are always returned the app gets in-app item information of the app whose status in seller portal is registering or updating iap_galaxyapps_failure_test_mode all iap requests fail negative testing to ensure that your app can handle errors such as improper input and user actions notethe tizen emulator only supports these two modes iap_galaxyapps_success_test_mode iap_galaxyapps_failure_test_mode if you set the mode to iap_galaxyapps_commercial_mode, it is automatically changed to iap_galaxyapps_success_test_mode get in-app items available for purchase to get all registered in-app items from galaxy store, use the iap_galaxyapps_get_item_list method pass in the index of the first and last item, the item type, service mode, callback function, and user data as parameters when the reply is delivered, the iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results to get the request result from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value method if the request was successful, you can get all the item details from the iap_galaxyapps_h object using the iap_galaxyapps_foreach_item_info method request for details, see the iap_galaxyapps_get_item_list int iap_galaxyapps_get_item_list int start_number, int end_number, const char *item_type, iap_galaxyapps_mode_e mode, iap_galaxyapps_reply_cb reply_cb, void *user_data response typedef void * iap_galaxyapps_reply_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data common result key value type description merrorcode int error code number merrorstring string error message mextrastring string extra result mstartnumber int index of the first item on the list mendnumber int index of the last item on the list mtotalcount int total number of items based on the first and last item index item details key value type description mitemid string item id numberthis is the same as the item id used in the request mitemname string name provided during the item registration in the seller portal mitemprice string item price in a local currency mitempricestring string currency code + pricefor example €7 99 mcurrencyunit string device user currency unit for example $, won, or pound mcurrencycode string currency codefor example eur or gbp mitemdesc string item description provided during the item registration mitemimageurl string item image url provided during the item registration mitemdownloadurl string item download url provided during the item registration mtype string item type 00 consumable01 non-consumable02 non-recurring subscription03 auto-recurring subscription 10 all msubscriptiondurationunit string subscription duration unit, defined as an upper case string month msubscriptiondurationmultiplier string if the item type mtype is 02 or 03, this is the item duration combined with msubscriptiondurationunit, it expresses the subscription duration, for example, 1month mjsonstring string original json string code snippet to handle the request output data, define a structure for it struct output_data { char* merrorcode; char* merrorstring; char* mextrastring; char* mstartnumber; char* mendnumber; char* mtotalcount; char* mitemid; char* mitemname; char* mitemprice; char* mitempricestring; char* mcurrencyunit; char* mcurrencycode; char* mitemdesc; char* mitemimageurl; char* mitemdownloadurl; char* mpaymentid; char* mpurchaseid; char* mpurchasedate; char* mverifyurl; char* mtype; char* msubscriptiondurationunit; char* msubscriptiondurationmultiplier; char* msubscriptionenddate; char* mjsonstring; }; typedef struct output_data_s; request the available items, and retrieve the item details in the reply callback /* request the available item list */ int ret = iap_galaxyapps_get_item_list 1, 10, "10", iap_galaxyapps_commercial_mode, __get_item_list_cb, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } static bool __foreach_item iap_galaxyapps_h handle, void *user_data { output_data value = {0,}; /* get item properties */ iap_galaxyapps_get_value handle, "mitemid", &value mitemid ; iap_galaxyapps_get_value handle, "mitemname", &value mitemname ; iap_galaxyapps_get_value handle, "mitempricestring", &value mitempricestring ; iap_galaxyapps_get_value handle, "mitemdesc", &value mitemdesc ; /* handle properties */ return true; } /* callback */ static void __get_item_list_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data { if result != iap_galaxyapps_error_none { char *merrorstring = null; iap_galaxyapps_get_value reply, "merrorstring", &merrorstring ; /* error handling */ return; } /* retrieve all items contained in the handle */ int ret = iap_galaxyapps_foreach_item_info reply, __foreach_item, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } return; } purchase an in-app item to purchase items from galaxy store, use the iap_galaxyapps_start_payment method pass in the index of the item id, service mode, callback function, and user data as parameters when the reply is delivered, the iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results to get both the request result and the purchased item details from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value method request for details, see the iap_galaxyapps_start_payment int iap_galaxyapps_start_payment const char *item_id, iap_galaxyapps_mode_e mode, iap_galaxyapps_reply_cb reply_cb, void *user_data response typedef void * iap_galaxyapps_reply_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data common result key value type description merrorcode int error code number merrorstring string error message mextrastring string extra result purchased item details key value type description mitemid string item id numberthis is the same as the item id used in the request mitemname string name provided during the item registration in the seller office mitemprice double item price in a local currency mitempricestring string currency code + pricefor example €7 99 mcurrencyunit string device user currency unitfor example $, won, or pound mcurrencycode string currency codefor example eur or gbp mitemdesc string item description provided during the item registration mitemimageurl string item image url provided during the item registration mitemdownloadurl string item download url provided during the item registration mpaymentid string id of the payment mpurchaseid string purchase ticket id used to verify the purchase with the store iap server mpurchasedate string date of purchasefor example "2020-11-15 10 31 23" mverifyurl string server's url, which can be used in combination with other parameters to verify the purchase with the iap server mjsonstring string original json string code snippet /* purchase an item */ int ret = iap_galaxyapps_start_payment "item_id", iap_galaxyapps_commercial_mode, __purchase_cb, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } /* callback */ static void __purchase_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data { output_data value = {0,}; if result != iap_galaxyapps_error_none { iap_galaxyapps_get_value reply, "merrorstring", &value merrorstring ; /* error handling */ return; } /* get properties of the purchased item */ iap_galaxyapps_get_value reply, "mitemid", &value mitemid ; iap_galaxyapps_get_value reply, "mitemname", &value mitemname ; iap_galaxyapps_get_value reply, "mitempricestring", &value mitempricestring ; iap_galaxyapps_get_value reply, "mitemdesc", &value mitemdesc ; /* handle properties */ return; } get a list of purchased items to get a list of all items purchased from galaxy store, use the iap_galaxyapps_get_purchased_item_list or iap_galaxyapps_get_purchased_item_list_by_item_ids method for iap_galaxyapps_get_purchased_item_list , pass in the index of the first and last item, the item type, the start and end date, the callback function, and user data as parameters for iap_galaxyapps_get_purchased_item_list_by_item_ids , pass in the item ids separated by comma , , the callback function, and user data as parameters when the reply is delivered, the iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results to get the request result from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value method if the request was successful, you can get all the item details from the iap_galaxyapps_h object using the iap_galaxyapps_foreach_item_info method request for details, see the iap_galaxyapps_get_purchased_item_list and iap_galaxyapps_get_purchased_item_list_by_item_ids int iap_galaxyapps_get_purchased_item_list int start_number, int end_number, const char *start_date, const char *end_date, iap_galaxyapps_reply_cb reply_cb, void *user_data int iap_galaxyapps_get_purchased_item_list_by_item_ids const char *item_ids, iap_galaxyapps_reply_cb reply_cb, void *user_data response typedef void * iap_galaxyapps_reply_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data common result key value type description merrorcode int error code number merrorstring string error message mextrastring string extra result mstartnumber int index of the first item on the list mendnumber int index of the last item on the list mtotalcount int total number of items based on the first and last item index purchased item details key value type description mitemid string item id numberthis is the same as the item id used in the request mitemname string name provided during the item registration in the seller portal mitemprice string item price in a local currency mitempricestring string currency code + price mcurrencyunit string device user currency unit mcurrencycode string currency code mitemdesc string item description provided during the item registration mitemimageurl string item image url provided during the item registration mitemdownloadurl string item download url provided during item registration mtype string item type 00 consumable01 nonconsumable02 nonrecurring subscription03 autorecurring subscription10 all mpaymentid string id of the payment mpurchaseid string id of the purchase mpurchasedate string date of purchasefor example "2020-11-15 10 31 23" msubscriptionenddate string if the item type mtype is 02 or 03, this is the due date mjsonstring string original json string code snippet int ret = iap_galaxyapps_get_purchased_item_list 1, 10, "20200101", "20221231", __get_purchased_item_list_cb, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } // item ids can be obtained by seperating the values returned by the iap_galaxyapps_get_item_list with comma , int ret = iap_galaxyapps_get_purchased_item_list_by_item_ids "item1,item2,item3", __get_purchased_item_list_cb, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } static bool __foreach_purchased_item iap_galaxyapps_h handle, void *user_data { output_data value = {0,}; /* get properties of the item */ iap_galaxyapps_get_value handle, "mitemid", &value mitemid ; iap_galaxyapps_get_value handle, "mitemname", &value mitemname ; iap_galaxyapps_get_value handle, "mitempricestring", &value mitempricestring ; iap_galaxyapps_get_value handle, "mitemdesc", &value mitemdesc ; /* handle properties */ return true; } /* callback */ static void __get_purchased_item_list_cb iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data { if result != iap_galaxyapps_error_none { char *merrorstring = null; iap_galaxyapps_get_value reply, "merrorstring", &merrorstring ; /* error handling */ return; } /* retrieve all items contained in the handle */ int ret = iap_galaxyapps_foreach_item_info reply, __foreach_purchased_item, null ; if ret != iap_galaxyapps_error_none { /* error handling */ return; } return; } handling errors during the iap process, various errors can occur, for example, due to an unstable network, connection error, invalid account, or invalid product if an error occurs, your application receives the iap_galaxyapps_error_e error type in the iap_galaxyapps_reply_cb callback handle all errors appropriately error code error code description iap_galaxyapps_error_none successful iap_galaxyapps_error_payment_is_canceled payment canceled iap_galaxyapps_error_network_not_available network is not available iap_galaxyapps_error_io_error ioexception iap_galaxyapps_error_timed_out timeout exception iap_galaxyapps_error_initialization failure during iap initialization iap_galaxyapps_error_need_app_upgrade samsung iap upgrade is required iap_galaxyapps_error_common error while running iap iap_galaxyapps_error_already_purchased error when a non-consumable product is repurchased or a subscription product is repurchased before the product expiration date iap_galaxyapps_error_request_payment_without_info error when payment is requested without bundle information iap_galaxyapps_error_product_does_not_exist error when the requested item list is not available iap_galaxyapps_error_confirm_inbox the payment result is not received after requesting payment from the server, and the purchased item list is not confirmed iap_galaxyapps_error_not_exist_local_price the item is not for sale in the country iap_galaxyapps_error_not_available_shop iap is not supported in the country iap_galaxyapps_error_invalid_parameter invalid parameter iap_galaxyapps_error_key_not_found specified key is not found iap_galaxyapps_error_not_supported_device the device does not support iap iap_galaxyapps_error_out_of_memory out of memory iap_galaxyapps_error_permission_denied permission denied verify a purchase this server api enables your server and client app to verify that a specified in-app item purchase and payment transaction were successfully completed the api returns a json object with a successful status and details about a successful transaction and the item or with a failure status this api can help to prevent malicious purchases and ensure that purchase and payment transactions were successful when the client app experiences network interruptions after an item purchase and payment transaction request https //iap samsungapps com/iap/appsitemverifyiapreceipt as?protocolversion=2 0&purchaseid={purchaseid} the purchaseid is assigned by samsung iap your app receives it in the iap_galaxyapps_h object as response of iap_galaxyapps_start_payment and the key is mpurchaseid response noteresponse parameters may be added, changed, and deleted success { "itemid" "item01", "paymentid" "zpmtid20131122gbi0015292", "orderid" "s20200106kra1908790", "itemname" "test pack", "itemdesc" "iap test item best value!", "purchasedate" "2020-11-22 04 22 36", "paymentamount" "9 000", "status" "true", "paymentmethod" "credit card", "mode" "real", } fail { "status" "false" } notebesides verifying a purchase, samsung iap server api also obtains service token information and gets detailed information of an autorecurring subscription item purchase submit the app to galaxy store 1 check the operation mode after iap integration, you must check the operation mode before submitting the app if you submit the app with iap_galaxyapps_success_test_mode, the users will get all the items for free so, before beta release or normal publication, confirm if the operation mode is iap_galaxyapps_commercial_mode 2 submit the app when you have created an app version that is ready for review testing and normal publication, register the app and its in-app item, and then click submit for more details, see the app registration guide
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
You have successfully updated your cookie preferences.