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.

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.

Note

To 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 = webapis.sso.getLoginUid(); // Unique ID for this user

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:

if (strTVServer == "1") {
  strUrlDPI = "https://sbox-checkoutapi.samsungcheckout.com/openapi";
  strServer = "DEV";
  strSecurityKey = "********";
} else if (strTVServer == "0") {
  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 Purchase List and Products List API requests. It is a Base64 hash generated by applying the HMAC SHA256 algorithm on a concatenated string of parameters using the DPI security key.

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

Note

The 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.

Note

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

To call the Purchase List API:

// 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 and response data are in JSON format:

Purchase List API request parameters:

Table 1-1. Purchase List API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 \| application/x-www-form-urlencoded ] ex) Content-Type: application/json;charset=UTF-8 Content-Type: application/x-www-form-urlencoded When using the [application/x-www-form-urlencoded] type, be careful not to include spaces(' ') in the body.
"Accept"	True	Media Type used for Client Allowed : [ application/json;charset=UTF-8 ] ex) Accept: application/json;charset=UTF-8

Table 1-2. Purchase List API request parameters (Body)
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 Possible values: "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"

Purchase List API response parameters:

Table 2. 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 (Subscription ID is used If it's a regular payment product type)
	"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	Product price, in "xxxx.yy" format
	"OrderCurrencyID"		String		Currency code
	"CancelStatus"		Boolean		Cancellation status: "true": Sale canceled "false": Sale ongoing For subscription products, indicates the cancellation status for the next subscription cycle.
	"AppliedStatus"		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" = ""
	"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" = ""
	"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
		"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 (The time calculated based on the billing cycle of the subscription and the SubsStartTime)
		"NextPaymentTime"			Next actaul payment time, in 14-digit UTC time (The time payment actually occurs using user's payment method)
		"IsFreeTrialPeriod"	Boolean		Information about whether the subscription is currently in Free-trial period "true": In Free-trial period "false": Not in Free-trial period (If the first payment fails after the end of the Free-trial, Samsung will attempt to make a second payment after one day in accordance with Samsung's policy. During this grace period, the IsFreeTrialPeriod value would be returned as true.)

Note

14-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 and response data are in JSON format:

Products List API request parameters:

Table 3-1. Products List API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 \| application/x-www-form-urlencoded ] ex) Content-Type: application/json;charset=UTF-8 Content-Type: application/x-www-form-urlencoded When using the [application/x-www-form-urlencoded] type, be careful not to include spaces(' ') in the body.
"Accept"	True	Media Type used for Client Allowed : [ application/json;charset=UTF-8 ] ex) Accept: application/json;charset=UTF-8

Table 3-2. Products List API request parameters (Body)
Parameter	Type	Mandatory	Description
"AppID"	String	True	Application ID
"CountryCode"	String	True	Country code The country code must be retrieved from the TV.
"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"

Products List API response parameters:

Table 4. Products 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"
"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
	"Period"			False	Limited period product duration, in minutes
	"Price"			True	Product price, in "xxxx.yy" format
	"CurrencyID"		String	True	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"		False	Free trial days of product. Mandatory for Free Trial + Subscription products.

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 and response data are in JSON format:

Verify Purchase API request parameters:

Table 5-1. Verify Purchase API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 \| application/x-www-form-urlencoded ] ex) Content-Type: application/json;charset=UTF-8 Content-Type: application/x-www-form-urlencoded When using the [application/x-www-form-urlencoded] type, be careful not to include spaces(' ') in the body.
"Accept"	True	Media Type used for Client Allowed : [ application/json;charset=UTF-8 ] ex) Accept: application/json;charset=UTF-8

Table 5-2. Verify Purchase API request parameters (Body)
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.

Verify Purchase API response parameters:

Table 6. 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

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.

Note

To 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 request and response data are in JSON format:

Apply Product API request parameters:

Table 7-1. Apply Purchase API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 \| application/x-www-form-urlencoded ] ex) Content-Type: application/json;charset=UTF-8 Content-Type: application/x-www-form-urlencoded When using the [application/x-www-form-urlencoded] type, be careful not to include spaces(' ') in the body.
"Accept"	True	Media Type used for Client Allowed : [ application/json;charset=UTF-8 ] ex) Accept: application/json;charset=UTF-8

Table 7-2. Apply Purchase API request parameters (Body)
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.

Apply Product API response parameters:

Table 8. 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

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 and response data are in JSON format:

Subscription Cancel API request parameters:

Table 9-1. Subscription Cancel API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 \| application/x-www-form-urlencoded ] ex) Content-Type: application/json;charset=UTF-8 Content-Type: application/x-www-form-urlencoded When using the [application/x-www-form-urlencoded] type, be careful not to include spaces(' ') in the body.
"Accept"	True	Media Type used for Client Allowed : [ application/json;charset=UTF-8 ] ex) Accept: application/json;charset=UTF-8

Table 9-2. Subscription Cancel API request parameters (Body)
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.

Subscription Cancel API response parameters:

Table 10. 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: "00": Active "01": Subscription expired "02": Canceled by buyer "03": Canceled for payment failure "04": Canceled by CP "05": Canceled by admin

Checking Billing Service Available Country

The /country/checkavailability API provides Billing service availability information for requested countrycodes.

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 countrycodes you want to check. Multi countrycodes available.

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");
  }
});

Billing Service Available Country Check API request and response data are in JSON format:

Billing Service Available Country Check API request parameters:

Table 11-1. Billing Service Available Country Check API request parameters (Header)
Parameter	Mandatory	Description
"Content-Type"	True	Indicates data type located in a body of request or response message. Allowed : [ application/json;charset=UTF-8 ] ex) Content-Type: application/json;charset=UTF-8
"Accept"	True	Media Type used for Client Allowed : [ application/json ] ex) Accept: application/json

Table 11-2. Billing Service Available Country Check API request parameters (Body)
Parameter	Type	Mandatory	Description
"AppID"	String	True	Application ID
"CountryCodes"			Countrycodes to check. Multiple countrycodes available. (Only Uppercase allowed) ex) CountryCodes=DE,US,KR
"CheckValue"			Security check value Required parameters: "AppID" + "CountryCodes" For multiple countrycodes, please use comma(,) removed and trimmed data. ex) CountryCodes=DE,US,KR then use "DEUSKR" for making CheckValue.

Billing Service Available Country Check API response parameters:

Table 12. 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	Countrycodes and info
	"CountryCode"	String	True	Countrycode

	"IsBillingSupported"	Boolean		Billing service support status. "true": Billing service supported "false": Billing service not supported

DPI Result Codes

The following table lists result codes and messages that are returned by the DPI service.

Table 13. DPI result codes and messages
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

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

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.

Important

When 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.

Table 14. Display your own product image
Default image	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 datatype to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // optional value
var UniqueCustomId = webapis.sso.getLoginUid(); // Unique ID for this user
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:

Table 15. buyItem() request parameters
Parameter		Type	Mandatory	Maximum length (characters)	Description
"AppID"		String	True	30	Application ID provided by Samsung Seller Office
"PaymentServer"		String		-	Possible values: "DEV": Staging zone "DUMMY": Staging zone with dummy payment "PRD": Operating zone
"PaymentDetails"		JSON		-	Payment details
	"OrderItemID"	String		30	Purchase item ID, for example, "DP123400000000" "ItemID" issued by the Products List API. when Dynamic product, need verification via "productId" of `Verify Product`
	"OrderTitle"			100	Purchase item title "ItemTitle" issued by the Products List API. when Dynamic product, use customized value instead.
	"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. when Dynamic product, use customized value instead and it needs verification via "productPrice" of `Verify Product`
	"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 If a value is not specified, a unique ID is generated by Samsung Checkout.
	"OrderItemPath"		False	-	Item image URI The image must be in JPEG, JPG, or PNG format.
	"DynmcProductID"		True (dynamic products only)	100	Unique ID for dynamic product from a third-party application when Dynamic product, need verification via "dynmcProductID" of `Verify Product`
	"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.

buyItem() method response parameters:

Table 16. buyItem() response parameters
Parameter		Type	Mandatory	Description
"payResult"		String	True	Possible values: “SUCCESS” “FAILED” “CANCEL”: Canceled by the user
"payDetail"		JSON	False	Payment details
	"InvoiceID"	String	False	Purchased Invoice ID, for example, "DO1904US000007153", this value is only available when payResult is "SUCCESS" otherwise, you will not get any value for "InvoiceID"

Note

"InvoiceID" in payDetail is available since Tizen 5.0

The “Dynamic Product” type is also supported on Samsung Checkout.

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

Dynamic Product

Verify Product Information

Available to be used only when the product type is dynamic product.

To check dynamic product information from DPI server to CP CMS. DPI server calls the API if ‘Verification’ is selected on DPI Portal.
API URL
Staging Zone (DEV) : ‘Verify URI’ entered in the DPI Portal of staging zone.
Operating Zone (PRD) : ‘Verify URI’ entered in the DPI Portal of 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 Product method request parameters:

Table 17. Verify Product request parameters
Parameter		Type	Mandatory	Maximum length (characters)	Description
"countryCode"		String	True	10	ISO3166-1 alpha2 Country Code (Upper Case)
"orderTime"		String	True	20	Order time (UTC-zero) (20140314175900)
"checkValue"		String	True	200	[Security Hash Code] * Necessary Parameters : appID + dynmcProductID + productId + productPrice + productCurrenyCode
"productDetail"		JSON	True	-	Product details
	"appId"	String	True	30	Application ID Same value as the "AppID" parameter for the `buyItem()` method.
	"productId"		True	30	Set ItemID Item purchase Same value as the "OrderItemID" parameter for the `buyItem()` method.
	"productPrice"		True	10	AppID or ItemID Price(Unit Price) Same value as the "OrderTotal" parameter for the `buyItem()` method.
	"productCurrencyCode"		True	10	Currency Code (ex. USD) Same value as the "OrderCurrencyID" parameter for the `buyItem()` method.
	"orderCustomId"		False	100	Unique customer ID If a value is not specified, a unique ID is generated by Samsung Checkout. Same value as the "OrderCustomID" parameter for the `buyItem()` method.
	"dynmcProductID"		True	100	dynmcProductID is the unique ID or string to track the product from the 3rd party application. Same value as the "DynmcProductID" parameter for the `buyItem()` method.
	"dynmcProductInfo"		False	100	dynamic product Information Same value as the "DynmcProductInfo" parameter for the `buyItem()` method.
	"dynmcShareCategory"		False	20	Share Category of dynamic product Same value as the "DynmcShareCategory" parameter for the `buyItem()` method.
	"dynmcTaxCategory"		False	30	Tax Category of dynamic product Same value as the "DynmcTaxCategory" parameter for the `buyItem()` method.

response parameters:

Table 18. Verify Product response parameters
Parameter	Type	Mandatory	Length	Description
"status"	String	True	9	Possible values: “100000” (Success) “ErrorCode” (Failure) Refer to the embedded Error Code file
"result"	String	True	100	Result Message (displayed at Smart TV screen)) “Success” or “Error Short Message”
"resultLongMesg"	String	False	200	Error Long Message for developer when Debug mode is true

Country and Currency Codes

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

Table 19. Country and currency codes
Country Name	Country Code	Currency	Currency Code
Aland Islands	AX	Euro	EUR
Argentina	AR	Argentine peso	ARS
Australia	AU	Australian dollar	AUD
Austria	AT	Euro	EUR
Belgium	BE	Euro	EUR
Brazil	BR	Brazilian real	BRL
Bulgaria	BG	Bulgarian lev	BGN
Canada	CA	Canadian dollar	CAD
Chile	CL	Chilean peso	CLP
Colombia	CO	Colombian peso	COP
Croatia	HR	Croatian kuna	HRK
Czech Republic	CZ	Czech koruna	CZK
Denmark	DK	Danish krone	DKK
Estonia	EE	Euro	EUR
Faroe Islands	FO	Danish krone	DKK
Finland	FI	Euro	EUR
France	FR	Euro	EUR
Germany	DE	Euro	EUR
Greece	GR	Euro	EUR
Greenland	GL	Danish krone	DKK
Guatemala	GT	Guatemalan quetzal	GTQ
Guernsey	GG	British pound	GBP
Hong Kong	HK	Hong Kong dollar	HKD
Hungary	HU	Hungarian forint	HUF
India	IN	Indian rupee	INR
Indonesia	ID	Indonesian rupiah	IDR
Ireland	IE	Euro	EUR
Isle of Man	IM	British pound	GBP
Israel	IL	Israeli shekel	ILS
Italy	IT	Euro	EUR
Jersey	JE	British pound	GBP
Jordan	JO	Jordanian dinar	JOD
Kazakhstan	KZ	Kazakhstani tenge	KZT
Korea, Republic of	KR	South Korean won	KRW
Latvia	LV	Euro	EUR
Lithuania	LT	Euro	EUR
Luxembourg	LU	Euro	EUR
Malaysia	MY	Malaysian ringgit	MYR
Mexico	MX	Mexican peso	MXN
Netherlands	NL	Euro	EUR
New Zealand	NZ	New Zealand dollar	NZD
Norway	NO	Norwegian krone	NOK
Panama	PA	US dollar	USD
Peru	PE	Peruvian sol	PEN
Philippines	PH	Philippine peso	PHP
Poland	PL	Polish zloty	PLN
Portugal	PT	Euro	EUR
Romania	RO	Euro	EUR
Russia	RU	Russian ruble	RUB
Saudi Arabia	SA	Saudi riyal	SAR
Singapore	SG	Singapore dollar	SGD
Slovakia	SK	Euro	EUR
Slovenia	SI	Euro	EUR
South Africa	ZA	South African rand	ZAR
Spain	ES	Euro	EUR
Sweden	SE	Swedish krona	SEK
Switzerland	CH	Swiss franc	CHF
Taiwan	TW	New Taiwan dollar	TWD
Thailand	TH	Thai baht	THB
Turkey	TR	Turkish lira	TRY
United Arab Emirates	AE	Emiriti dirham	AED
Ukraine	UA	Ukrainian hryvnia	UAH
United Kingdom	GB	British pound	GBP
United States of America	US	US dollar	USD
Vietnam	VN	Vietnamese dong	VND