top

Billing API

To use Samsung Product API, 

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

Should be loaded in index.html

This module defines the Billing (Samsung Checkout) functionalities provided by the Tizen Samsung TV Product API.

Since : 2.4

Product : TV

Table of Contents

  1. 1. Type Definitions
    1. 1.1. TVServerType
    2. 1.2. HistoryType
    3. 1.3. ProductsListData
    4. 1.4. ItemDetails
    5. 1.5. ProductSubscriptionInfo
    6. 1.6. ApplyInvoiceData
    7. 1.7. VerifyInvoiceData
    8. 1.8. UserPurchaseData
    9. 1.9. InvoiceDetails
    10. 1.10. PurchaseSubscriptionInfo
    11. 1.11. CancelSubscriptionData
    12. 1.12. ServiceAvailableData
  2. 2. Interfaces
    1. 2.1. BillingManagerObject
    2. 2.2. BillingManager
    3. 2.3. BillingBuyDataSuccessCallback
    4. 2.4. BillingBuyData
    5. 2.5. BillingProductsListCallback
    6. 2.6. BillingApplyInvoiceCallback
    7. 2.7. BillingVerifyInvoiceCallback
    8. 2.8. BillingGetUserPurchaseListCallback
    9. 2.9. BillingCancelSubscriptionCallback
    10. 2.10. BillingIsServiceAvailableCallback
  3. 3. Full WebIDL

Summary of Interfaces and Methods

Interface Method
BillingManagerObject  
BillingManager void buyItem(DOMString appId, TVServerType serverType, DOMString paymentDetails, BillingBuyDataSuccessCallback onsuccess, optional ErrorCallback ? onerror);
void getProductsList(DOMString appId, DOMString countryCode, DOMString pageSize, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingProductsListCallback onsuccess, optional ErrorCallback ? onerror);
void applyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingApplyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
void verifyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingVerifyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
void getUserPurchaseList(DOMString appId, DOMString customId, DOMString countryCode, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingGetUserPurchaseListCallback onsuccess, optional ErrorCallback ? onerror);
void cancelSubscription(DOMString appId, DOMString invoiceId, DOMString customId, DOMString countryCode, TVServerType serverType, BillingCancelSubscriptionCallback onsuccess, optional ErrorCallback ? onerror);
void isServiceAvailable(TVServerType serverType, BillingIsServiceAvailableCallback onsuccess, optional ErrorCallback ? onerror);
DOMString getVersion();
BillingBuyDataSuccessCallback void onsuccess(BillingBuyData data);
BillingBuyData  
BillingProductsListCallback void onsuccess(ProductsListData data)
BillingApplyInvoiceCallback void onsuccess(ApplyInvoiceData data)
BillingVerifyInvoiceCallback void onsuccess(VerifyInvoiceData data)
BillingGetUserPurchaseListCallback void onsuccess(UserPurchaseData data)
BillingCancelSubscriptionCallback void onsuccess(CancelSubscriptionData data)
BillingIsServiceAvailableCallback void onsuccess(ServiceAvailableData data)

1. Type Definitions

1.1. TVServerType

Specifies billing server types.

enum TVServerType {
  "DEV",
  "PRD"
};

The following values are supported

  • DEV : Staging server
  • PRD : Operating server

1.2. HistoryType

Specifies product types for the purchase history.

enum HistoryType {
  "ALL", 
  "SUBSCRIPTION",
  "NON-SUBSCRIPTION"
};

The following values are supported

  • ALL : All product types
  • SUBSCRIPTION : Subscription products only
  • NON-SUBSCRIPTION : Non-subscription products only

1.3. ProductsListData

Defines a dictionary for product list data returned by the getProductsList API.

dictionary ProductsListData {
  DOMString CPStatus;
  DOMString? CPResult;
  long TotalCount;
  DOMString CheckValue;
  ItemDetails? ItemDetails;
};

The following values are supported

  • CPStatus : DPI result code. Returns "100000" on success and other codes on failure
  • CPResult : Optional additional message:
    • "EOF" Last page of the product list
    • "hasNext:TRUE" Product list has further pages
    • Other error message, depending on the DPI result code
  • TotalCount : Total number of invoices
  • CheckValue : Security check value
  • ItemDetails : Optional dictionary in JSON format

1.4. ItemDetails

Defines a dictionary for the ProductsListData dictionary 'ItemDetails' parameter.

dictionary ItemDetails {
  long Seq;
  DOMString ItemID;
  DOMString ItemTitle;
  long ItemType;
  long? Period;
  long Price;
  DOMString CurrencyID;
  ProductSubscriptionInfo? SubscriptionInfo;
};

The following values are supported

  • Seq : Sequence number (1 ~ TotalCount)
  • ItemID : Product ID
  • ItemTitle : Product name
  • ItemType : Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
  • Period : Limited period product duration, in minutes
  • Price : Product price, in "xxxx.yy" format
  • CurrencyID : Currency code
  • SubscriptionInfo : Subscription information. Mandatory for subscription products

1.5. ProductSubscriptionInfo

Defines a dictionary for the ItemDetails dictionary 'SubscriptionInfo' parameter.

dictionary ProductSubscriptionInfo {
  DOMString PaymentCyclePeriod;
  long PaymentCycleFrq;
  long PaymentCycle;
};

The following values are supported

  • PaymentCyclePeriod : Subscription payment period:
    • "D": Days
    • "W": Weeks
    • "M": Months
  • PaymentCycleFrq : Payment cycle frequency
  • PaymentCycle : Number of payment cycles

1.6. ApplyInvoiceData

Defines a dictionary for data returned by the applyInvoice API.

dictionary ApplyInvoiceData {
  DOMString CPStatus;
  DOMString? CPResult;
  DOMString AppliedTime;
};

The following values are supported

  • CPStatus : DPI result code. Returns "100000" on success and other codes on failure.
  • CPResult : Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • AppliedTime : Time product applied, in 14-digit UTC time

1.7. VerifyInvoiceData

Defines a dictionary for data returned by the verifyInvoice API.

dictionary VerifyInvoiceData {
  DOMString CPStatus;
  DOMString? CPResult;
  DOMString AppID;
  DOMString InvoiceID;
};

The following values are supported

  • CPStatus : DPI result code. Returns "100000" on success and other codes on failure.
  • CPResult : Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • AppID : Application ID
  • InvoiceID : Invoice ID

1.8. UserPurchaseData

Defines a dictionary for data returned by the getUserPurchaseList API.

dictionary UserPurchaseData {
  DOMString CPStatus;
  DOMString? CPResult;
  long TotalCount;
  DOMString CheckValue;
  InvoiceDetails? InvoiceDetails;
};

The following values are supported

  • CPStatus : It returns "100000" in success, [ErrorCode] in failure. Refer to DPI Error Code
  • CPResult : Optional additional message:
    • "EOF" Last page of the product list
    • "hasNext:TRUE" Product list has further pages
    • Other error message, depending on the DPI result code
  • TotalCount : Total number of invoices
  • CheckValue : Security check value
  • InvoiceDetails : Optional dictionary in JSON format

1.9. InvoiceDetails

Defines a dictionary for data returned by the getUserPurchaseList API.

dictionary InvoiceDetails {
  long Seq;
  DOMString InvoiceID;
  DOMString ItemID;
  DOMString ItemTitle;
  long ItemType;
  DOMString OrderTime;
  long? Period;
  long Price;
  DOMString OrderCurrencyID;
  boolean CancelStatus;
  boolean AppliedStatus;
  DOMString? AppliedTime;
  DOMString? LimitEndTime;
  DOMString? RemainTime;
  PurchaseSubscriptionInfo? SubscriptionInfo;
};

The following values are supported

  • Seq : Sequence number (1 ~ TotalCount)
  • InvoiceID : Invoice ID
  • ItemID : Product ID
  • ItemTitle : Product name
  • ItemType : Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
  • OrderTime : Payment time, in 14-digit UTC time
  • Period : Limited period product duration, in minutes
  • Price : Product price, in "xxxx.yy" format
  • OrderCurrencyID : Currency code
  • CancelStatus : Cancellation status:
    • "true": Sale canceled
    • "false" : Sale ongoing
  • AppliedStatus : Product application status:
    • "true": Applied
    • "false" : Not applied
  • AppliedTime : Time product applied, in 14-digit UTC time
  • LimitEndTime : Limited period product end time, in 14-digit UTC time
  • RemainTime : Limited period product time remaining, in seconds
  • SubscriptionInfo : Subscription information. Mandatory for subscription products

1.10. PurchaseSubscriptionInfo

Defines a dictionary for the InvoiceDetails dictionary 'SubscriptionInfo' parameter.

dictionary PurchaseSubscriptionInfo {
  DOMString SubscriptionId;
  DOMString SubsStartTime;
  DOMString SubsEndTime;
  DOMString SubsStatus;
};

The following values are supported

  • SubscriptionId : 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

1.11. CancelSubscriptionData

Defines a dictionary for subscription cancellation data returned by the cancelSubscription API.

dictionary CancelSubscriptionData {
  DOMString CPStatus;
  DOMString? CPResult;
  DOMString InvoiceID;
  DOMString? SubsCancelTime;
  DOMString? SubsStatus;
};

The following values are supported

  • CPStatus : DPI result code. Returns "100000" on success and other codes on failure
  • CPResult : Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • InvoiceID : Invoice ID
  • SubsCancelTime : Optional time subscription canceled, in 14-digit UTC time
  • SubsStatus : Optional subscription status:
    • "00": Active
    • "01": Subscription expired
    • "02": Canceled by buyer
    • "03": Canceled for payment failure
    • "04": Canceled by CP
    • "05": Canceled by admin

1.12. ServiceAvailableData

Defines a dictionary for data returned by the IsServiceAvailable API.

dictionary ServiceAvailableData{
  DOMString status;
  DOMString result;
  DOMString serviceYn;
};

The following values are supported

  • status : Returns "100000" on success and other codes on failure
  • result : Returns "Success" on success
  • serviceYn : Returns "Y" if the service is available

2. Interfaces

2.1. BillingManagerObject

Defines a WebApi object instance of the Tizen Samsung TV Product API.
The webapis.billing object enables access to Billing API functionality.

[NoInterfaceObject]interface BillingManagerObject {
    readonly attribute BillingManager billing;
};

WebApi implements BillingManagerObject;

Since : 2.4

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Attributes

2.2. BillingManager

Provides methods for Billing functionalities.

[NoInterfaceObject]interface BillingManager {
  void buyItem(DOMString appId, TVServerType serverType, DOMString paymentDetails, BillingBuyDataSuccessCallback  onsuccess, optional ErrorCallback ? onerror);
  void getProductsList(DOMString appId, DOMString countryCode, DOMString pageSize, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingProductsListCallback  onsuccess, optional ErrorCallback ? onerror);
  void applyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingApplyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
  void verifyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingVerifyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
  void getUserPurchaseList(DOMString appId, DOMString customId, DOMString countryCode, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingGetUserPurchaseListCallback onsuccess, optional ErrorCallback ? onerror);
  void cancelSubscription(DOMString appId, DOMString invoiceId, DOMString customId, DOMString countryCode, TVServerType serverType, BillingCancelSubscriptionCallback onsuccess, optional ErrorCallback ? onerror);
  void isServiceAvailable(TVServerType serverType, BillingIsServiceAvailableCallback onsuccess, optional ErrorCallback ? onerror);
  DOMString getVersion();
};

Methods

buyItem
Enables implementing the Samsung Checkout Client module within the application. After authenticating the purchase information through the application, the user can proceed to purchase payment.

In case you want to use this function with Dynamic product item, parameters of "DynmcProductID", "DynmcProductInfo", "DynmcShareCategory", "DynmcTaxCategory" are madatory to use.

void buyItem(DOMString appId, TVServerType serverType, DOMString paymentDetails, BillingBuyDataSuccessCallback  onsuccess, optional ErrorCallback ? onerror);

Since : 2.4

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • serverType: Billing server type
  • paymentDetails: Payment parameters
    • OrderItemID[MANDATORY]
    • OrderTitle[MANDATORY]
    • OrderTotal[MANDATORY]
    • OrderCurrencyID[MANDATORY]
    • OrderID[OPTIONAL]
    • OrderCustomID[MANDATORY]
    • OrderItemPath[OPTIONAL]
    • DynmcProductID[OPTIONAL]
    • DynmcProductInfo[OPTIONAL]
    • DynmcShareCategory[OPTIONAL]
    • DynmcTaxCategory[OPTIONAL]
    • StltAppId[OPTIONAL]
  • onsuccess: Returns "payResult" and "payDetail"
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


///You should put check TV Servertype and add serverType param as below according to TV status when submit app to apps server///
var strTVServer = webapis.productinfo.getSmartTVServerType();
var serverType;

if(strTVServer == "1")
{
    serverType = "DEV";
}
else if(strTVServer == "0")
{
    serverType = "PRD";
}
//////////////////////////////////
var detailObj = new Object();
detailObj.OrderItemID = productsList.ItemDetails[selectedItem].ItemID; // issued by "getProductsList"
detailObj.OrderTitle = productsList.ItemDetails[selectedItem].ItemTitle; // issued by "getProductsList"
detailObj.OrderTotal = productsList.ItemDetails[selectedItem].Price.toString();
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // optional value
var uniqueCustomId = webapis.sso.getLoginUid(); //unique identifiable id only for this user
detailObj.OrderCustomID = uniqueCustomId;

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

getProductsList
Retrieves the list of products registered on the Billing (DPI) server.

void getProductsList(DOMString appId, DOMString countryCode, DOMString pageSize, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingProductsListCallback  onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • countryCode: Billing server type
  • pageSize: Number of products retrieved per page (maximum 100)
  • pageNumber: Requested page number (1 ~ N)
  • checkValue: Security check value. Required parameters = "AppID" + "CountryCode"
  • serverType: Billing server type
  • onsuccess: Returns the product list
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


    var tvServer = webapis.productinfo.getSmartTVServerType();
var server = "";

if (tvServer == "1") {
    server = "DEV";
} else if (tvServer == "0") {
    server = "PRD";
}
var appId = "********";
var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var securityKey = "********";
var pageSize = "100"; //sample
var pageNumber = "1"; //sample
var hash = CryptoJS.HmacSHA256(appId + countryCode, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.getProductsList(appId, countryCode, pageSize, pageNumber, checkValue, server, onsuccess, onerror);   
applyInvoice
Checks whether a purchase item has been applied.

void applyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingApplyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • customId: Same value as "OrderCustomID" parameter for the BuyItem API
  • invoiceId: Invoice ID
  • countryCode: TV country code
  • serverType: Billing server type
  • onsuccess: Returns purchase apply status
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


var tvServer = webapis.productinfo.getSmartTVServerType();
var server = "";

if (tvServer == "1") {
    server = "DEV";
} else if (tvServer == "0") {
    server = "PRD";
}

var appId = "**********";
var uniqueCustomId = webapis.sso.getLoginUid(); //unique identifiable id only for this user
var orderCustomID = uniqueCustomId;
var invoiceID = "*********"; // Issued by getUserPurchaseList
var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.applyInvoice(appId, orderCustomID, invoiceID, countryCode, server, onsuccess, onerror);
verifyInvoice
Checks whether a purchase, corresponding to a specific "InvoiceID", was successful.

void verifyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingVerifyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • customId: Same value as "OrderCustomID" parameter for the BuyItem API
  • invoiceId: Invoice ID
  • countryCode: TV country code
  • serverType: Billing server type
  • onsuccess: Returns the payment status
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


var tvServer = webapis.productinfo.getSmartTVServerType();
var server = "";

if (tvServer == "1") {
    server = "DEV";
} else if (tvServer == "0") {
    server = "PRD";
}

var appId = "**********";
var uniqueCustomId = webapis.sso.getLoginUid(); //unique identifiable id only for this user
var orderCustomID = uniqueCustomId;
var invoiceID = "*********"; // Issued by getUserPurchaseList
var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.verifyInvoice(appId, orderCustomID, invoiceID, countryCode, server, onsuccess, onerror);
getUserPurchaseList
Retrieves the user's purchase list.

void getUserPurchaseList(DOMString appId, DOMString customId, DOMString countryCode, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingGetUserPurchaseListCallback onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • customId: Same value as "OrderCustomID" parameter for the BuyItem API
  • countryCode: TV country code
  • itemType: Product type
  • pageNumber: Requested page number (1 ~ N)
  • checkValue: Security check value. Required parameters = "AppID" + "CountryCode"
  • serverType: Billing server type
  • onsuccess: Returns the purchase list
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


  var tvServer = webapis.productinfo.getSmartTVServerType();
    var server = "";
    
    if (tvServer == "1") {
        server = "DEV";
    } else if (tvServer == "0") {
        server = "PRD";
    }

    var appId = "********";
    var uniqueCustomId = webapis.sso.getLoginUid(); //unique identifiable id only for this user
    var orderCustomID = uniqueCustomId;
    var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
    var securityKey = "********";
    var itemType = "2";
    var pageNumber = "1";
    var hash = CryptoJS.HmacSHA256(appId + orderCustomID + countryCode + itemType + pageNumber, securityKey);
    var strCheckValue = CryptoJS.enc.Base64.stringify(hash);
    var onsuccess = function(res){};
    var onerror = function(error){};
    webapis.billing.getUserPurchaseList(appId, orderCustomID, countryCode, pageNumber, strCheckValue, server, onsuccess, onerror);

cancelSubscription
Cancels a subscription product.

void cancelSubscription(DOMString appId, DOMString invoiceId, DOMString customId, DOMString countryCode, TVServerType serverType, BillingCancelSubscriptionCallback onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • appid: Application ID
  • invoiceId: Invoice ID
  • customId: Same value as "OrderCustomID" parameter for the BuyItem API
  • countryCode: TV country code
  • serverType: Billing server type
  • onsuccess: Returns the subscription cancellation status
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


var tvServer = webapis.productinfo.getSmartTVServerType();
var server = "";

if (tvServer == "1") {
    server = "DEV";
} else if (tvServer == "0") {
    server = "PRD";
}

var appId = "3201503001547";
var uniqueCustomId = webapis.sso.getLoginUid(); //unique identifiable id only for this user
var orderCustomID = uniqueCustomId;
var invoiceID = "*********"; // Issued by getUserPurchaseList
var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.cancelSubscription(appId, invoiceID, orderCustomID , countryCode , server, onsuccess, onerror);
isServiceAvailable
Checks whether the Billing server is available.

void isServiceAvailable(TVServerType serverType, BillingIsServiceAvailableCallback onsuccess, optional ErrorCallback ? onerror);

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Parameters:

  • serverType: Billing server type
  • onsuccess: Returns the server availability
  • onerror [OPTIONAL]: Optional callback method to invoke if an error occurs

Exceptions:

  • WebAPIException
    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.isServiceAvailable("DEV", onsuccess, onerror)
getVersion
Retrieves the Billing API version.

DOMString getVersion();

Since : 4.0

Product : TV

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/billing

Return value:

Billing API version

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:


var version = webapis.billing.getVersion();

2.3. BillingBuyDataSuccessCallback

Defines the payment success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingBuyDataSuccessCallback {
  void onsuccess(BillingBuyData data);
};

Methods

onsuccess
Callback method returning the payment status.

void onsuccess(BillingBuyData data);

Parameters:

  • data: Payment status

Code example:


void onsuccess(data) {
  if(data.payResult == SUCCESS) {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.4. BillingBuyData

Defines the payment result and information.

[NoInterfaceObject] interface BillingBuyData{
  readonly attribute DOMString payResult;
  readonly attribute DOMString payDetail;
};

Attributes

  • readonly DOMString payResult
    Payment result
  • readonly DOMString payDetail
    Payment information

2.5. BillingProductsListCallback

Defines the product list success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingProductsListCallback {
  void onsuccess(ProductsListData data);
};

Methods

onsuccess
Callback method returning the product list request status.

void onsuccess(ProductsListData data);

Parameters:

  • data: Product list request status

Code example:


void onsuccess(data) {
  if(data.CPStatus == "10000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.6. BillingApplyInvoiceCallback

Defines the apply invoice success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingApplyInvoiceCallback {
  void onsuccess(ApplyInvoiceData data);
};

Methods

onsuccess
Callback method returning the apply invoice request status.

void onsuccess(ProductsListData data);

Parameters:

  • data: Apply invoice request status

Code example:


void onsuccess(data) {
  if(data.CPStatus == "10000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.7. BillingVerifyInvoiceCallback

Defines the payment verification success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingVerifyInvoiceCallback {
  void onsuccess(VerifyInvoiceData data);
};

Methods

onsuccess
Callback method returning the payment verification request status.

void onsuccess(VerifyInvoiceData data);

Parameters:

  • data: Payment verification request status

Code example:


void onsuccess(data) {
  if(data.CPStatus == "10000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.8. BillingGetUserPurchaseListCallback

Defines the purchase history success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingGetUserPurchaseListCallback {
  void onsuccess(UserPurchaseData data);
};

Methods

onsuccess
Callback method returning the purchase history request status.

void onsuccess(UserPurchaseData data);

Parameters:

  • data: Purchase history request status

Code example:


void onsuccess(data) {
  if(data.CPStatus == "10000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.9. BillingCancelSubscriptionCallback

Defines the subscription cancel success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingCancelSubscriptionCallback {
  void onsuccess(CancelSubscriptionData data);
};

Methods

onsuccess
Callback method returning the subscription cancel request status.

void onsuccess(UserPurchaseData data);

Parameters:

  • data: Subscription cancel request status

Code example:


void onsuccess(data) {
  if(data.CPStatus == "10000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.10. BillingIsServiceAvailableCallback

Defines the service availability check success callback.

[Callback = FunctionOnly, NoInterfaceObject]interface BillingIsServiceAvailableCallback {
  void onsuccess(ServiceAvailableData data);
};

Methods

onsuccess
Callback method returning the service availability check status.

void onsuccess(ServiceAvailableData data);

Parameters:

  • data: Service availability check status

Code example:


void onsuccess(data) {
  if(data.serviceYn == "Y") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

module Billing {
  enum TVServerType {
    "DEV",
    "PRD"
  };

  enum HistoryType {
    "ALL",
    "SUBSCRIPTION",
    "NON-SUBSCRIPTION"
  };

  dictionary ProductsListData {
    DOMString CPStatus;
    DOMString? CPResult;
    long TotalCount;
    DOMString CheckValue;
    ItemDetails? ItemDetails;
  };

  dictionary ItemDetails {
    long Seq;
    DOMString ItemID;
    DOMString ItemTitle;
    long ItemType;
    long? Period;
    long Price;
    DOMString CurrencyID;
    ProductSubscriptionInfo? SubscriptionInfo;
  };

  dictionary ProductSubscriptionInfo {
    DOMString PaymentCyclePeriod;
    long PaymentCycleFrq;
    long PaymentCycle;
  };

  dictionary ApplyInvoiceData {
    DOMString CPStatus;
    DOMString? CPResult;
    DOMString AppliedTime;
  };

  dictionary VerifyInvoiceData {
    DOMString CPStatus;
    DOMString? CPResult;
    DOMString AppID;
    DOMString InvoiceID;
  };

  dictionary UserPurchaseData {
    DOMString CPStatus;
    DOMString? CPResult;
    long TotalCount;
    DOMString CheckValue;
    InvoiceDetails? InvoiceDetails;
  };

  dictionary InvoiceDetails {
    long Seq;
    DOMString InvoiceID;
    DOMString ItemID;
    DOMString ItemTitle;
    long ItemType;
    DOMString OrderTime;
    long? Period;
    long Price;
    DOMString OrderCurrencyID;
    boolean CancelStatus;
    boolean AppliedStatus;
    DOMString? AppliedTime;
    DOMString? LimitEndTime;
    DOMString? RemainTime;
    PurchaseSubscriptionInfo? SubscriptionInfo;
  };

  dictionary PurchaseSubscriptionInfo {
    DOMString SubscriptionId;
    DOMString SubsStartTime;
    DOMString SubsEndTime;
    DOMString SubsStatus;
  };

  dictionary CancelSubscriptionData {
    DOMString CPStatus;
    DOMString? CPResult;
    DOMString InvoiceID;
    DOMString? SubsCancelTime;
    DOMString? SubsStatus;
  };

  dictionary ServiceAvailableData{
    DOMString status;
    DOMString result;
    DOMString serviceYn;
  };

  [NoInterfaceObject]interface BillingManagerObject {
    readonly attribute BillingManager billing;
  };

  WebApi implements BillingManagerObject;

  [NoInterfaceObject]interface BillingManager {
    void buyItem(DOMString appId, TVServerType serverType, DOMString paymentDetails, BillingBuyDataSuccessCallback  onsuccess, optional ErrorCallback ? onerror);
    void getProductsList(DOMString appId, DOMString countryCode, DOMString pageSize, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingProductsListCallback  onsuccess, optional ErrorCallback ? onerror);
    void applyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingApplyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
    void verifyInvoice(DOMString appId, DOMString customId, DOMString invoiceId, DOMString countryCode, TVServerType serverType, BillingVerifyInvoiceCallback onsuccess, optional ErrorCallback ? onerror);
    void getUserPurchaseList(DOMString appId, DOMString customId, DOMString countryCode, DOMString pageNumber, DOMString checkValue, TVServerType serverType, BillingGetUserPurchaseListCallback onsuccess, optional ErrorCallback ? onerror);
    void cancelSubscription(DOMString appId, DOMString invoiceId, DOMString customId, DOMString countryCode, TVServerType serverType, BillingCancelSubscriptionCallback onsuccess, optional ErrorCallback ? onerror);
    void isServiceAvailable(TVServerType serverType, BillingIsServiceAvailableCallback onsuccess, optional ErrorCallback ? onerror);
    DOMString getVersion();
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingBuyDataSuccessCallback {
    void onsuccess(BillingBuyData data);
  };

  [NoInterfaceObject] interface BillingBuyData{
    readonly attribute DOMString payResult;
    readonly attribute DOMString payDetail;
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingProductsListCallback {
    void onsuccess(ProductsListData data);
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingApplyInvoiceCallback {
    void onsuccess(ApplyInvoiceData data);
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingVerifyInvoiceCallback {
    void onsuccess(VerifyInvoiceData data);
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingGetUserPurchaseListCallback {
    void onsuccess(UserPurchaseData data);
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingCancelSubscriptionCallback {
    void onsuccess(CancelSubscriptionData data);
  };

  [Callback = FunctionOnly, NoInterfaceObject]interface BillingIsServiceAvailableCallback {
    void onsuccess(ServiceAvailableData data);
  };
};