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. ShowRegisterPromotionalCodeData
    13. 1.13. PromotionalCodeDetail
    14. 1.14. ShowRegisterCreditCardData
    15. 1.15. ShowPurchaseHistoryData
    16. 1.16. PurchaseHistoryDetail
    17. 1.17. 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. BillingShowRegisterPromotionalCodeCallback
    11. 2.11. BillingShowRegisterCreditCardCallback
    12. 2.12. BillingShowPurchaseHistoryCallback
    13. 2.13. 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)
BillingShowRegisterPromotionalCodeCallback void onsuccess(ShowRegisterPromotionalCodeData data)
BillingShowRegisterCreditCardCallback void onsuccess(ShowRegisterCreditCardData data)
BillingShowPurchaseHistoryCallback void onsuccess(ShowPurchaseHistoryData 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. ShowRegisterPromotionalCodeData

This defines data set that is coming from showRegisterPromotionalCode API.

dictionary ShowRegisterPromotionalCodeData {
  DOMString openDeepLinkResult;
  PromotionalCodeDetail openDeepLinkDetail;
};

The following values are supported

  • openDeepLinkResult : It returns "SUCCESS" in success, "FAIL" in failure.
  • openDeepLinkDetail : It returns the detail information of coupon or gift card

1.13. PromotionalCodeDetail

This defines data set of PromotionalCodeDetail parameter that contains ShowRegisterPromotionalCodeData dictionary.

dictionary PromotionalCodeDetail {
  DOMString AppliedCouponCount;
  DOMString AppliedCouponList;
  DOMString RegistedBenefitCount;
  DOMString RegistedBenefitList;
};

The following values are supported

  • AppliedCouponCount : It returns the number of applied coupon count.
  • AppliedCouponList : It returns the list of applied coupon.
  • RegistedBenefitCount : It returns the number of benefit.
  • RegistedBenefitList : It returns the list of benefit code.

1.14. ShowRegisterCreditCardData

This defines data set that is coming from ShowRegisterCreditCard API.

dictionary ShowRegisterCreditCardData {
  DOMString openDeepLinkResult;
  DOMString? openDeepLinkDetail;
};

The following values are supported

  • openDeepLinkResult : It returns "SUCCESS" in success, "FAIL" in failure.
  • openDeepLinkDetail : It is optional and not used now.

1.15. ShowPurchaseHistoryData

This defines data set that is coming from ShowPurchasesHistory API.

dictionary ShowPurchaseHistoryData {
  DOMString openDeepLinkResult;
  PurchaseHistoryDetail openDeepLinkDetail;
};

The following values are supported

  • openDeepLinkResult : It returns "SUCCESS" in success, "FAIL" in failure.
  • openDeepLinkDetail : It returns the detail information of refund or cancel.

1.16. PurchaseHistoryDetail

This defines data set of PurchaseHistoryDetail parameter that contains ShowPurchaseHistoryData dictionary.

dictionary PurchaseHistoryDetail {
  DOMString InvoiceRefundCount;
  DOMString InvoiceRefundList;
  DOMString SubscriptionCancelCount;
  DOMString SubscriptionCancelList;
};

The following values are supported

  • InvoiceRefundCount : It returns the number of product that user make refunded.
  • InvoiceRefundList : It returns array that contains the list of refunded invoice ID.
  • SubscriptionCancelCount : It returns the number of subscription product that user make cancelled.
  • SubscriptionCancelList : It returns array that contains the list of cancelled subscription.

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

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


var strAppId = "3201503001547";
var strUID = webapis.sso.getLoginUid();
var paymentDetails = new Object();
paymentDetails.OrderItemID="PID_2_consum_cupn";
paymentDetails.OrderTitle="hello consum US coupon";
paymentDetails.OrderTotal="2";
paymentDetails.OrderCurrencyID="USD";
paymentDetails.OrderCustomID=strUID;
var stringifyResult = JSON.stringify(paymentDetails);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.buyItem(strAppId, "DEV", stringifyResult, onsuccess, onerror);
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.

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 (Samsung Account UID)
  • 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 strAppId = "3201503001547";
var strUID = webapis.sso.getLoginUid();
var InvoiceID = "*********"; // Issued by getProductsList
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.applyInvoice(strAppId, strUID, InvoiceID, strCountryCode, "DEV", 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 (Samsung Account UID)
  • 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 strAppId = "3201503001547";
var strUID = webapis.sso.getLoginUid();
var InvoiceID = "*********"; // Issued by getProductsList
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.verifyInvoice(strAppId, strUID, InvoiceID, strCountryCode, "DEV", 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 (Samsung Account UID)
  • 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 strAppId = "3201503001547";
var strUID = webapis.sso.getLoginUid();
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var strPageNumber = "1";
var strCheckValue = "*******"; // For more information, see "Generating Check Values" in the "Samsung Checkout" guide
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.getUserPurchaseList(strAppId, strUID, strCountryCode, strPageNumber, strCheckValue, "DEV", 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 (Samsung Account UID)
  • 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 strAppId = "3201503001547";
var strUID = webapis.sso.getLoginUid();
var InvoiceID = "*********"; // Issued by getProductsList
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.cancelSubscription(strAppId, InvoiceID, strUID , strCountryCode , "DEV", 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. BillingShowRegisterPromotionalCodeCallback

This callback interface defines coupon/gift card registration success callback.

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

Methods

onsuccess
This method is callback parameter.

void onsuccess(ShowRegisterPromotionalCodeData data);

Parameters:

  • data: provide status

Code example:


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

2.11. BillingShowRegisterCreditCardCallback

This callback interface defines credit card registration success callback.

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

Methods

onsuccess
This method is callback parameter.

void onsuccess(ShowRegisterCreditCardData data);

Parameters:

  • data: provide status

Code example:


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

2.12. BillingShowPurchaseHistoryCallback

This callback interface defines purchase history success callback.

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

Methods

onsuccess
This method is callback parameter.

void onsuccess(ShowPurchaseHistoryData data);

Parameters:

  • data: provide status

Code example:


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

2.13. 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 ShowRegisterPromotionalCodeData {
    DOMString openDeepLinkResult;
    PromotionalCodeDetail openDeepLinkDetail;
  };

  dictionary PromotionalCodeDetail {
    DOMString AppliedCouponCount;
    DOMString AppliedCouponList;
    DOMString RegistedBenefitCount;
    DOMString RegistedBenefitList;
  };

  dictionary ShowRegisterCreditCardData {
    DOMString openDeepLinkResult;
    DOMString? openDeepLinkDetail;
  };

  dictionary ShowPurchaseHistoryData {
    DOMString openDeepLinkResult;
    PurchaseHistoryDetail openDeepLinkDetail;
  };

  dictionary PurchaseHistoryDetail {
    DOMString InvoiceRefundCount;
    DOMString InvoiceRefundList;
    DOMString SubscriptionCancelCount;
    DOMString SubscriptionCancelList;
  };

  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 BillingShowRegisterPromotionalCodeCallback {
    void onsuccess(ShowRegisterPromotionalCodeData data);
  };

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

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

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