top

Samsung Checkout

This guide describes how you can develop billing system on your application.

Overview

Samsung Checkout offers the most optimized purchase experience on Smart TV where consumers can register payment methods fast and safely. And it makes frictionless payments repetitively within a TV environment. Also Samsung Checkout provides a comprehensive global monetization platform empowering developers to integrate various business models and promotional campaigns into their services.

  • There are 2 guides for Samsung Checkout.
    • Samsung Checkout (this guide)
      This guide describes how to develop billing system on your application.
    • Samsung Checkout DPI Portal
      This guide describes how to manage and maintenance for products on your application. Before starting to develop, please read first Samsung Checkout DPI Portal to get more details.
  • Specification
    • TV : Full Smart TVs ranging 2015~ (excluding Evolution Kit)
    • Supported Payment Methods : credit/debit cards, PayPal, carrier billing (Korea)
    • Security : Tizen SecureIME, 2nd screen card registration (mobile/PC)
    • Account : Samsung Account (shares account & payment info with Galaxy phones)
  • TV-Optimized Purchase Experience
    • Fast and simple 2-step checkout once a payment method is registered
    • Number-centric information entry suitable for TV remote controllers
    • Consumers can register credit/debit cards directly on TV or via mobile phone
      Figure 1. Frictionless 2-Step Checkout : 1. Confirm  -> 2. PIN Check  -> 3. Done

      Figure 1. Frictionless 2-Step Checkout : 1. Confirm -> 2. PIN Check -> 3. Done

Important

Samsung Account is a mandatory requirement to integrate with Samsung Checkout.
Samsung Checkout assumes that users are logged into Samsung Account at all times

Outline on Samsung Checkout

Samsung checkout provides secure and easy purchase function to Samsung Smart TV platform. If the user purchases a charged product on your application, Samsung checkout carries out user identification, purchase confirmation and purchase completion confirmation. After the user completes the purchase it, Samsung checkout returns the purchase result to your application.

Also developers can manage product application and product sales through DPI and proceed the actual purchase through Samsung Checkout.

The major functions of Samsung checkout are as follows:

  • Provide Common purchase GUI interface
  • Return purchase result to your application

Figure 2. Samsung checkout Chart Flow

Figure 2. Samsung checkout Chart Flow

Environment of the DPI(Digital Product Inventory) service

Submitting application which is integrated with Billing completely.

  • Submission should be done after setting API to be called distinguishing Staging Zone (DEV) / Operating Zone (PRD) environment.
  • Product information and price information in DPI Staging Zone / Operating Zone Portal should be checked whether they correspond or not

Figure 3. Billing System Relation Map

Figure 3. Billing System Relation Map

Operating Zone (Live / Production Environment)

  • When refund is made while being categorized as a real payment, accomplished payment in Operating Zone causes a charge on the part of developer. Thus, be careful not to use for purpose to test it.
  • When submitting app, you should set Operating Zone on your application.
  • Environment

  • Value

    • BuyItem API 2nd Parameter : “PRD”
  • Example

    var urlDPI = "https://dpiapi.samsungcloudsolution.com/openapi";
    var server = "PRD";
    var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL (It can be different with Sandbox's Security key)
    

Staging Zone (Test / Developing Environment)

  • The Verification System is a development environment that is separately provided to ease the Billing Linkage Development.
  • It supports environment which minimizes the exceptional cases of each country when the real payment is made.
  • Environment

  • Value

    • BuyItem API 2nd Parameter : “DEV”
  • Example

    var urlDPI = "https://sbox-dpiapi.samsungcloudsolution.com/openapi";
    var server = "DEV";
    var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL
    

Dummy Payment (Developing Environment)

  • It is provided user don’t need to register either PayPal account or Credit Card, but able to use all the service provided by DPI as if it is real payment transaction.
  • It is provided only for development, so before submit application to Samsung, use Staging Zone(DEV) / Operating Zone(PRD) environment instead of Dummy Payment(DUMMY).
  • Value
    • BuyItem API 2nd Parameter : “DUMMY”
  • Example

    var urlDPI = "https://sbox-dpiapi.samsungcloudsolution.com/openapi";
    var server = "DUMMY";
    var securityKey = "*****";  // YOUR SECURITY KEY ISSUED BY DPI PORTAL
    
Table 1. Payment
Dummy payment Actual payment
Note

Since the data cannot be shared between the Operating Zone and the Staging Zone, such as product type and price should correspond when App is put into QA for release.

Payment Method

  • Credit card
    When you register your credit card as a payment method in Samsung Checkout, you can register your credit card via mobile or PC website through entering the authentication code.
    Figure 4. Registration Credit Card

    Figure 4. Registration Credit Card

In case of using “DEV” or “DUMMY” server to request payment, It should be used below each URL to enter your authentication code on your TV via mobile or PC website.

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

Prerequisite

Before starting to develop Samsung checkout for your application, It is required to start registering your application on the Seller Office.

You don’t need to complete to register with your source codes, It is available to use DPI Portal only to set “Billing(Use)” and “Samsung Checkout on TV(Yes)” and save temporarily at the 2nd step of App Registration Page.

For more details, please refer Samsung Checkout DPI Portal Guide

Note

If you want to manage your product for billing, please navigate to DPI Portal

Implementation

Developer can implement In-app-purchase feature using open API provided by DPI. DPI service provides information on sellable products and purchase history of each customer on application. And it also supports the procedure of product management (Apply Product API) in an effort to guarantee secure sales of products.

Basic Features

The DPI and Samsung Checkout provide major functions as below.

  • Major Functions of DPI
    • Provide product information for each country
    • Provide user specific purchase information
    • Assure purchase integrity
    • Manage application of product after purchase
    • Security through prevention of fraudulent access
  • Major Functions of Samsung Checkout
    • Provide GUI Interface for Common Purchase
    • Deliver purchase result to your application
    • Product image display (shared image URL via network)
      In case developer want to display product image on Samsung Checkout, save image URL in your own contents server.
Table 2. Display Product Image
Default image Product image

Development Flow

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

Figure 5. payment sequence diagram

Figure 5. payment sequence diagram

1. Request Purchases List

Refer to [APIs > POST APIs > Request Purchase List API]

  • If there is non-applied product(AppliedStatus) in the delivered purchase list, apply the product.
  • If there is refunded product(CancelStatus) in the delivered purchase list, retrieve the product.
  • Send the application result to the server.
    • Refer to [APIs > POST APIs > Verify Purchase API] and [APIs > POST APIs > Apply Product API]

2. Request Products list

Refer to [APIs > POST APIs > Request Products List API]

3. Purchase the product

Refer to [APIs > BuyItem API]

  • In case the user selects the “Buy” button in the your application, Samsung Checkout carries out common purchase GUI.
  • User can enter the account and the passcode of 3rd party billing service.
  • User can enter the phone number and PIN number on the common purchase GUI.
  • Samsung Checkout delivers the purchase result to your application when the user finishes the purchase of charged product.
  • Your application can confirm the success/failure of purchase and reflect the result on the application.
  • Purchase completes.

4. Re-check the purchase result of the product

Refer to [APIs > POST APIs > Verify Purchase API]

5. Apply the product

Send the application result to the server
Refer to [APIs > POST APIs > Apply Product API]

APIs

DPI server is operated by distinguishing Staging Zone and Operating Zone. Staging Zone(DEV) should be used during development and Operating Zone(PRD) should be used during App submission in accordance with TV environment. And they have each different OpenAPI.

Initialization

Following initialization must be called before using below 5 POST APIs supported by DPI and buyItem API.

1. get UID

Please declare following privileges to get UID in config.xml

<tizen:privilege name="http://developer.samsung.com/privilege/sso.partner"/>
var loginUid = webapis.sso.getLoginUid(); //get UID value from TV

2. get country code

If you want more details, please refer Samsung Product API References > ProductInfo API
Please declare following privileges to get country code in config.xml

<tizen:privilege name="http://developer.samsung.com/privilege/productinfo"/>
var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);

3. get server type

If you want more details, please refer Samsung Product API References > ProductInfo API

var serverType = webapis.productinfo.getSmartTVServerType();

4. set DPI URL & Server Type

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

Making CheckValue

DPI uses CheckValue which is a base64 hash value made from the ‘HMAC SHA256 algorithm’ and ‘DPI Security Key’ in order to assure the integrity of data. The method of creating CheckValue is also illustrated in this chapter.

  • CheckValue
    CheckValue parameter is base64 hash value which is generated through the ‘HMAC SHA256 algorithm’ and ‘DPI Security Key’. It is used to guarantee integrity of data.
    Once app approval completes at DPI Portal, DPI Security Key can be found at [DPI Portal > App Setting] menu
    Figure 6. Security Key Issuance

    Figure 6. Security Key Issuance

Note

  • The issued security key is a key to be used for Open API calls made by a Smart TV app. Please be careful not to reveal this key to others.
  • In order to cope with attacks on App such as reverse engineering and etc. In a more secure manner, developer can manage the key using management server.

CheckValue is used to determine whether a normal request of called Request Purchases List API and Request Products List API. If CheckValue is incorrect, DPI responds the error of abnormal approach.
Method as described above is also useful for checking the response data at developer side. By checking CheckValue from API response, it is possible to determine whether the normal data from the DPI server. In order to ensure the data integrity of the real-time request/response, CheckValue should be generated for every API request/response in runtime.

Generating a CheckValue

The following 2 items are used as parameters.

1. The Combination of Necessary Parameters

Combine all of the necessary parameters referring to each API specification of CheckValue parameters. (ex: “12345”+”123”+”US”+”2”+”1” = “12345123US21”)

2. DPI Security Key

Use the ‘DPI Security Key’ which is issued at DPI Portal.

Note

Please note that you can use any kind of open library such as “CryptoJS”. We use “CryptoJS” on this sample code. (It is optimized for v3.1.2)
Please refer this downloadable site

var appId = "1234567890"; //YOUR APPID
var loginUid = "yourUid";  //refer initialization
var countryCode = "US";  //refer initialization
var itemType = "2"; // refer to request value of invoice/list API
var pageNumber = 1; // refer to request value of invoice/list API

var detailObj = new Object();
detailObj.AppID = appId;  // YOUR APPID
detailObj.CustomID = loginUid;  // You should use same value with BuyItem's parameter
detailObj.CountryCode = countryCode; // country of User’s TV
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);

POST APIs

DPI provides five APIs for sale and management of products as follows, and supports POST method in JSON data format for communication.

  • Request Purchase List API
  • Request Products List API
  • Verify Purchase API
  • Apply Product API
  • Subscription Cancel API

Request Purchase List API

Requests the list of purchased items for a specific user (usually the currently logged in user).
If you refer to the Response API on the Application, you can identify whether AppliedStatus or CancelStatus.

  • AppliedStatus : the purchase history has been normally reflected on the App.
  • CancelStatus : the purchase history of the user has been refunded on the App.

However, for the case of subscription product, default value of AppliedStatus is true, CancelStatus does not indicate the refund status of the purchase history but cancellation status of the next subscription Cycle. SubsStatus and SubsEndTime show expiration status of the subscription.

// please refer CheckValue section
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) {
    // If you want more details how to use, please refer 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");
  }
});
  • Request

    Table 3. Request Purchase List API
    Parameter Type Mandatory Description
    AppID String True Application ID
    CustomID String True * Same as the OrderCustomID of the ‘BuyItem’ API Parameter (Samsung Account UID)
    CountryCode String True [Country code] : Refer to [Reference > Country code] - The value for country code should not be written arbitrarily, but should be written after receiving the information from TV.
    ItemType String True 1: NON-CONSUMABLE and LIMITED-PERIOD 2: ALL * Purchase information is provided corresponding to the period. (Refer to [Period of Providing Product Purchases Information] chapter.)
    PageNumber Number True [The Number of Requested Page] * 1~N, each page has 100 entries of purchase records. * Up to 100 purchase records are provided at a time. To receive the entire purchase records, request Purchases List while increasing the PageNumber until EOF is returned at CPResult parameter.
    CheckValue String True [Security Hash Code] – Refer to APIs > Make CheckValue * Necessary Parameters = AppID + CustomID + CountryCode + ItemType + PageNumber
  • Response

    Table 4. Response Purchase List API
    Parameters Type Mandatory Description
    CPStatus String True Result code
    “100000” (Success)
    “ErrorCode” (Failure)
    * Refer to [Reference > DPI Error Code]
    CPResult String False Result Message
    - “EOF” : the last page
    - “hasNext:TRUE” : There’s next page.
    - “Error Short Message” : Error message corresponding to the ErrorCode of CPStatus.
    * Refer to [Reference > DPI Error Code]
    TotalCount Number True Entire number of Invoices.
    * The total sum of all page’s purchase history.
    * The total sum of all purchase history in the period.
    (Refer to [Period of Providing Product Purchases Information] chapter.)
    CheckValue String True [Security Hash Code] – Refer to APIs > Make CheckValue
    * Necessary Parameters = CPStatus + CPResult + TotalCount + InvoiceDetails[0].ItemID + … + InvoiceDetails[TotlaCount].ItemID
    InvoiceDetails JSON False [Invoice Info]
      Seq Number True Sequence number (1 ~ TotalCount)
    InvoiceID String True Invoice ID
    ItemID String True Product ID
    ItemTitle String True Product name
    ItemType Number True [Product type]
    1 : CONSUMABLE
    2 : NON-CONSUMABLE
    3 : LIMITED-PERIOD
    4 : SUBSCRIPTION
    *The response ItemType is a parameter that is in different attribute from the Request ItemType. This shows the type information of products that is classified in detail.
    OrderTime String True Payment time
    (UTC-zero, ex> 20140314175900)
    Period Number False Period (Minutes)
    Price Number True Price (xxxx.yy)
    OrderCurrencyID String True Currency code
    * Refer to [Reference > Currency Code]
    CancelStatus Boolean True [Sales Cancellation Status]
    - true : Sales Cancellation
    - false : Sales Ongoing
    * for the case of subscription product, refers to the cancellation status of the next subscription Cycle
    AppliedStatus Boolean True [Product Application Status]
    - true : Applied
    - false : Not Applied
    * for the case of subscription product, default value is true(Applied)
    AppliedTime String False [Applied Time]
    (UTC-zero, ex> 20140314175900)
    * The starting time of using limited period product is applied on the standard of the AppliedTime field.
    LimitEndTime String False Only applies to limited period products. 
    AppliedTime + Period 
    (UTC-zero, ex> 20140314175900)
    RemainTime String False Only applies to limited period products.
    LimtEndTime – The time when invoice/list was called for is converted (seconds)
    SubscriptionInfo JSON False [SubscriptionInfo] 
    Mandatory when productType is Subscription
      SubscriptionId
    String True [Subscription ID]
    SubsStartTime String True [Subscription Registration Date]
    ( UTC-zero, ex> 20150114175900 )
    SubsEndTime String True [Subscription Expiry Date]
    ( UTC-zero, ex> 20150114175900 )
    SubsStatus String True [Subscription Status]
    00: Active 
    01 : Subscription Period Finished
    02 : Cancellation by the User 
    03 : Cancellation by the payment failure
    04 : Cancellation by CP
    05 : Cancellation by admin

Request Products List API

Request product information on DPI server. When It is “Show” status, the products information on sale is returned. This is generally used in bringing the list of products available for sale on the in-app purchase store.

// please refer CheckValue section
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) {
    // If you want more details how to use, please refer 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");
  }
});
  • Request

    Table 5. Request Products List API
    Parameters Type Mandatory Description
    AppID String True Application ID
    CountryCode String True [Country code] * Refer to [Reference > Country code] - The value for country code should not be written arbitrarily, but should be written after receiving the information from TV.
    CheckValue String True [Security Hash Code] – Refer to APIs > Make CheckValue * Necessary Parameters = AppID+CountryCode
    PageSize Number False [The Size of the Requested Page] * The number of products on each page (1-N (Maximum : 100))
    PageNumber Number False [The Number of Requested Page] * 1~N, each page has #PageSize entries of product information. * Up to 100 products are provided at a time. To receive the entire product information, request Products List while increasing the PageNumber until EOF is returned at CPResult parameter.
  • Response

    Table 6. Response Products List API
    Parameters Type Mandatory Description
    CPStatus String True Result code
    “100000” (Success)
    “ErrorCode” (Failure)
    * Refer to [Reference > DPI Error Code]
    CPResult String False Result Message
    - “EOF” : the last page
    - “hasNext:TRUE” : There’s next page.
    - “Error Short Message” : Error message corresponding to the ErrorCode of CPStatus.
    * Refer to [Reference > DPI Error Code]
    TotalCount Number True Entire number of Invoices.
    * The total sum of all page’s purchase history.
    * The total sum of all purchase history in the period.
    (Refer to [Period of Providing Product Purchases Information] chapter.)
    CheckValue String True [Security Hash Code] – Refer to APIs > Make CheckValue
    * Necessary Parameters = CPStatus + CPResult + TotalCount + InvoiceDetails[0].ItemID + … + InvoiceDetails[TotlaCount].ItemID
    ItemDetails JSON False [Item Details]
      Seq Number True Sequence number (1 ~ TotalCount)
    ItemID String True Product ID
    ItemTitle String True Product name
    ItemType Number True [Product type]
    1 : CONSUMABLE
    2 : NON-CONSUMABLE
    3 : LIMITED-PERIOD
    4 : SUBSCRIPTION
    *The response ItemType is a parameter that is in different attribute from the Request ItemType. This shows the type information of products that is classified in detail.
    Period Number False Period (Minutes)
    Price Number True Price (xxxx.yy)
    CurrencyID String True Currency Code
    (Refer to Reference > Currency Code)
    SubscriptionInfo JSON False [SubscriptionInfo] 
    Mandatory when productType is Subscription
      PaymentCyclePeriod
    String True Payment cycle Period
    D : day(s), W : week(s), M : month(s)
    PaymentCycleFrq Number True Frequency of payment cycle
    PaymentCycle Number True After how many cycles should billing stop

Verify Purchase API

To check whether a purchase corresponding to the requested InvoiceID was successful or not.

/* 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;  // You should use same value with BuyItem's parameter
detailObj.CountryCode = countryCode;  // country of User’s TV

var paymentDetails = JSON.stringify(detailObj);

//call API
$.ajax({
  url: strUrlDPI + "/invoice/verify",
  type: "POST",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // If you want more details how to use, please refer 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");
  }
});
  • Request

    Table 7. Request Purchase API
    Parameters Type Mandatory Description
    AppID String True Application ID
    InvoiceID String True Invoice ID
    CustomID String True * Same as the OrderCustomID which is the ‘BuyItem’ API Parameter Customer ID (Samsung Account UID)
    CountryCode String True [Country code] : Refer to [Reference > Country code] - The value for country code should not be written arbitrarily, but should be written after receiving the information from TV.
  • Response

    Table 8. Reponse Purchase API
    Parameters Type Mandatory Description
    CPStatus String True Result code “100000” (Success) “ErrorCode” (Failure) * Refer to [Reference > DPI Error Code]
    CPResult String False Result Message “SUCCESS” or “Error Short Message” * Refer to [Reference > DPI Error Code]
    AppID String True Requested App ID
    InvoiceID String True Requested Invoice ID

Apply Product API

The DPI is notified that the purchased product has been successfully applied to the app. The Apply Product Open API is prepared for cases where the purchase result is not delivered to the app. In abnormal network status, the application may not receive the “payment complete” message even the payment has been completed. In those cases, the product is not applied to the app. It is possible to apply the product to the app by checking the AppliedStatus of the response message after the app’s call for Request Purchases List API (generally, right after the app has been executed).

However, in case of subscription product, the product is deemed to be applied right at the point when purchase is made, and the Applied Status is set to be true. Thus, the relevant API does not need to be used.To check whether a purchase corresponding to the requested InvoiceID was successful or not.

Note

If errors occur more than three times, it is recommended that the product is kept in non-applied status and Apply Product is requested again after the network connection becomes normal (to exclude the possibility of the same product being applied twice)

/* 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;  // You should use same value with BuyItem's parameter
detailObj.CountryCode = countryCode;  // country of User’s TV

var paymentDetails = JSON.stringify(detailObj);

//call API
$.ajax({
  url: strUrlDPI + "/invoice/apply",
  type: "POST",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // If you want more details how to use, please refer 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");
  }
});
  • Request

    Table 9. Request Apply Product API
    Parameters Type Mandatory Description
    AppID String True Application ID
    InvoiceID String True Invoice ID
    CustomID String True Customer ID* Same as the OrderCustomID which is the ‘BuyItem’ API Parameter Customer ID (Samsung Account UID)
    CountryCode String True [Country code] * Refer to [Reference > Country code] - The value for country code should not be written arbitrarily, but should be written after receiving the information from TV.
  • Response

    Table 10. Response Apply Product API
    Parameters Type Mandatory Description
    CPStatus String True Result code “100000” (Success) “ErrorCode” (Failure)* Refer to [Reference > DPI Error Code]
    CPResult String False Result Message “SUCCESS” or “Error Short Message” * Refer to [Reference > DPI Error Code]
    AppliedTime String True Product Applied Time (UTC-zero, ex> 20140314175900)

Subscription Cancel API

Available to be used only when the product type is subscription product. Request for cancellaction of subscription on DPI server. DPI returns the expiry date when the relevant subscription of registered product actually expires and the status.

/* 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;  // You should use same value with BuyItem's parameter
detailObj.CountryCode = countryCode;  // country of User’s TV

var paymentDetails = JSON.stringify(detailObj);

//call API
$.ajax({
  url: strUrlDPI + "/subscription/cancel",
  type: "POST",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // If you want more details how to use, please refer 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");
  }
});
  • Request

    Table 11. Request Cancel API
    Parameters 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] * Refer to [Reference > Country code] - Country Code value should not be input arbitrarily, but should be based on the information obtained from TV.
  • Response

    Table 12. Response Cancel API
    Parameters Type Mandatory Description
    CPStatus String True Result code “100000” (Success) “ErrorCode” (Failure) * Refer to [Reference > DPI Error Code]
    CPResult String False Result Message “SUCCESS” or “Error Short Message”
    InvoiceID String True Invoice ID
    SubsCancelTime String False return the time when cancellation was complete after subscription cancel requested Subscription Canceled time ( UTC-zero, ex> 20150114175900 )
    SubsStatus String False Subscription status 00: active 01 : Finished cyclic payment (Expired) 02 : canceled subscription (Canceled by Buyer) 03 : canceled subscription by cyclic payment fail (Canceled (Payment Failure)) 04 : Canceled by CP 05 : Canceled by Admin

BuyItem API

A separate API provided by a separate Plugin should be used in order to run the Samsung Checkout on the App.
In this case, Plugin is provided in three separate engines for each individual engine as shown below.

  • BuyItem API
    • UnityEngine
    • WebEngine (Recommended)
    • NativeEngine

BuyItem

In order to check user authentication and make the purchase of paid item, it is necessary to perform the purchase GUI such as the screen below.

Important

If buyItem is called, Purchase GUI is shown on your application automatically. In this status, it is not recommended to change GUI for your own application, until receiving return value of response. In other words, you need to wait until finishing whole purchase transaction during shown Purchase GUI.

Different plugin for different development engine should be imported and called for, and the method of such is explained below for each development engine.

Figure 7. Common Purchase GUI

Figure 7. Common Purchase GUI

  • WebEngine
    Plugin for Web applications is not provided separately. After include the JS script for webapi in the html file (ex: index.html) of app, calling the BuyItem API.
    In buyItem, all data of request or response are JSON format.
    If you want more details, please refer Samsung Product API References > Billing API

1. Declare privilege in config.xml

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

2. Include JS script in html file

<script type='text/javascript' language='javascript' src='$WEBAPIS/webapis/webapis.js'></script>

3. Use BuyItem API in js file

webapis.billing.buyItem(AppID, PaymentServer, PaymentDetails, onsuccess, onerror);
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(); // need to change datatype to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // not mandatory value
detailObj.OrderCustomID = loginUid; // same value with invoice/list's parameter

var paymentDetails = JSON.stringify(detailObj);
webapis.billing.buyItem(appId, server, paymentDetails, 
function(data) {
    // If you want more details how to use, please refer 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 + "]");
});
  • Request

    Parameters Type Mandatory Description
    AppID String True AppID which is provided by Samsung Seller Site
    PaymentServer String True Parameter for the selection of payment server
    DUMMY : during development. (CANNOT use in QA, User Environment)
    - For the convenience of CP SW development, we provide function called ‘Dummy Payment’ in Staging Zone only.
    DEV : When using DPI Staging Zone (during development, during QA)
    - Parameter accessing through Staging Zone server
    PRD : When using DPI Operating Zone (Actual User Environment)
    - Parameter accessing through the actual payment server
    PaymentDetails JSON True [Payment Details]
      OrderItemID String True * Use the ItemID issued by DPI ‘cont/list’ API.
    Item ID for purchase (ex. DP123400000000)
    OrderTitle String True * Use the ItemTitle issued by DPI ‘cont/list’ API.
    Item Title for purchase (ex. Consumable Item)
    OrderTotal String True * Use the Price issued by DPI ‘cont/list’ API.
    * Please check the numeric separators when convert from Number to String, (Refer to comment)
    (Example : 1,000.03 (O) / 1.000,03 (X))
    Total amount of purchase
    OrderCurrencyID String True * Use the CurrencyID issued by DPI ‘cont/list’ API.
    Purchase currency unit (ex. USD)
    OrderID String False Management ID for purchase managed by 3rd party application
    OrderCustomID String True * Use the same value with CustomID parameter of DPI ‘invoice/list’ API
    Value for classification to distinguish users
    In case of using Samsung Account, UID is to be used. (ex. “123456789012”)
    - If the value of the OrderCustomID is "" or NULL, Samsung Account UID value is used.
    OrderItemPath String False Image path of item
    Image type : jpeg, jpg, png only
    StltAppId String False Settlement Application ID
  • Response

    Table 14. Response BuyItem API
    Parameters Type Mandatory Description
    payResult String True - “SUCCESS” : success - “FAILED” : fail - “CANCEL” : cancel (canceled by user)
Note

Currently Dynamic Product is also supported on Samsung Checkout.
Since the request parameter for Dynamic Product is different with general product, It is not contained all of things on this guide.
If you want to get more additional information for development about this, please contact Samsung.

Sample Application

References

DPI Error Code

Table 15. DPI Error Code
Result Code Result Message Description
100000 1. Basic Message - SUCCESS 2. Additional messages - If products/purchases history is exist, and have the following page : hasNext:TRUE - If products/purchases history is exist, and it is the last page : EOF - If purchases history doesn’t exist : Your Invoice Not Found. Success
400111 AppID not correct When requested App ID does not exist
Other Errors Refer to DPI Portal [Help] -> [Error Code]

Currency Code

  • This chart is for reference.

When running Samsung Checkout Module, please refer to the CurrencyID in the response for Request Product List.

Table 16. Currency Code
Currency Currency Code
US Dollar USD
Canadian Dollar CAD
Pound Sterling GBP
Euro EUR
Australian Dollar AUD
Turkey Dollar TRY
Dirham AED
Zloty PLN
Swiss Franc CHF
Krona SEK
Lev BGN
Czech Krona CZK
Forint HUF
Denmark Krona DKK
Norway Krona NOK
Ruble RUB
Mexico Peso MXN
Shekel ILS
Peso CLP
Argentina Peso ARS
Riyal SAR
Real BRL
South African Rand ZAR
India Rupee INR
Hryvnia UAH
Tenge KZT
Nuevo sol PEN
Won KRW
Quetzal GTQ
Colombia Peso COP

Country Code

For more details, please refer [Initialization > 2. get country code]

// to get country code
webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);

Use the information obtained from TV on the script below.

Table 17. Country Code
Country Name Country Code Currency Code
United States of America US USD
Canada CA CAD
United Kingdom GB GBP
Isle of Man IM GBP
Guernsey GG GBP
Jersey Je GBP
France FR EUR
Germany DE EUR
Italy IT EUR
Spain ES EUR
Australia AU AUD
Turkey TR TRY
UAE AE AED
Poland PL PLN
Switzerland CH CHF
Netherland NL EUR
Austria AT EUR
Belgium BE EUR
Luxembourg LU EUR
Rumania RO EUR
Greece GR EUR
Sweden SE SEK
Ireland IE EUR
Bulgaria BG BGN
Czech Republic CZ CZK
Hungary HU HUF
Denmark DK DKK
Greenland GL DKK
Faroe Islands FO DKK
Finland FI EUR
Aland Islands AX EUR
Norway NO NOK
Slovakia SK EUR
Russia RU RUB
Mexico MX MXN
Israel IL ILS
Chile CL CLP
Argentina AR ARS
Saudi Arabia SA SAR
Brazil BR BRL
Korea, Republic of KR KRW
Lithuania LT EUR
Latvia LV EUR
Estonia EE EUR
Peru PE PEN
Guatemala GT GTQ
Panama PA USD
Colombia CO COP
India IN INR
South Africa ZA ZAR
Ukraine UA UAH
Kazakhstan KZ KZT
Portugal PT EUR

Limitations when Saving Save Data inside TV

All the Saved Data of the App are deleted when app is deleted beause of storage limitation.

Therefore, after purchasing paid items, if the purchase history is saved not on a separate server but inside the TV, the purchase history may not be saved if the user deletes the App and reinstalls it, and all the items may get initialized. This is a limitation of a platform. Thus, If the app saves data inside the TV, It is recommended to announce that It occurs such problem of regarding content when user delete and reinstall the app.

If there is a request from a user who had not recognized such problem earlier, functions such as ‘Purchase History UnApply’ and ‘Refund’ are provided through DPI Portal, so as to enable developer to respond directly to such request.

Important

Contents related to this limitation should be processed after consulting with Samsung PM in advance.