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.
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:
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.
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.
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
"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 period
If 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.
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.
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.
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.
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.
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:
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.
"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.
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_TRIAL
COUPON
"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.
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.
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_TRIAL
COUPON
"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.
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:
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
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:
Table 33. Billing Service Available Country Check API response parameters
Billing API
To implement the Samsung Checkout functionality, use the Billing API.
When the user wants to make a purchase, authenticate the user and show the common purchase GUI with the buyItem() method.
ImportantWhen the buyItem() method is called, the common purchase GUI is shown in the application automatically. Do not change the purchase GUI appearance until the purchase transaction is complete and the application receives the response.
You can customize the product image in Samsung Checkout by providing the URI to an image on your own content server.
Default image
Product image
Table 34. Display your own product image
To implement Samsung Checkout:
var detailObj = new Object();
detailObj.OrderItemID = productsList.ItemDetails[selectedItem].ItemID; // Issued by "cont/list"
detailObj.OrderTitle = productsList.ItemDetails[selectedItem].ItemTitle; // Issued by "cont/list"
detailObj.OrderTotal = productsList.ItemDetails[selectedItem].Price.toString(); // Change data type to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // This value is optional
var UniqueCustomId = "123"; // Unique ID for this user. "123" is an example value. It can be an ID managed by your service.
detailObj.OrderCustomID = UniqueCustomId; // Same value as "CustomID" parameter for "invoice/list"
var paymentDetails = JSON.stringify(detailObj);
webapis.billing.buyItem(appId, serverType, paymentDetails,
function(data) {
// For implemention details, see the Samsung Checkout Sample Application
console.log("[Billing buyItem]: pay_result [" + data.payResult + "], pay_detail [" + data.payDetail + "]");
},
function(error) {
console.log("[Billing buyItem] status:[" + error.code + "] errorName:[" + error.name + "] errorMessage:[" + error.message + "]");
}
);
The buyItem() method request and response data are in JSON format:
Purchase item ID, for example, "DP123400000000". "ItemID" issued by the Products List API. For dynamic products, use this value as "productId" for the Verify Dynamic Product Information API.
"OrderTitle"
100
Purchase item title. "ItemTitle" issued by the Products List API. For dynamic products, use a customized value.
"OrderTotal"
20
Total purchase price. "Price" issued by the Products List API. When converting the number to string type, pay attention to the unit separators. For dynamic products, use a customized value and use it as "productPrice" for the Verify Dynamic Product Information API.
"OrderCurrencyID"
10
Purchase currency unit. "CurrencyID" issued by the Products List API.
"OrderID"
False
50
Management ID for purchases managed by third-party applications
"OrderCustomID"
True
100
Unique customer ID
"OrderItemPath"
False
-
Item image URI. The image must be in JPEG, JPG, or PNG format.
"DynmcProductID"
True (For dynamic products only)
100
Unique ID for the dynamic product from a third-party application. Use this value as "dynmcProductId" for the Verify Dynamic Product Information API.
"DynmcProductInfo"
False
Dynamic product item type, such as rental or permanent purchase. For dynamic products only.
"DynmcShareCategory"
20
Share category. For dynamic products only.
"DynmcTaxCategory"
30
Tax category. For dynamic products only.
"StltAppId"
Settlement application ID. For Samsung internal use only. Do not use.
Table 35. buyItem() request parameters
buyItem() method response parameters:
Parameter
Type
Mandatory
Description
"payResult"
String
True
Possible values:
"SUCCESS"
"FAILED"
"CANCEL": Canceled by the user
"payDetail"
JSON
False
Payment details
"InvoiceID"
String
False
Purchased Invoice ID, for example, "DO1904US000007153". A value is only returned when "payResult" is "SUCCESS".
Table 36. buyItem() response parameters
Note
Dynamic products are also supported by Samsung Checkout.
For more information on offering dynamic products in your application, contact a Samsung representative by going to "Samsung Apps TV Seller Office > Support" and creating a "1:1 Q&A" support ticket.
Verifying Dynamic Product Information
The Verify Dynamic Product Information API ("cp/verify") is only available when the product type is dynamic product. The API checks the dynamic product information between DPI server and CP CMS. The DPI server calls this API when "Verification" is selected in the DPI Portal.
API URL
Operating Zone (PRD): The "Verify URI" entered in the DPI Portal for the operating zone.
Application ID. Same value as the "AppID" parameter for the buyItem() method.
"productId"
Purchase item ID. Same value as the "OrderItemID" parameter for the buyItem() method.
"productPrice"
10
Purchase price (Unit price). Same value as the "OrderTotal" parameter for the buyItem() method.
"productCurrencyCode"
Currency code. Same value as the "OrderCurrencyID" parameter for the buyItem() method.
"orderCustomId"
False
100
Unique customer ID. Same value as the "OrderCustomID" parameter for the buyItem() method.
"dynmcProductID"
True
Unique ID or string to track the product from the third-party application. Same value as the "DynmcProductID" parameter for the buyItem() method.
"dynmcProductInfo"
False
Dynamic product information. Same value as the "DynmcProductInfo" parameter for the buyItem() method.
"dynmcShareCategory"
20
Share category for the dynamic product. Same value as the "DynmcShareCategory" parameter for the buyItem() method.
"dynmcTaxCategory"
30
Tax category for the dynamic product. Same value as the "DynmcTaxCategory" parameter for the buyItem() method.
Table 37. Verify Dynamic Product Information API request parameters
Verify Dynamic Product Information API response parameters:
Parameter
Type
Mandatory
Length
Description
"status"
String
True
9
Result code:
"100000": Success
"ErrorCode": Failure
For error code details, see the embedded Error Code file.
"result"
100
Result message to be displayed:
"Success" or other short error message
"resultLongMesg"
False
200
Detailed error message when debug mode is active
Table 38. Verify Dynamic Product Information API response parameters
DPI Result Codes
The following table lists result codes and messages that are returned by the DPI service.
Result Code
Result Message
Description
100000
"SUCCESS"
Additional messages:
"hasNext:TRUE": Product list or purchase history has further pages
"EOF": Last page of the product list or purchase history
"Your Invoice Not Found": No purchase history exists
400111
"AppID not correct"
Requested application ID does not exist
Table 39. DPI result codes and messages
For explanations of additional DPI result codes, at the DPI portal, go to "Help > Error Code".
Country and Currency Codes
The following table lists countries with their corresponding country code, currency, and currency code.
Country Name
Country Code (ISO3166-1 alpha-2)
Currency
Currency Code (ISO 4217)
Aland Islands
AX
Euro
EUR
Albania
AL
United States dollar
USD
Algeria
DZ
Algerian dinar
DZD
Argentina
AR
Argentinian peso
ARS
Australia
AU
Australian dollar
AUD
Austria
AT
Euro
EUR
Bahrain
BH
Bahraini dinar
BHD
Belarus
BY
Belarusian ruble
BYN
Belgium
BE
Euro
EUR
Bolivia
BO
United States dollar
USD
Bosnia and Herzegovina
BA
United States dollar
USD
Brazil
BR
Brazilian real
BRL
Bulgaria
BG
Bulgarian lev
BGN
Canada
CA
Canadian dollar
CAD
Chile
CL
Chilean peso
CLP
Colombia
CO
Colombian peso
COP
Costa Rica
CR
United States dollar
USD
Croatia
HR
Euro
EUR
Czechia
CZ
Czech koruna
CZK
Denmark
DK
Danish krone
DKK
Dominican Republic
DO
United States dollar
USD
Ecuador
EC
United States dollar
USD
Egypt
EG
Egyptian pound
EGP
Estonia
EE
Euro
EUR
Faroe Islands
FO
Danish krone
DKK
Finland
FI
Euro
EUR
France
FR
Euro
EUR
Germany
DE
Euro
EUR
Greece
GR
Euro
EUR
Greenland
GL
Danish krone
DKK
Guatemala
GT
Guatemalan quetzal
GTQ
Guernsey
GG
British pound
GBP
Hong Kong
HK
Hong Kong dollar
HKD
Hungary
HU
Hungarian forint
HUF
Iceland
IS
United States dollar
USD
India
IN
Indian rupee
INR
Indonesia
ID
Indonesian rupiah
IDR
Iraq
IQ
Iraqi dinar
IQD
Ireland
IE
Euro
EUR
Isle of Man
IM
British pound
GBP
Israel
IL
Israeli shekel
ILS
Italy
IT
Euro
EUR
Jersey
JE
British pound
GBP
Jordan
JO
Jordanian dinar
JOD
Kazakhstan
KZ
Kazakhstani tenge
KZT
Korea, Republic of
KR
South Korean won
KRW
Kuwait
KW
Kuwaiti dinar
KWD
Kyrgyzstan
KG
United States dollar
USD
Latvia
LV
Euro
EUR
Lebanon
LB
Lebanese pound
LBP
Libya
LY
Libya dinar
LYD
Lithuania
LT
Euro
EUR
Luxembourg
LU
Euro
EUR
Malaysia
MY
Malaysian ringgit
MYR
Mexico
MX
Mexican peso
MXN
Moldova
MD
United States dollar
USD
Mongolia
MN
United States dollar
USD
Montenegro
ME
United States dollar
USD
Morocco
MA
Moroccan dirham
MAD
Netherlands
NL
Euro
EUR
New Zealand
NZ
New Zealand dollar
NZD
North Macedonia
MK
United States dollar
USD
Norway
NO
Norwegian krone
NOK
Oman
OM
Omani rial
OMR
Pakistan
PK
United States dollar
USD
Panama
PA
United States dollar
USD
Peru
PE
Peruvian sol
PEN
Philippines
PH
Philippine peso
PHP
Poland
PL
Polish zloty
PLN
Portugal
PT
Euro
EUR
Qatar
QA
Qatari riyal
QAR
Romania
RO
Euro
EUR
Russian Federation
RU
Russian ruble
RUB
Saudi Arabia
SA
Saudi rial
SAR
Serbia
RS
Serbian dinar
RSD
Singapore
SG
Singapore dollar
SGD
Slovakia
SK
Euro
EUR
Slovenia
SI
Euro
EUR
South Africa
ZA
South African rand
ZAR
Spain
ES
Euro
EUR
Sweden
SE
Swedish krona
SEK
Switzerland
CH
Swiss franc
CHF
Taiwan
TW
New Taiwan dollar
TWD
Tajikistan
TJ
United States dollar
USD
Thailand
TH
Thai baht
THB
Tunisia
TN
Tunisian dinar
TND
Türkiye
TR
Turkish lira
TRY
Turkmenistan
TM
United States dollar
USD
Ukraine
UA
Ukrainian hryvna
UAH
United Arab Emirates
AE
United Arab Emirates dirham
AED
United Kingdom
GB
British pound
GBP
United States
US
United States dollar
USD
Uzbekistan
UZ
United States dollar
USD
Venezuela
VE
United States dollar
USD
Vietnam
VN
Vietnamese dong
VND
Yemen
YE
Yemeni rial
YER
Table 40. Country and currency codes
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
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.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
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.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.