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 Product API.

Since : 2.4

Product : TV

Privilege Level : Public

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

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 getServiceCountryAvailability(DOMString appId, DOMString[] countryCodes, DOMString checkValue, TVServerType serverType, BillingGetServiceCountryAvailabilityCallback 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);

BillingGetServiceCountryAvailabilityCallback

void onsuccess(ServiceCountryAvailabilityData 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. This type is not supported since 2019 product.
  • 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 apiResult;
};

The following values are supported

  • apiResult : getProductsList API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in ProductsListAPIResult format at the below.

1.4 ProductsListAPIResult

Defines a dictionary for the ProductsListData dictionary apiResult parameter.

dictionary ProductsListAPIResult {
  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] 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] Optional dictionary in JSON format

1.5 ItemDetails

Defines a dictionary for the ProductsListAPIResult 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 : [Optional] Limited period product duration, in minutes
  • Price : Product price, in "xxxx.yy" format
  • CurrencyID : Currency code
  • SubscriptionInfo : [Optional] Subscription information. Mandatory for subscription products.

1.6 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.7 ApplyInvoiceData

Defines a dictionary for data returned by the applyInvoice API.

dictionary ApplyInvoiceData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : applyInvoice API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in ApplyInvoiceAPIResult format at the below.

1.8 ApplyInvoiceAPIResult

Defines a dictionary for the ApplyInvoiceData dictionary 'apiResult' parameter.

dictionary ApplyInvoiceAPIResult {
  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] Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • AppliedTime : Time product applied, in 14-digit UTC time

1.9 VerifyInvoiceData

Defines a dictionary for data returned by the verifyInvoice API.

dictionary VerifyInvoiceData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : verifyInvoice API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in VerifyInvoiceAPIResult format at the below.

1.10 VerifyInvoiceAPIResult

Defines a dictionary for the VerifyInvoiceData dictionary 'apiResult' parameter.

dictionary VerifyInvoiceAPIResult {
  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] Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • AppID : Application ID
  • InvoiceID : Invoice ID that you want to verify whether a purchase was successful

1.11 UserPurchaseData

Defines a dictionary for data returned by the getUserPurchaseList API.

dictionary UserPurchaseData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : getUserPurchaseList API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in GetUserPurchaseListAPIResult format at the below.

1.12 GetUserPurchaseListAPIResult

Defines a dictionary for the UserPurchaseData dictionary 'apiResult' parameter.

dictionary GetUserPurchaseListAPIResult {
  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] 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] Optional dictionary in JSON format

1.13 InvoiceDetails

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

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 of this purchase history
  • 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 : [Optional] 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 : [Optional] Time product applied, in 14-digit UTC time
  • LimitEndTime : [Optional] Limited period product end time, in 14-digit UTC time
  • RemainTime : [Optional] Limited period product time remaining, in seconds
  • SubscriptionInfo : [Optional] Subscription information. Mandatory for subscription products.

1.14 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 : ID of subscription history
  • 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.15 ServiceCountryAvailabilityData

Defines a dictionary for data returned by the getServiceCountryAvailability API.

dictionary ServiceCountryAvailabilityData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : getServiceCountryAvailability API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in GetUserPurchaseListAPIResult format at the below.

1.16 GetServiceCountryAvailabilityAPIResult

Defines a dictionary for the ServiceCountryAvailabilityData dictionary 'apiResult' parameter.

dictionary GetServiceCountryAvailabilityAPIResult {
  DOMString CPStatus;
  DOMString? CPResult;
  Countries[]? CountryAvailability;
};

The following values are supported

  • CPStatus : It returns "100000" in success, [ErrorCode] in failure. Refer to DPI Error Code.
  • CPResult : [Optional] Returns "Success" on success
  • CountryAvailability : [Optional] List of Countries with information of service availability

1.17 Countries

Defines a dictionary for the GetServiceCountryAvailabilityAPIResult dictionary 'CountryAvailability' parameter.

dictionary Countries {
  DOMString CountryCode;
  boolean IsBillingSupported;
};

The following values are supported

  • CountryCode : CountryCode to check Service Availability
  • IsBillingSupported : status :
    • "true": Service is available
    • "false" : Service is not available

1.18 CancelSubscriptionData

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

dictionary CancelSubscriptionData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : cancelSubscription API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in CancelSubscriptionAPIResult format at the below.

1.19 CancelSubscriptionAPIResult

Defines a dictionary for the CancelSubscriptionData dictionary apiResult parameter.

dictionary CancelSubscriptionAPIResult {
  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] Optional additional message:
    • "SUCCESS"
    • Other error message, depending on the DPI result code
  • InvoiceID : Invoice ID of subscription that you want to cancel
  • SubsCancelTime : [Optional] Optional time subscription canceled, in 14-digit UTC time
  • SubsStatus : [Optional] 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.20 ShowRegisterPromotionalCodeData

This defines data set that is coming from showRegisterPromotionalCode API.

dictionary ShowRegisterPromotionalCodeData {
  DOMString openDeepLinkResult;
  DOMString 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. It is a dictionary in JSON format, so you have to parse it to use. For more information, please refer to "PromotionalCodeDetail" at the below.

1.21 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.22 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 : [Optional] It is optional and not used now.

1.23 ShowPurchaseHistoryData

This defines data set that is coming from ShowPurchasesHistory API.

dictionary ShowPurchaseHistoryData {
  DOMString openDeepLinkResult;
  DOMString 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. It is a dictionary in JSON format, so you have to parse it to use. For more information, please refer to "PurchaseHistoryDetail" at the below.

1.24 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.25 ServiceAvailableData

Defines a dictionary for data returned by the IsServiceAvailable API.

dictionary ServiceAvailableData {
  DOMString apiResult;
};

The following values are supported

  • apiResult : IsServiceAvailable API result dictionary in JSON format. This value is JSON string type data, so Please use it by JSON parsing. After you parse this value, you can use it in ServiceAvailableAPIResult format at the below.

1.26 ServiceAvailableAPIResult

Defines a dictionary for the ServiceAvailableData dictionary 'apiResult' parameter.

dictionary ServiceAvailableAPIResult {
  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 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

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 getServiceCountryAvailability(DOMString appId, DOMString[] countryCodes, DOMString checkValue, TVServerType serverType, BillingGetServiceCountryAvailabilityCallback 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);

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" if there is no internal error occurs until client to server data communication.
    payResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    payDetail, can have additional data when it's returned, such as InvoiceID. Please refer to the development guide of "buyItem" for details
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method
    UnknownError, if other error occur, such as internal error or "billing client already running" error

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 2.4

Code Example :

var strAppId = "";
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);

Product : TV

Privilege Level : Public

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

Parameters :

  • appId : Application ID
  • countryCode : TV country code
  • pageSize : Number of products retrieved per page (maximum 100)
  • pageNumber : Requested page number (1 ~ N)
  • checkValue : Security check value. Required parameters = "appId" + "countryCode"
    The check value is used by the DPI service to verify API requests. It is a Base64 hash generated by applying the HMAC SHA256 algorithm on a concatenated string of parameters using the DPI security key.
    You can see the example how to generate checkValue from the following Code example.
    You can use any open library to generate the HMAC SHA256 hash. The following example uses the CryptoJS library
  • serverType : Billing server type
  • onsuccess : Returns the product list if there is no internal error occurs until client to server data communication
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 4.0

Code Example :

var strSecurityKey = ""; // The DPI security key is issued at the DPI portal.
var strAppId = "";
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var reqParams = strAppId + strCountryCode;
var hash = CryptoJS.HmacSHA256(reqParams, strSecurityKey);
var strCheckValue = CryptoJS.enc.Base64.stringify(hash);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.getProductsList(strAppId, strCountryCode, "100", "1", strCheckValue, "DEV", onsuccess, onerror);

applyInvoice

Updates the apply status of purchase item to DPI server.

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

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 of purchased Item that you want to update apply status
  • countryCode : TV country code
  • serverType : Billing server type
  • onsuccess : Returns purchase apply status if there is no internal error occurs until client to server data communication
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 4.0

Code Example :

var strAppId = "";
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);

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 that you want to verify whether a purchase was successful
  • countryCode : TV country code
  • serverType : Billing server type
  • onsuccess : Returns the payment status if there is no internal error occurs until client to server data communication.
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 4.0

Code Example :

var strAppId = "";
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);

getServiceCountryAvailability

Get Service Country availability for Samsung Checkout

void getServiceCountryAvailability(DOMString appId, DOMString[] countryCodes, DOMString checkValue, TVServerType serverType, BillingGetServiceCountryAvailabilityCallback onsuccess, optional ErrorCallback? onerror);

Product : TV

Privilege Level : Public

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

Parameters :

  • appId : Application ID
  • countryCodes : to check. Multiple countrycodes available. (Add as array, only Uppercase allowed) ex) countrycodes=["DE","US","KR"]
  • checkValue : Security check value. Required parameters = "appId" + "countryCodes"
    The check value is used by the DPI service to verify API requests. It is a Base64 hash generated by applying the HMAC SHA256 algorithm on a concatenated string of parameters using the DPI security key.
    You can see the example how to generate checkValue from the following Code example.
    You can use any open library to generate the HMAC SHA256 hash. The following example uses the CryptoJS library
  • serverType : Billing server type
  • onsuccess : Returns the service availability status of each country if there is no internal error occurs until client to server data communication.
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 5.5

Code Example :

var strSecurityKey = ""; // The DPI security key is issued at the DPI portal.
var strAppId = "";
var countryCodes = ["DE","US","KR"];
var reqParams = strAppId + "DEUSKR";
var hash = CryptoJS.HmacSHA256(reqParams, strSecurityKey);
var strCheckValue = CryptoJS.enc.Base64.stringify(hash);
var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.getServiceCountryAvailability(strAppId, countryCodes, strCheckValue, "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);

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
  • pageNumber : Requested page number (1 ~ N)
  • checkValue : Security check value. Required parameters = "appId" + "customId" + "countryCode" + "ItemType" + "pageNumber"
    ItemType, MUST use 2 as value ("all items")
    The check value is used by the DPI service to verify API requests. It is a Base64 hash generated by applying the HMAC SHA256 algorithm on a concatenated string of parameters using the DPI security key.
    You can see the example how to generate checkValue from the following Code example.
    You can use any open library to generate the HMAC SHA256 hash. The following example uses the CryptoJS library
  • serverType : Billing server type
  • onsuccess : Returns the purchase list if there is no internal error occurs until client to server data communication
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 4.0

Code Example :

var strSecurityKey = ""; // The DPI security key is issued at the DPI portal.
var strAppId = "";
var strUID = webapis.sso.getLoginUid();
var strCountryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
var strPageNumber = "1";
var reqParams = strAppId + strUID + strCountryCode + "2" + strPageNumber;
var hash = CryptoJS.HmacSHA256(reqParams, strSecurityKey);
var strCheckValue = CryptoJS.enc.Base64.stringify(hash);
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);

Product : TV

Privilege Level : Public

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

Parameters :

  • appId : Application ID
  • invoiceId : Invoice ID of subscription that you want to cancel
  • 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 if there is no internal error occurs until client to server data communication.
    apiResult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it
    when CPStatus value from apiResult is "100000", it means server communication is done properly and other values are valid in returns
  • onerror [optional][nullable] : Optional callback method to invoke if an error occurs before the client to server data communication.
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if serverType contains an invalid value

Since : 4.0

Code Example :

var strAppId = "";
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. However, this api will be replaced by getServiceCountryAvailability after deprecation

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

Product : TV

Privilege Level : Public

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

Parameters :

  • serverType : Billing server
  • onsuccess : Returns the server availability
  • onerror [optional][nullable] : Optional callback method to invoke if an internal error occurs before the client to server data communication
    SecurityError, if the application does not have the privilege to call this method.
    UnknownError, if any other error occurs.

Exceptions :

  • WebAPIException
    • with error type TypeMismatchError, if any of input parameter is not compatible with its expected type
    • with error type InvalidValuesError, if any input parameter contains an invalid value.

Since : 4.0

Deprecated : 5.5

Code Example :

var onsuccess = function(data) {};
var onerror = function(error) {};
webapis.billing.isServiceAvailable("DEV", onsuccess, onerror)

getVersion

Retrieves the Billing API version.

DOMString getVersion();

Product : TV

Privilege Level : Public

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

Return Value :

  • DOMString : Billing API version

Exceptions :

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

Since : 4.0

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

Privilege Level : Public

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

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 {
  attribute DOMString payResult;
  attribute DOMString payDetail;
};

Attributes

  • DOMString payResult
    Payment result
  • DOMString payDetail
    Payment information. It is same with paymentDetails param of buyItem.

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

Privilege Level : Public

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

Parameters :

  • data : It includes getProductList API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  var resProductsList = JSON.parse(data.apiResult);
  if(resProductsList.CPStatus == "100000") {
    // 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(ApplyInvoiceData data);

Privilege Level : Public

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

Parameters :

  • data : It includes applyInvoice API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  resApplyProduct = JSON.parse(data.apiResult);
  if(resApplyProduct.CPStatus == "100000") {
    // 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);

Privilege Level : Public

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

Parameters :

  • data : It includes verifyInvoice API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  resVerifyPurchase = JSON.parse(data.apiResult);
  if(resVerifyPurchase.CPStatus == "100000") {
    // 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);

Privilege Level : Public

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

Parameters :

  • data : It includes getUserPurchaseList API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  resPurchasesList = JSON.parse(data.apiResult);
  if(resPurchasesList.CPStatus == "100000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.9 BillingGetServiceCountryAvailabilityCallback

Defines the Get Service Country Availability callback.

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

Methods

onsuccess

Callback method returning availability of country list status.

void onsuccess(ServiceCountryAvailabilityData data);

Privilege Level : Public

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

Parameters :

  • data : It includes getServiceCountryAvailability API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  resServiceCountryAvailability = JSON.parse(data.apiResult);
  if(resServiceCountryAvailability.CPStatus == "100000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.10 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(CancelSubscriptionData data);

Privilege Level : Public

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

Parameters :

  • data : It includes cancelSubscription API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

void onsuccess(data) {
  resCancelSubscription = JSON.parse(data.apiResult);
  if(resCancelSubscription.CPStatus == "100000") {
    // Implement success logic
  } else {
    // Implement cancel or fail logic
  }
}

2.11 BillingIsServiceAvailableCallback

Defines the service availability check success callback.

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

Deprecated : 5.5

Methods

onsuccess

Callback method returning the service availability check status.

void onsuccess(ServiceAvailableData data);

Privilege Level : Public

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

Parameters :

  • data : It includes isServiceAvailable API result. but you can't use it as it is. you have to parse it as JSON format data.

Code Example :

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

3. Full WebIDL

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

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

  dictionary ProductsListData {
    DOMString apiResult;
  };

  dictionary ProductsListAPIResult {
    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 apiResult;
  };

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

  dictionary VerifyInvoiceData {
    DOMString apiResult;
  };

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

  dictionary UserPurchaseData {
    DOMString apiResult;
  };

  dictionary GetUserPurchaseListAPIResult {
    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 ServiceCountryAvailabilityData {
    DOMString apiResult;
  };

  dictionary GetServiceCountryAvailabilityAPIResult {
    DOMString CPStatus;
    DOMString? CPResult;
    Countries[]? CountryAvailability;
  };

  dictionary Countries {
    DOMString CountryCode;
    boolean IsBillingSupported;
  };

  dictionary CancelSubscriptionData {
    DOMString apiResult;
  };

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

  dictionary ShowRegisterPromotionalCodeData {
    DOMString openDeepLinkResult;
    DOMString openDeepLinkDetail;
  };

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

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

  dictionary ShowPurchaseHistoryData {
    DOMString openDeepLinkResult;
    DOMString openDeepLinkDetail;
  };

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

  dictionary ServiceAvailableData {
    DOMString apiResult;
  };

  dictionary ServiceAvailableAPIResult {
    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 getServiceCountryAvailability(DOMString appId, DOMString[] countryCodes, DOMString checkValue, TVServerType serverType, BillingGetServiceCountryAvailabilityCallback 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 {
    attribute DOMString payResult;
    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 BillingGetServiceCountryAvailabilityCallback {
    void onsuccess(ServiceCountryAvailabilityData data);
  };

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

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

};