top

Samsung Checkout

This topic describes how you can develop a billing system for your application, to allow users to make purchases within your application.

Samsung Checkout offers an optimized purchase experience on Samsung TVs. The user can quickly and safely register a payment method and make frictionless payments repetitively within the TV environment. In addition, Samsung Checkout provides a comprehensive global monetization platform, which allows you to integrate various business models and promotional campaigns into your services.

The TV-optimized purchase experience provides a quick and simple 3-step checkout, once a payment method is registered. The checkout requires only number-centric information to be entered, making it easy to use with a TV remote control. Users can register their payment method directly on the TV or through a mobile phone.

Figure 1. 3-step checkout: Confirm > Provide PIN > Done

Figure 1. 3-step checkout: Confirm > Provide PIN > Done

To use Samsung Checkout, the user needs:

  • TV: Samsung Smart TV, 2015 or later model (excluding Evolution Kit)
  • Payment method: Credit or debit card, PayPal, or carrier billing (in Korea)
  • Security: Tizen SecureIME, 2nd-screen card registration (mobile or PC)
  • Account: Samsung Account (for sharing account and payment information with Galaxy phones)
Important

A Samsung Account is mandatory for using Samsung Checkout. Samsung Checkout assumes that the user is logged in to Samsung Account at all times.

You can manage your product application and product sales through DPI (Digital Product Inventory) and process the actual purchase through Samsung Checkout.

For complete information, see:

  • Samsung Checkout (this guide) to develop a billing system for your application.
  • Samsung Checkout DPI Portal  to manage products for your application.
Important

All application data that is saved locally on a TV is deleted when the application is deleted from that TV. If the user’s purchase history is saved only in the TV storage and not remotely, and the user deletes and reinstalls the application, all application settings and content are removed, including purchased content. If your application saves purchase information in the TV storage only, inform the user that uninstalling the application deletes their purchased content.

The DPI portal provides functions, such as “Purchase History Unapply” and “Refund”, to help you address situations when your customer inadvertently deletes application data. Before proceeding with the unapply and refund processes, you must contact a Samsung representative by going to “Samsung Apps TV Seller Office > Support > 1:1 Q&A”.

Samsung Checkout Process

When a user wants to purchase a product on your application, Samsung Checkout provides a common purchase GUI, which identifies the user and confirms first the purchase and then the purchase completion. After the user completes the purchase, Samsung Checkout returns the purchase result to your application.

Figure 2. Samsung Checkout process

Figure 2. Samsung Checkout process

DPI Service Environment

The DPI service provides information on buyable products in your application and the purchase history of your customers. It serves the appropriate product information for the user’s country, provides user-specific purchase information, and manages applying the product after purchase. The DPI service also assures purchase integrity and provides security through preventing fraudulent access.

The DPI service environment is divided into 2 separate zones:

  • Operating Zone (PRD) for live production applications
    When you submit your application for release, set it to use the operating zone.

    Note

    When a refund of a real payment is made in the operating zone, a charge is applied on you. Consequently, do not use the operating zone for testing.

  • Staging zone (DEV) for development and testing
    The purpose of the staging zone is to facilitate the billing linkage development. This environment minimizes the exceptional country-specific cases that can happen when real payments are made in the operating zone.
    The staging zone also includes a dummy payment testing option, where the user does not need to register any payment method, but can still use all the DPI services as in real payment transactions.

    Table 1. Dummy and actual payment screens
    Dummy payment Actual payment

The following figure illustrates the DPI service environments.

Figure 3. DPI service environments

Figure 3. DPI service environments

Implementation information for each DPI service environment is described in the following table.

Table 2. DPI service environment details
Service EnvironmentDetails
Operating zone
Environment: buyItem() method 2nd parameter: "PRD"
Example:
var urlDPI = "https://checkoutapi.samsungcheckout.com/openapi";
var server = "PRD";
var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL
                            // (Can be different from Sandbox's Security key)
Staging zone
Environment: buyItem() method 2nd parameter: "DEV"
Example:
var urlDPI = "https://sbox-checkoutapi.samsungcheckout.com/openapi";
var server = "DEV";
var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL
Staging zone with dummy payment
Environment: buyItem() method 2nd parameter: "DUMMY"
Example:
var urlDPI = "https://sbox-checkoutapi.samsungcheckout.com/openapi";
var server = "DUMMY";
var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL

When you submit your application for release, make sure that it has been fully integrated with the billing system:

  • Set the DPI APIs to use the operating zone (PRD) environment.
  • Ensure that the product and price information in the operating zone matches the tested information in the staging zone (DEV). No data is automatically shared between the zones.

Registering a Payment Method

When the user registers their credit card as a payment method in Samsung Checkout, they can do it through their mobile phone or computer Web site by entering the authentication code.

Figure 4. Registering a credit card as a payment method

Figure 4. Registering a credit card as a payment method

When you are creating a user for testing your application, pay attention to the URL you use to enter your authentication code and register a payment method. Each URL requests a different server to handle the payment:

  • PRD: www.samsungcheckout.com or www.payon.tv
  • DEV: sbox.samsungcheckout.com or sbox.payon.tv
  • DUMMY: sbox.samsungcheckout.com or sbox.payon.tv

Prerequisites

Before you start to develop Samsung Checkout for your application, you must start to register your application on the 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 Samsung Checkout DPI Portal Guide.

Note

To manage your product for billing, go to the DPI Portal.

Implementation

You can implement in-app purchases in your application using an open API provided by the DPI service.

Development Flow

The payment service supports purchase management and payment as shown in the following flow.

Figure 5. Payment flow

Figure 5. Payment flow

  1. Request the purchase list:
    a. Retrieve the customer purchase list using a Purchase List API request.
    b. Respond to the purchase list content:

    • If there are products in the purchase list which are not applied, verify the purchase and apply the products.
    • If there are products in the purchase list which have been refunded, retrieve the products.
    c. Send the application result to the server.
  2. Request the product list.
    Request the product information list using a Products List API request.

  3. The user purchases the product:
    a. When the user selects “Buy” in the application, provide a common purchase GUI through Samsung Checkout.
    b. The user can enter the account and passcode for a third-party billing service.
    c. The user confirms the purchase by entering a phone number and PIN on the common purchase GUI.
    Samsung Checkout delivers the purchase result to your application.

  4. Request the purchase list.
    Update the customer purchase list.

  5. Verify the purchase.
    Verify the purchase using a Verify Purchase API request.

  6. Apply the product.
    Apply the product using an Apply Product API request, and send the application result to the server.

Initialization

To implement in-app purchases:

  1. To use the DPI, ProductInfo, and Billing 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"/> 
    
  2. To use the methods of the ProductInfo and Billing APIs, include the “webapis.js” library in the “index.html” file:

    <script type='text/javascript' language='javascript' src='$WEBAPIS/webapis/webapis.js'></script> 
    
  3. Initialize the required variables:
    a. Retrieve the User ID:

    var loginUid = webapis.sso.getLoginUid(); //get UID value from TV 
    

    b. Retrieve the country code:

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

    c. Retrieve the server type:

    var serverType = webapis.productinfo.getSmartTVServerType(); 
    

    d. Set the DPI URL and service environment:

    // Use Dummy Payment (DUMMY) for development 
    // When submitting to Samsung Apps TV, use Sandbox or Live environment depending on the TV environment. (PRD) 
    var urlDPI = "https://sbox-checkoutapi.samsungcheckout.com/openapi"; 
    var server = "DUMMY"; // "DUMMY", "DEV", "PRD" 
    var securityKey = "**********"; // YOUR SECURITY KEY ISSUED BY DPI PORTAL 
    

DPI Service APIs

You can use the APIs provided by the DPI service to manage products and sales.

Generating Check Values

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

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

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 APPID
var loginUid = "yourUid";  // 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 APPID
detailObj.CustomID = loginUid;  // same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code
detailObj.ItemType = itemType;   // "2" : ALL
detailObj.PageNumber = pageNumber;

var reqParams = detailObj.AppID + detailObj.CustomID + detailObj.CountryCode + detailObj.ItemType + detailObj.PageNumber;
/* Required Parameters
 [invoice/list] Request : appId + loginUid + 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);

Using POST APIs

The DPI service APIs communicate data in JSON format, using the POST method.

Purchase List API (“invoice/list”)

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

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 + loginUid + 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",
  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 3. Purchase List API request parameters
    Parameter Type Mandatory Description
    "AppID"
    String
    True
    Application ID
    "CustomID" Customer ID (Samsung Account UID)
    "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 4. Purchase List API response parameters
    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" False Result message:
    • "EOF": Last page of the purchase history
    • "hasNext:TRUE": Purchase history has further pages
    • Other message corresponding to the "CPStatus" error code
    "TotalCount" Number True Total number of invoices
    Sum of all purchase history pages, or sum of purchase history in the specified time period.
    "CheckValue" String Security check value
    Required parameters: "CPStatus" + "CPResult" + "TotalCount" + "InvoiceDetails[0].ItemID" + … + "InvoiceDetails[TotalCount].ItemID"
    "InvoiceDetails" JSON False Invoice information
      "Seq" Number True Sequence number
    Range: 1 ~ TotalCount
    "InvoiceID" String Invoice ID
    "ItemID" Product ID
    "ItemTitle" Product name
    "ItemType" Number Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
    The response "ItemType" value differs from the request "ItemType" value. The response value contains more detail.
    "OrderTime" String Payment time, in 14-digit UTC time, for example, "20140314175900"
    "Period" Number False Limited period product duration, in minutes
    "Price" True Product price, in "xxxx.yy" format
    "OrderCurrencyID" String Currency code
    "CancelStatus" Boolean Cancellation status:
    • "true": Sale canceled
    • "false": Sale ongoing
    For subscription products, indicates the cancellation status for the next subscription cycle.
    "AppliedStatus" Product application status:
    • "true": Applied
    • "false": Not applied
    For subscription products, the default value is "true".
    "AppliedTime" String False Time product applied, in 14-digit UTC time
    "LimitEndTime" Limited period product end time, in 14-digit UTC time
    For limited period products only.
    "LimitEndTime" = "AppliedTime" + "Period"
    "RemainTime" Limited period product time remaining, in seconds
    For limited period products only.
    "RemainTime" = "LimitEndTime" – request time
    "SubscriptionInfo" JSON Subscription information 
    Mandatory for subscription products.
      "SubscriptionId"
    String True Subscription ID
    "SubsStartTime" Subscription start time, in 14-digit UTC time
    "SubsEndTime" Subscription expiry time, in 14-digit UTC time
    "SubsStatus" Subscription status:
    • "00": Active
    • "01": Subscription expired
    • "02": Canceled by buyer
    • "03": Canceled for payment failure
    • "04": Canceled by CP
    • "05": Canceled by admin

Products List API (“cont/list”)

The Products List API requests product information from the DPI server. When the API is in “show” status, it returns the information for the products on sale. This API is generally used to generate a list of buyable products in the application.

To call the Products List API:

// 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",
  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 5. Products List API request parameters
    Parameter Type Mandatory Description
    "AppID"
    String
    True
    Application ID
    "CountryCode" Country code
    The country code must be retrieved from the TV.
    "PageSize"
    Number
    False
    Requested page size
    Range: 1~N (maximum 100)
    Number of products retrieved per page.
    "PageNumber" Requested page number
    Range: 1~N
    Each purchase record page has a number of entries equal to the "PageSize" value. To receive the complete purchase record, post Purchase List API requests while increasing the "PageNumber" value, until "EOF" is returned in the "CPResult" parameter.
    "CheckValue"
    String
    True
    Security check value
    Required parameters: "AppID" + "CountryCode"
  • Products List API response parameters:

    Table 6. Products List API response parameters
    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" False Result message:
    • "EOF": Last page of the purchase history
    • "hasNext:TRUE": Purchase history has further pages
    • Other message corresponding to the "CPStatus" error code
    "TotalCount" Number True Total number of invoices
    Sum of all purchase history pages, or sum of purchase history in the specified time period.
    "CheckValue" String Security check value
    Required parameters: "CPStatus" + "CPResult" + "TotalCount" + "InvoiceDetails[0].ItemID" + … + "InvoiceDetails[TotalCount].ItemID"
    "ItemDetails" JSON False Invoice information
      "Seq" Number True Sequence number
    Range: 1 ~ TotalCount
    "ItemID" String Product ID
    "ItemTitle" Product name
    "ItemType" Number Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
    "Period" False Limited period product duration, in minutes
    "Price" True Product price, in "xxxx.yy" format
    "CurrencyID" String Currency code
    "SubscriptionInfo" JSON False Subscription information 
    Mandatory for subscription products.
      "PaymentCyclePeriod"
    String True Subscription payment period:
    • "D": Days
    • "W": Weeks
    • "M": Months
    "PaymentCycleFrq" Number Payment cycle frequency
    "PaymentCycle" Number of payment cycles

Verify Purchase API (“invoice/verify”)

The Verify Purchase API 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 APPID
detailObj.InvoiceID = unCanceledItems[key].InvoiceID;  // issued by "invoice/list"
detailObj.CustomID = loginUid;  // 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",
  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 7. Verify Purchase API request parameters
    Parameter Type Mandatory Description
    "AppID"
    String
    True
    Application ID
    "InvoiceID"
    String
    True
    Invoice ID
    "CustomID"
    String
    True
    Customer ID (Samsung Account UID)
    "CountryCode"
    String
    True
    Country code
    The country code must be retrieved from the TV.
  • Verify Purchase API response parameters:

    Table 8. Verify Purchase API response parameters
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult"
    String
    False
    Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "AppID"
    String
    True
    Requested application ID
    "InvoiceID"
    String
    True
    Requested invoice ID

Apply Product API (“invoice/apply”)

The Apply Product API supports product management to help guarantee secure sales of your products. Normally, the DPI service is notified that the purchased product has been successfully applied. The Apply Product API is used in situations where purchase result delivery to the application encounters issues and is not successful. For example, if the network connection is interrupted, the application can fail to receive the “payment complete” message, even though the payment was completed. In this situation, the product is not applied to the application. You can check for unapplied products using the “AppliedStatus” parameter of the Purchase List API response and apply the product at that time.

For subscription products, the product is considered applied at the time of purchase and the “AppliedStatus” is set “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 APPID
detailObj.InvoiceID = unCanceledItems[key].InvoiceID;  // issued by "invoice/list"
detailObj.CustomID = loginUid;  // 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",
  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 9. Apply Purchase API request parameters
    Parameter Type Mandatory Description
    "AppID"
    String
    True
    Application ID
    "InvoiceID"
    String
    True
    Invoice ID
    "CustomID"
    String
    True
    Customer ID (Samsung Account UID)
    "CountryCode"
    String
    True
    Country code
    The country code must be retrieved from the TV.
  • Apply Product API response parameters:

    Table 10. Apply Product API response parameters
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult"
    String
    False
    Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "AppliedTime"
    String
    True
    Time product applied, in 14-digit UTC time, for example, "20140314175900"

Subscription Cancel API (“subscription/cancel”)

You can only use the Subscription Cancel API with subscription products, to request canceling the subscription. The DPI server returns the subscription expiry time and the current subscription status.

To call the Subscription Cancel API:

/* Required Parameters
 [subscription/cancel] Request
*/

var detailObj = new Object();
detailObj.AppID = appId;  // YOUR APPID
detailObj.InvoiceID = unCanceledItems [key].InvoiceID;  // issued by "invoice/list"
detailObj.CustomID = loginUid;   // 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",
  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 11. Subscription Cancel API request parameters
    Parameter Type Mandatory Description
    "AppID"
    String
    True
    Application ID
    "InvoiceID"
    String
    True
    Invoice ID
    "CustomID"
    String
    True
    Customer ID (Samsung Account UID)
    "CountryCode"
    String
    True
    Country code
    The country code must be retrieved from the TV.
  • Subscription Cancel API response parameters:

    Table 12. Subscription Cancel API response parameters
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult"
    String
    False
    Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "InvoiceID"
    String
    True
    Invoice ID
    "SubsCancelTime"
    String
    False
    Time subscription canceled, in 14-digit UTC time, for example, "20140314175900"
    "SubsStatus"
    String
    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

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 13. 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
detailObj.OrderCustomID = loginUid; // same value as "CustomID" parameter for "invoice/list" 

var paymentDetails = JSON.stringify(detailObj);
webapis.billing.buyItem(appId, server, 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 14. buyItem() request parameters
    Parameter Type Mandatory Length (character) Description
    "AppID" String True 30 Application ID provided by Samsung Seller Office
    "PaymentServer" String True Possible values:
    • "DEV": Staging zone
    • "DUMMY": Staging zone with dummy payment
    • "PRD": Operating zone
    "PaymentDetails" JSON True - Payment details
      "OrderItemID" String True 30 Purchase item ID, for example, "DP123400000000"
    "ItemID" issued by the Products List API.
    "OrderTitle" String True 100 Purchase item title
    "ItemTitle" issued by the Products List API.
    The length of title must not be exceeded 100 characters.
    "OrderTotal" String True 20 Total purchase price
    "Price" issued by the Products List API.
    When converting the number to string type, pay attention to the unit separators.
    "OrderCurrencyID" String True 10 Purchase currency unit
    "CurrencyID" issued by the Products List API.
    "OrderID" String False 50 Management ID for purchases managed by third-party applications
    "OrderCustomID" String True 100 Customer ID (Samsung Account UID)
    "CustomID" parameter from the Purchase List API.
    If the value of "OrderCustomID" is empty or "NULL", the Samsung Account UID value is used.
    "OrderItemPath" String True Item image URI
    The image must be in JPEG, JPG, or PNG format.
    "StltAppId" String True 30 Settlement application ID
  • buyItem() method response parameters:

    Table 15. buyItem() response parameters
    Parameter Type Mandatory Description
    “payResult” String True Possible values:
    • “SUCCESS”
    • “FAILED”
    • “CANCEL”: Canceled by the user
Note

The “Dynamic Product” type is also supported on Samsung Checkout.
The request parameters for dynamic products differ, and are not described in this topic. For more information, contact a Samsung representative by going to “Samsung Apps TV Seller Office > Support > 1:1 Q&A”.

DPI Result Codes

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

Table 16. 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”.

Country and Currency Codes

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

Table 17. 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
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
Hungary HU Hungarian forint HUF
India IN Indian rupee INR
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
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
Mexico MX Mexican peso MXN
Netherlands NL Euro EUR
Norway NO Norwegian krone NOK
Panama PA US dollar USD
Peru PE Peruvian sol PEN
Poland PL Polish zloty PLN
Portugal PT Euro EUR
Romania RO Euro EUR
Russia RU Russian ruble RUB
Saudi Arabia SA Saudi riyal SAR
Slovakia SK Euro EUR
South Africa ZA South African rand ZAR
Spain ES Euro EUR
Sweden SE Swedish krona SEK
Switzerland CH Swiss franc CHF
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