Implementing the Purchase Process

This topic describes how to implement a billing system for managing products, sales, and payments, by using Samsung Checkout in your application.

Related Info

Samples

Implement a billing system for in-app purchases in your application, by using Samsung Checkout through the DPI service APIs and the Billing API.

Prerequisites

To implement in-app purchases:

Before you start implementing Samsung Checkout in your application, start registering your application at the Samsung Apps TV Seller Office. You do not need to complete the registration with your source code at this point. To be able to use the DPI portal, you need to proceed to the second step of the App Registration Page and set the "Billing" field to "Use" and the "Samsung Checkout on TV" field to "Yes". You can save the registration at this point and return to it later when your source code is complete. For more information, see the Samsung Checkout DPI Portal Guide.

NoteTo manage your product for billing, go to the Samsung Checkout DPI Portal.

To use the DPI, Billing, ProductInfo, and Sso APIs, the application has to request permission by adding the following privileges to the "config.xml" file:

<tizen:privilege name="http://developer.samsung.com/privilege/sso.partner"/>
<tizen:privilege name="http://developer.samsung.com/privilege/productinfo"/>
<tizen:privilege name="http://developer.samsung.com/privilege/billing"/>

To use the methods of the Billing, ProductInfo, and Sso APIs, include the "webapis.js" library in the "index.html" file:
```
<script type='text/javascript' language='javascript' src='$WEBAPIS/webapis/webapis.js'></script>
```

Initialize the required variables:

Retrieve the user ID:

  var UniqueCustomId = "123"; // Unique ID for this user. "123" is an example value. It can be an ID managed by your service.

Retrieve the country code:

var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);

Retrieve the server type:

var strTVServer = webapis.productinfo.getSmartTVServerType();

Set the DPI URL and service environment depending on the server type:

strUrlDPI = "https://checkoutapi.samsungcheckout.com/openapi";
strServer = "PRD";
strSecurityKey = "********";

DPI Service APIs

You can use the APIs provided by the DPI service to manage products and sales. The DPI service APIs communicate data in JSON format, using the POST method.

Generating Check Values

The check value is used by the DPI service to verify API requests. It is a Base64 hash generated by applying the HMAC SHA256 algorithm on a concatenated string of parameters using the DPI security key.

The application can also use the check value to verify that API response data from the DPI server is legitimate. To ensure the data integrity of requests and responses in real time, generate and verify the check value for API requests and responses during runtime.

NoteThe DPI security key is used only by Samsung Smart TV applications for open API calls. Do not expose this key. You can use a key management server for greater security.

To generate the check value, the following 2 items are used as parameters:

Concatenation of the required parameters

For example, "12345"+"123"+"US"+"2"+"1" is concatenated to "12345123US21".

The required parameters vary depending on the API.
DPI security key

The DPI security key is issued at the DPI portal.

You can use any open library to generate the HMAC SHA256 hash. The following example uses the CryptoJS library:

var appId = "1234567890"; // Your application ID
var UniqueCustomID = "yourUniqueID"; // Retrieved during initialization
var countryCode = "US"; // Retrieved during initialization
var itemType = "2"; // Request value for "invoice/list" API
var pageNumber = 1; // Request value for "invoice/list" API

var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.CustomID = UniqueCustomID; // Same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code
detailObj.ItemType = itemType; // "2": all items
detailObj.PageNumber = pageNumber;
var reqParams = detailObj.AppID + detailObj.CustomID + detailObj.CountryCode + detailObj.ItemType + detailObj.PageNumber;
/* Required Parameters
   [invoice/list] Request : appId + UniqueCustomID + countryCode + itemType + pageNumber
   [cont/list] Request : appId + countryCode
   Response : CPStatus, CPResult, TotalCount, ItemID(Seq)
*/

var hash = CryptoJS.HmacSHA256(reqParams , securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

Requesting User Purchases

The Purchase List API ("invoice/list") requests the list of purchased items for a specific user, usually the currently logged-in user. The API response identifies whether purchased products have been applied or have been refunded.

NoteFor subscription products, the default value of the "AppliedStatus" parameter is "true", but the "CancelStatus" parameter does not indicate the refund status in purchase history. Instead, it indicates the cancelation status for the next subscription cycle. The "SubsStatus" and "SubsEndTime" parameters detail the subscription expiration status.

To call the Purchase List API:

// Generate CheckValue
var reqParams = detailObj.AppID + detailObj.CustomID + detailObj.CountryCode + detailObj.ItemType + detailObj.PageNumber;
/* Required Parameters
   [invoice/list] Request : appId + UniqueCustomID + countryCode + itemType + pageNumber
   [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: urlDPI + "/invoice/list",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout sample application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
  console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Purchase List API request has the following headers:

Header	Mandatory	Description
"Content-Type"	True	Media type of the message: "application/json;charset=UTF-8" "application/x-www-form-urlencoded" For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').
"Accept"	Media type accepted by the client: "application/json;charset=UTF-8"

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"			String	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	True	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": SUBSCRIPTION The response "ItemType" value differs from the request "ItemType" value. The response value contains more detail.
	"OrderTime"		String		Payment time, in 14-digit UTC time
	"Period"		Number	False	Limited period product duration, in minutes
	"Price"		Number	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"		Boolean		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"			True (For limited period products only)	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.

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"

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"	String	True	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"	Number	False	Requested page number. Range: 1~N. Each purchase record page has a number of entries equal to the "PageSize" value. To receive the complete purchase record, post Purchase List API requests while increasing the "PageNumber" value, until "EOF" is returned in the "CPResult" parameter.
"CheckValue"	String	True	Security check value. Required parameters: "AppID" + "CountryCode".

Table 5. Products List API request parameters

Product List API response parameters

Parameter			Type	Mandatory	Description
"CPStatus"			String	True	Result code: "100000": Success "ErrorCode": Failure
"CPResult"			String	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	True	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"		String		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"		Number		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"

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"		True	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"

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"

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"	String	True	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"	String	True	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"			String	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"		String		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"

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_TRIAL COUPON
	"FreeTrialDays"	Integer	True	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"	String	True	End date of the free trial or coupon benefit. Format: "yyyy-MM-dd".
"AfterProductName"		String	True	Name of the new product
"AfterProductPrice"		String		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"		String		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"

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_TRIAL COUPON
	"FreeTrialDays"	Integer	True	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"	String	True	End date of the free trial or coupon benefit. Format: "yyyy-MM-dd".
"AfterProductName"		String	True	Name of the new product
"AfterProductPrice"		String		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"		String		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"

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"	String[]	False	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"	String	True	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"		String	True	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"

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"

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"		False	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"

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"		String	True	Result message: "SUCCESS" Other message corresponding to the "CPStatus" error code
"Countries"		JSON	False	Country information
	"CountryCode"	String	True	Country code
	"IsBillingSupported"	Boolean	True	Billing service support status: "true": Billing service supported "false": Billing service not supported

Table 33. Billing Service Available Country Check API response parameters

Billing API

To implement the Samsung Checkout functionality, use the Billing API.

When the user wants to make a purchase, authenticate the user and show the common purchase GUI with the buyItem() method.

ImportantWhen the buyItem() method is called, the common purchase GUI is shown in the application automatically. Do not change the purchase GUI appearance until the purchase transaction is complete and the application receives the response.

You can customize the product image in Samsung Checkout by providing the URI to an image on your own content server.

Default image	Product image

Table 34. Display your own product image

To implement Samsung Checkout:

var detailObj = new Object();
detailObj.OrderItemID = productsList.ItemDetails[selectedItem].ItemID; // Issued by "cont/list"
detailObj.OrderTitle = productsList.ItemDetails[selectedItem].ItemTitle; // Issued by "cont/list"
detailObj.OrderTotal = productsList.ItemDetails[selectedItem].Price.toString(); // Change data type to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // This value is optional
var UniqueCustomId = "123"; // Unique ID for this user. "123" is an example value. It can be an ID managed by your service.
detailObj.OrderCustomID = UniqueCustomId; // Same value as "CustomID" parameter for "invoice/list"

var paymentDetails = JSON.stringify(detailObj);
webapis.billing.buyItem(appId, serverType, paymentDetails,
  function(data) {
    // For implemention details, see the Samsung Checkout Sample Application
    console.log("[Billing buyItem]: pay_result [" + data.payResult + "], pay_detail [" + data.payDetail + "]");
  },
  function(error) {
    console.log("[Billing buyItem] status:[" + error.code + "] errorName:[" + error.name + "] errorMessage:[" + error.message + "]");
  }
);

The buyItem() method request and response data are in JSON format:

buyItem() method request parameters:

Parameter		Type	Mandatory	Maximum length (characters)	Description
"AppID"		String	True	30	Application ID provided by the Samsung Apps TV Seller Office
"PaymentServer"		String		-	Possible values: "PRD": Operating zone
"PaymentDetails"		JSON		-	Payment details
	"OrderItemID"	String	True	30	Purchase item ID, for example, "DP123400000000". "ItemID" issued by the Products List API. For dynamic products, use this value as "productId" for the Verify Dynamic Product Information API.
	"OrderTitle"			100	Purchase item title. "ItemTitle" issued by the Products List API. For dynamic products, use a customized value.
	"OrderTotal"			20	Total purchase price. "Price" issued by the Products List API. When converting the number to string type, pay attention to the unit separators. For dynamic products, use a customized value and use it as "productPrice" for the Verify Dynamic Product Information API.
	"OrderCurrencyID"			10	Purchase currency unit. "CurrencyID" issued by the Products List API.
	"OrderID"		False	50	Management ID for purchases managed by third-party applications
	"OrderCustomID"		True	100	Unique customer ID
	"OrderItemPath"		False	-	Item image URI. The image must be in JPEG, JPG, or PNG format.
	"DynmcProductID"		True (For dynamic products only)	100	Unique ID for the dynamic product from a third-party application. Use this value as "dynmcProductId" for the Verify Dynamic Product Information API.
	"DynmcProductInfo"		False	100	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"			30	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".

Parameter

Type

Mandatory

Description

"payResult"

String

True

Possible values:

"SUCCESS"
"FAILED"
"CANCEL": Canceled by the user

"payDetail"

JSON

False

Payment details

"InvoiceID"

String

False

Purchased Invoice ID, for example, "DO1904US000007153".
A value is only returned when "payResult" is "SUCCESS".

Table 36. buyItem() response parameters

Note

Dynamic products are also supported by Samsung Checkout.
For more information on offering dynamic products in your application, contact a Samsung representative by going to "Samsung Apps TV Seller Office > Support" and creating a "1:1 Q&A" support ticket.

Verifying Dynamic Product Information

The Verify Dynamic Product Information API ("cp/verify") is only available when the product type is dynamic product. The API checks the dynamic product information between DPI server and CP CMS. The DPI server calls this API when "Verification" is selected in the DPI Portal.

API URL

Operating Zone (PRD): The "Verify URI" entered in the DPI Portal for the operating zone.

POST https://xxxxxxxx.com/xxxx/cp/verify HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json;charset=UTF-8
Accept : application/json;charset=UTF-8
Content-Length: 391
Host: xxxx.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "countryCode": "ES",
  "orderTime": "20181017213438",
  "checkValue": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "productDetail": {
    "appId": "3201505000000",
    "productId": "RENT_PROD",
    "productPrice": "1.58",
    "productCurrencyCode": "USD",
    "orderCustomId": "xxxxxxxx",
    "dynmcProductID": "RENT_OPTION_4537",
    "dynmcProductInfo": "RENT_OPTION_4537"
  }
}

Verify Dynamic Product Information API request parameters:

Parameter		Type	Mandatory	Maximum length (characters)	Description
"countryCode"		String	True	10	Country code in uppercase
"orderTime"				20	Order time (UTC-0). (20140314175900)
"checkValue"				200	Security check value. Required parameters: "AppID" + "dynmcProductID" + "productId" + "productPrice" + "productCurrencyCode".
"productDetail"		JSON		-	Product details
	"appId"	String	True	30	Application ID. Same value as the "AppID" parameter for the `buyItem()` method.
	"productId"			30	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"			10	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

Parameter

Type

Mandatory

Length

Description

"status"

String

True

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

Result Code

Result Message

Description

100000

"SUCCESS"

Additional messages:

"hasNext:TRUE": Product list or purchase history has further pages
"EOF": Last page of the product list or purchase history
"Your Invoice Not Found": No purchase history exists

400111

"AppID not correct"

Requested application ID does not exist

Table 39. DPI result codes and messages

For explanations of additional DPI result codes, at the DPI portal, go to "Help > Error Code".

Country and Currency Codes

The following table lists countries with their corresponding country code, currency, and currency code.

Country Name	Country Code (ISO3166-1 alpha-2)	Currency	Currency Code (ISO 4217)
Aland Islands	AX	Euro	EUR
Albania	AL	United States dollar	USD
Algeria	DZ	Algerian dinar	DZD
Argentina	AR	Argentinian peso	ARS
Australia	AU	Australian dollar	AUD
Austria	AT	Euro	EUR
Bahrain	BH	Bahraini dinar	BHD
Belarus	BY	Belarusian ruble	BYN
Belgium	BE	Euro	EUR
Bolivia	BO	United States dollar	USD
Bosnia and Herzegovina	BA	United States dollar	USD
Brazil	BR	Brazilian real	BRL
Bulgaria	BG	Bulgarian lev	BGN
Canada	CA	Canadian dollar	CAD
Chile	CL	Chilean peso	CLP
Colombia	CO	Colombian peso	COP
Costa Rica	CR	United States dollar	USD
Croatia	HR	Euro	EUR
Czechia	CZ	Czech koruna	CZK
Denmark	DK	Danish krone	DKK
Dominican Republic	DO	United States dollar	USD
Ecuador	EC	United States dollar	USD
Egypt	EG	Egyptian pound	EGP
Estonia	EE	Euro	EUR
Faroe Islands	FO	Danish krone	DKK
Finland	FI	Euro	EUR
France	FR	Euro	EUR
Germany	DE	Euro	EUR
Greece	GR	Euro	EUR
Greenland	GL	Danish krone	DKK
Guatemala	GT	Guatemalan quetzal	GTQ
Guernsey	GG	British pound	GBP
Hong Kong	HK	Hong Kong dollar	HKD
Hungary	HU	Hungarian forint	HUF
Iceland	IS	United States dollar	USD
India	IN	Indian rupee	INR
Indonesia	ID	Indonesian rupiah	IDR
Iraq	IQ	Iraqi dinar	IQD
Ireland	IE	Euro	EUR
Isle of Man	IM	British pound	GBP
Israel	IL	Israeli shekel	ILS
Italy	IT	Euro	EUR
Jersey	JE	British pound	GBP
Jordan	JO	Jordanian dinar	JOD
Kazakhstan	KZ	Kazakhstani tenge	KZT
Korea, Republic of	KR	South Korean won	KRW
Kuwait	KW	Kuwaiti dinar	KWD
Kyrgyzstan	KG	United States dollar	USD
Latvia	LV	Euro	EUR
Lebanon	LB	Lebanese pound	LBP
Libya	LY	Libya dinar	LYD
Lithuania	LT	Euro	EUR
Luxembourg	LU	Euro	EUR
Malaysia	MY	Malaysian ringgit	MYR
Mexico	MX	Mexican peso	MXN
Moldova	MD	United States dollar	USD
Mongolia	MN	United States dollar	USD
Montenegro	ME	United States dollar	USD
Morocco	MA	Moroccan dirham	MAD
Netherlands	NL	Euro	EUR
New Zealand	NZ	New Zealand dollar	NZD
North Macedonia	MK	United States dollar	USD
Norway	NO	Norwegian krone	NOK
Oman	OM	Omani rial	OMR
Pakistan	PK	United States dollar	USD
Panama	PA	United States dollar	USD
Peru	PE	Peruvian sol	PEN
Philippines	PH	Philippine peso	PHP
Poland	PL	Polish zloty	PLN
Portugal	PT	Euro	EUR
Qatar	QA	Qatari riyal	QAR
Romania	RO	Euro	EUR
Russian Federation	RU	Russian ruble	RUB
Saudi Arabia	SA	Saudi rial	SAR
Serbia	RS	Serbian dinar	RSD
Singapore	SG	Singapore dollar	SGD
Slovakia	SK	Euro	EUR
Slovenia	SI	Euro	EUR
South Africa	ZA	South African rand	ZAR
Spain	ES	Euro	EUR
Sweden	SE	Swedish krona	SEK
Switzerland	CH	Swiss franc	CHF
Taiwan	TW	New Taiwan dollar	TWD
Tajikistan	TJ	United States dollar	USD
Thailand	TH	Thai baht	THB
Tunisia	TN	Tunisian dinar	TND
Türkiye	TR	Turkish lira	TRY
Turkmenistan	TM	United States dollar	USD
Ukraine	UA	Ukrainian hryvna	UAH
United Arab Emirates	AE	United Arab Emirates dirham	AED
United Kingdom	GB	British pound	GBP
United States	US	United States dollar	USD
Uzbekistan	UZ	United States dollar	USD
Venezuela	VE	United States dollar	USD
Vietnam	VN	Vietnamese dong	VND
Yemen	YE	Yemeni rial	YER

Table 40. Country and currency codes

Implementing the Purchase Process

Related Info

Samples

Prerequisites

DPI Service APIs

Generating Check Values

Requesting User Purchases

Requesting Products for Sale

Verifying Purchases

Applying Products

Modifying Subscription Plans

Retrieve Changeable Products

Pre-check Subscription Plan Changes

Reserve Subscription Plan Changes

Retrieve Subscription Plan Change Reservation Status

Cancel Subscription Plan Change Reservations

Canceling Subscriptions

Checking Billing Service Availability

Billing API

Verifying Dynamic Product Information

DPI Result Codes

Country and Currency Codes

Manage Your Cookies

Essential Cookies

Analytical/Performance Cookies

Functionality Cookies

Advertising Cookies

Preferences Submitted