Implementing the Purchase Process

This topic describes how to implement a billing system for managing products, sales, and payments, by using Samsung Checkout in your application.

Related Info

Samples

Implement a billing system for in-app purchases in your application, by using Samsung Checkout through the DPI service APIs and the Billing API.

Prerequisites

To implement in-app purchases:

  1. Before you start implementing Samsung Checkout in your application, start registering your application at the Samsung Apps TV Seller Office. You do not need to complete the registration with your source code at this point. To be able to use the DPI portal, you need to proceed to the second step of the App Registration Page and set the "Billing" field to "Use" and the "Samsung Checkout on TV" field to "Yes". You can save the registration at this point and return to it later when your source code is complete. For more information, see the Samsung Checkout DPI Portal Guide.

  2. To use the DPI, Billing, ProductInfo, and Sso APIs, the application has to request permission by adding the following privileges to the "config.xml" file:

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

  3. To use the methods of the Billing, ProductInfo, and Sso APIs, include the “webapis.js” library in the “index.html” file:

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

  4. Initialize the required variables:

    1. Retrieve the User ID:
      var UniqueCustomId = "123"; // Unique ID for this user. "123" is a one of the example for Unique custom id. you can assign id managed by your service
    1. Retrieve the country code:
    var countryCode = webapis.productinfo.getSystemConfig(webapis.productinfo.ProductInfoConfigKey.CONFIG_KEY_SERVICE_COUNTRY);
    1. Retrieve the server type:
    var strTVServer = webapis.productinfo.getSmartTVServerType();
    1. Set the DPI URL and service environment depending on the server type:
    strUrlDPI = "https://checkoutapi.samsungcheckout.com/openapi";
strServer = "PRD";
strSecurityKey = "********";

DPI Service APIs

You can use the APIs provided by the DPI service to manage products and sales. The DPI service APIs communicate data in JSON format, using the POST method.

Generating Check Values

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

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

To generate the check value, the following 2 items are used as parameters:

  • Concatenation of the required parameters

    For example, “12345”+”123”+”US”+”2”+”1” is concatenated to “12345123US21”.

    The required parameters vary depending on the API.
  • DPI security key

    The DPI security key is issued at the DPI portal.

You can use any open library to generate the HMAC SHA256 hash. The following example uses the CryptoJS library:

var appId = "1234567890"; // Your application ID
var UniqueCustomID = "yourUniqueID"; // Retrieved during initialization
var countryCode = "US"; // Retrieved during initialization
var itemType = "2"; // Request value for "invoice/list" API
var pageNumber = 1; // Request value for "invoice/list" API

var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.CustomID = UniqueCustomID; // Same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code
detailObj.ItemType = itemType; // "2": all items
detailObj.PageNumber = pageNumber;
var reqParams = detailObj.AppID + detailObj.CustomID + detailObj.CountryCode + detailObj.ItemType + detailObj.PageNumber;
/* Required Parameters
   [invoice/list] Request : appId + UniqueCustomID + countryCode + itemType + pageNumber
   [cont/list] Request : appId + countryCode
   Response : CPStatus, CPResult, TotalCount, ItemID(Seq)
*/

var hash = CryptoJS.HmacSHA256(reqParams , securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

Requesting User Purchases

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

To call the Purchase List API:

// Generate CheckValue
var reqParams = detailObj.AppID + detailObj.CustomID + detailObj.CountryCode + detailObj.ItemType + detailObj.PageNumber;
/* Required Parameters
   [invoice/list] Request : appId + UniqueCustomID + countryCode + itemType + pageNumber
   [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: urlDPI + "/invoice/list",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout sample application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
  console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Purchase List API request and response data are in JSON format:

  • Purchase List API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

    Table 1-1. Purchase List API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "CustomID" Unique Customer ID
    Same value as the "OrderCustomID" parameter for the buyItem() method.
    "CountryCode" Country code
    The country code must be retrieved from the TV.
    "ItemType" Product type
    Possible values:
    • "1": NON-CONSUMABLE and LIMITED-PERIOD items
    • "2": All items
    "PageNumber" Number Requested page number
    Range: 1~N
    Each purchase record page has up to 100 entries. To receive the complete purchase record, post Purchase List API requests while increasing the "PageNumber" value, until "EOF" is returned in the "CPResult" parameter.
    "CheckValue" String Security check value
    Required parameters: "AppID" + "CustomID" + "CountryCode" + "ItemType" + "PageNumber"

    Table 1-2. Purchase List API request parameters (Body)

  • Purchase List API response parameters:

    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" False Result message:
    • "EOF": Last page of the purchase history
    • "hasNext:TRUE": Purchase history has further pages
    • Other message corresponding to the "CPStatus" error code
    "TotalCount" Number True Total number of invoices
    Sum of all purchase history pages, or sum of purchase history in the specified time period.
    "CheckValue" String Security check value
    Required parameters: "CPStatus" + "CPResult" + "TotalCount" + "InvoiceDetails[0].ItemID" + … + "InvoiceDetails[TotalCount].ItemID"
    "InvoiceDetails" JSON False Invoice information
    "Seq" Number True Sequence number
    Range: 1 ~ TotalCount
    "InvoiceID" String Invoice ID
    (Subscription ID is used If it's a regular payment product type)
    "ItemID" Product ID
    "ItemTitle" Product name
    "ItemType" Number Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
    The response "ItemType" value differs from the request "ItemType" value. The response value contains more detail.
    "OrderTime" String Payment time, in 14-digit UTC time
    "Period" Number False Limited period product duration, in minutes
    "Price" True Product price, in "xxxx.yy" format
    "OrderCurrencyID" String Currency code
    "CancelStatus" Boolean Cancellation status:
    • "true": Sale canceled
    • "false": Sale ongoing
    For subscription products, indicates the cancellation status for the next subscription cycle.
    "AppliedStatus" Product application status:
    • "true": Applied
    • "false": Not applied
    For subscription products, the default value is "true".
    "AppliedTime" String False Time product applied, in 14-digit UTC time
    "LimitEndTime" True
    (For limited period products only)

    		 Limited period product end time, in 14-digit UTC time
    If the product has not been applied, "LimitEndTime" = ""
    "RemainTime" Limited period product time remaining, in seconds
    "RemainTime" = "LimitEndTime" – request time
    If the product has not been applied, "RemainTime" = ""
    "SubscriptionInfo" JSON False Subscription information 
    Mandatory for subscription products.
    "SubscriptionId" String True Subscription ID
    "SubsStartTime" Subscription start time, in 14-digit UTC time
    "SubsEndTime" Subscription expiry time, in 14-digit UTC time
    "SubsStatus" Subscription status:
    • "00": Active
    • "01": Subscription expired
    • "02": Canceled by buyer
    • "03": Canceled for payment failure
    • "04": Canceled by CP
    • "05": Canceled by admin
    • "06": Canceled by GDPR restriction
    • "07": Canceled by withdrawn account
    • "08": Canceled by unused account
    • "09": Canceled by misused blocked account
    • "10": Canceled by blacklist blocked account
    "LastPaymentAmount" Latest payment amount, in "xxxx.yy" format
    "LastPaymentTime" Latest payment time, in 14-digit UTC time
    "NextCycleTime" Next payment time, in 14-digit UTC time
    (The time calculated based on the billing cycle of the subscription and the SubsStartTime)
    "NextPaymentTime" Next actaul payment time, in 14-digit UTC time
    (The time payment actually occurs using user's payment method)
    "IsFreeTrialPeriod" Boolean Information about whether the subscription is currently in Free-trial period
    • "true": In Free-trial period
    • "false": Not in Free-trial period
    (If the first payment fails after the end of the Free-trial,
    Samsung will attempt to make a second payment after one day in accordance with Samsung's policy.
    During this grace period, the IsFreeTrialPeriod value would be returned as true.)
    "CountryCode" String ISO3166-1 alpha2 Country Code (Upper Case)
    Base Country code of this subscription.
    Currently, we use the country code was set on TV at the time of joining to this subscription.

    Table 2. Purchase List API response parameters

Requesting Products for Sale

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

To call the Products List API:

// Generate checkValue
var reqParams = detailObj.AppID + detailObj.CountryCode;
/* Required Parameters
   [cont/list] Request : appId + countryCode
   [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/cont/list",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Products List API request and response data are in JSON format:

  • Products List API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

    Table 3-1. Products List API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "CountryCode" Country code
    The country code must be retrieved from the TV.
    "ProductIDList" String[] False Products present in this list are included in the response even if the product value is "optional", otherwise they are not included.
    "PageSize" Number False Requested page size
    Range: 1~N (maximum 100)
    Number of products retrieved per page.
    "PageNumber" Requested page number
    Range: 1~N
    Each purchase record page has a number of entries equal to the "PageSize" value. To receive the complete purchase record, post Purchase List API requests while increasing the "PageNumber" value, until "EOF" is returned in the "CPResult" parameter.
    "CheckValue" String True Security check value
    Required parameters: "AppID" + "CountryCode"

    Table 3-2. Products List API request parameters (Body)

  • Product List API response parameters

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

    Table 4. Products List API response parameters

Verifying Purchases

The Verify Purchase API ("invoice/verify") checks whether a purchase, corresponding to the requested "InvoiceID", was successful.

To call the Verify Purchase API:

/* Required Parameters
   [invoice/verify] Request
*/
var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.InvoiceID = unCanceledItems[key].InvoiceID; // Issued by "invoice/list"
detailObj.CustomID = UniqueCustomID; // Same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code

var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/invoice/verify",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Verify Purchase API request and response data are in JSON format:

  • Verify Purchase API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

    Table 5-1. Verify Purchase API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "InvoiceID" Invoice ID
    "CustomID" Unique Customer ID
    Same value as the "OrderCustomID" parameter for the buyItem() method.
    "CountryCode" Country code
    The country code must be retrieved from the TV.

    Table 5-2. Verify Purchase API request parameters (Body)

  • Verify Purchase API response parameters:

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

    Table 6. Verify Purchase API response parameters

Applying Products

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

For subscription products, the product is considered applied at the time of purchase and the "AppliedStatus" is set to "true" by default. Consequently, it is not necessary to check whether a subscription product purchase corresponding to the requested "InvoiceID" was successful.

To call the Apply Product API:

/* Required Parameters
   [invoice/apply] Request
*/

var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.InvoiceID = unCanceledItems[key].InvoiceID; // Issued by "invoice/list"
detailObj.CustomID = UniqueCustomID; // Same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code

var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/invoice/apply",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Apply Product API request and response data are in JSON format:

  • Apply Product API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

    Table 7-1. Apply Purchase API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "InvoiceID" Invoice ID
    "CustomID" Unique Customer ID
    Same value as the "OrderCustomID" parameter for the buyItem() method.
    "CountryCode" Country code
    The country code must be retrieved from the TV.

    Table 7-2. Apply Purchase API request parameters (Body)

  • Apply Product API response parameters:

    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" False Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "AppliedTime" True Time product applied, in 14-digit UTC time

    Table 8. Apply Product API response parameters

Canceling Subscriptions

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

To call the Subscription Cancel API:

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

var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.InvoiceID = unCanceledItems [key].InvoiceID; // Issued by "invoice/list"
detailObj.CustomID = UniqueCustomID; // Same value as OrderCustomID parameter for buyItem()
detailObj.CountryCode = countryCode; // TV country code

var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/cancel",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Cancel API request and response data are in JSON format:

  • Subscription Cancel API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

    Table 9-1. Subscription Cancel API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "InvoiceID" Invoice ID
    "CustomID" Unique Customer ID
    Same value as the "OrderCustomID" parameter for the buyItem() method.
    "CountryCode" Country code
    The country code must be retrieved from the TV.

    Table 9-2. Subscription Cancel API request parameters (Body)

  • Subscription Cancel API response parameters:

    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" False Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "InvoiceID" True Invoice ID
    "SubsCancelTime" False Time subscription canceled, in 14-digit UTC time
    "SubsStatus" Subscription status:
    • "02": Canceled by buyer

    Table 10. Subscription Cancel API response parameters

Checking Billing Service Available Country/Location

The /country/checkavailability API provides Billing service availability information for requested countrycodes.

To call the Billing Service Available Country Check API:

/* Required Parameters
   [country/checkavailability] Request : appId + countryCodes + checkValue
*/

var detailObj = new Object();
detailObj.AppID = appId; // Your application ID
detailObj.CountryCodes = countryCodes; // TV countrycodes you want to check. Multi countrycodes available.

var reqParams = detailObj.AppID + detailObj.CountryCodes;
var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;

var countryCheckDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/country/checkavailability",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: countryCheckDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

Billing Service Available Country Check API request and response data are in JSON format:

  • Billing Service Available Country Check API request parameters:

    Parameter Mandatory Description
    "Content-Type" True Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Content-Type: application/json;charset=UTF-8
    "Accept" Media Type used for Client
    • Allowed : [ application/json ]
    • ex) Accept: application/json

    Table 11-1. Billing Service Available Country Check API request parameters (Header)

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "CountryCodes" Countrycodes to check. Multiple countrycodes available. (Only Uppercase allowed)
    • ex) CountryCodes=DE,US,KR
    "CheckValue" Security check value
    Required parameters: "AppID" + "CountryCodes"
    For multiple countrycodes, please use comma(,) removed and trimmed data.
    • ex) CountryCodes=DE,US,KR then use "DEUSKR" for making CheckValue.

    Table 11-2. Billing Service Available Country Check API request parameters (Body)

  • Billing Service Available Country Check API response parameters:

    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "Countries" JSON False Countrycodes and info
    "CountryCode" String True Countrycode
    "IsBillingSupported" Boolean Billing service support status.
    • "true": Billing service supported
    • "false": Billing service not supported

    Table 12. Billing Service Available Country Check API response parameters

DPI Result Codes

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

Result Code Result Message Description
100000 "SUCCESS" Additional messages:
  • "hasNext:TRUE": Product list or purchase history has further pages
  • "EOF": Last page of the product list or purchase history
  • "Your Invoice Not Found": No purchase history exists
400111 "AppID not correct" Requested application ID does not exist

Table 13. DPI result codes and messages

For explanations of additional DPI result codes, at the DPI portal, go to "Help > Error Code".

Billing API

To implement the Samsung Checkout functionality, use the Billing API.

When the user wants to make a purchase, authenticate the user and show the common purchase GUI with the buyItem() method.

You can customize the product image in Samsung Checkout by providing the URI to an image on your own content server.

Default image Product image

Table 14. Display your own product image

To implement Samsung Checkout:

var detailObj = new Object();
detailObj.OrderItemID = productsList.ItemDetails[selectedItem].ItemID; // Issued by "cont/list"
detailObj.OrderTitle = productsList.ItemDetails[selectedItem].ItemTitle; // Issued by "cont/list"
detailObj.OrderTotal = productsList.ItemDetails[selectedItem].Price.toString(); // Change datatype to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // optional value
var UniqueCustomId = "123"; // Unique ID for this user. "123" is a one of the example for Unique custom id. you can assign id managed by your service
detailObj.OrderCustomID = UniqueCustomId; // Same value as "CustomID" parameter for "invoice/list"

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

The buyItem() method request and response data are in JSON format:

  • buyItem() method request parameters:

    Parameter Type Mandatory Maximum length
    (characters)

    		 Description
    "AppID" String True 30 Application ID provided by Samsung Seller Office
    "PaymentServer" - Possible values:
    • "PRD": Operating zone
    "PaymentDetails" JSON Payment details
    "OrderItemID" String True 30 Purchase item ID, for example, "DP123400000000"
    "ItemID" issued by the Products List API.
    when Dynamic product, need verification via "productId" of Verify Product
    "OrderTitle" 100 Purchase item title
    "ItemTitle" issued by the Products List API.
    when Dynamic product, use customized value instead.
    "OrderTotal" 20 Total purchase price
    "Price" issued by the Products List API.
    When converting the number to string type, pay attention to the unit separators.
    when Dynamic product, use customized value instead and it needs verification via "productPrice" of Verify Product
    "OrderCurrencyID" 10 Purchase currency unit
    "CurrencyID" issued by the Products List API.
    "OrderID" False 50 Management ID for purchases managed by third-party applications
    "OrderCustomID" True 100 Unique customer ID
    "OrderItemPath" False - Item image URI
    The image must be in JPEG, JPG, or PNG format.
    "DynmcProductID" True
    (dynamic products only)

    		 100 Unique ID for dynamic product from a third-party application
    when Dynamic product, need verification via "dynmcProductID" of Verify Product
    "DynmcProductInfo" False Dynamic product item type, such as rental or permanent purchase
    For dynamic products only.
    "DynmcShareCategory" 20 Share category
    For dynamic products only.
    "DynmcTaxCategory" 30 Tax category
    For dynamic products only.
    "StltAppId" Settlement application ID
    For Samsung internal use only. Do not use.

    Table 15. buyItem() request parameters

  • buyItem() method response parameters:

Parameter Type Mandatory Description
"payResult" String True Possible values:
  • “SUCCESS”
  • “FAILED”
  • “CANCEL”: Canceled by the user
"payDetail" JSON False Payment details
"InvoiceID" String False Purchased Invoice ID, for example, "DO1904US000007153", this value is only available when payResult is "SUCCESS" otherwise, you will not get any value for "InvoiceID"

Table 16. buyItem() response parameters

Dynamic Product

Verify Product Information

Available to be used only when the product type is dynamic product.

  • To check dynamic product information from DPI server to CP CMS. DPI server calls the API if ‘Verification’ is selected on DPI Portal.

  • API URL

    Operating Zone (PRD) : ‘Verify URI’ entered in the DPI Portal of operating zone.

POST https://xxxxxxxx.com/xxxx/cp/verify HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json;charset=UTF-8
Accept : application/json;charset=UTF-8
Content-Length: 391
Host: xxxx.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "countryCode": "ES",
  "orderTime": "20181017213438",
  "checkValue": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "productDetail": {
    "appId": "3201505000000",
    "productId": "RENT_PROD",
    "productPrice": "1.58",
    "productCurrencyCode": "USD",
    "orderCustomId": "xxxxxxxx",
    "dynmcProductID": "RENT_OPTION_4537",
    "dynmcProductInfo": "RENT_OPTION_4537"
  }
}

  • Verify Product method request parameters:

    Parameter Type Mandatory Maximum length
    (characters)

    		 Description
    "countryCode" String True 10 ISO3166-1 alpha2 Country Code (Upper Case)
    "orderTime" String True 20 Order time (UTC-zero)
    (20140314175900)
    "checkValue" String True 200 [Security Hash Code]
    * Necessary Parameters : appID + dynmcProductID + productId + productPrice + productCurrenyCode
    "productDetail" JSON True - Product details
    "appId" String True 30 Application ID
    Same value as the "AppID" parameter for the buyItem() method.
    "productId" True 30 Set ItemID Item purchase
    Same value as the "OrderItemID" parameter for the buyItem() method.
    "productPrice" True 10 AppID or ItemID Price(Unit Price)
    Same value as the "OrderTotal" parameter for the buyItem() method.
    "productCurrencyCode" True 10 Currency Code (ex. USD)
    Same value as the "OrderCurrencyID" parameter for the buyItem() method.
    "orderCustomId" False 100 Unique customer ID
    Same value as the "OrderCustomID" parameter for the buyItem() method.
    "dynmcProductID" True 100 dynmcProductID is the unique ID or string to track the product from the 3rd party application.
    Same value as the "DynmcProductID" parameter for the buyItem() method.
    "dynmcProductInfo" False 100 dynamic product Information
    Same value as the "DynmcProductInfo" parameter for the buyItem() method.
    "dynmcShareCategory" False 20 Share Category of dynamic product
    Same value as the "DynmcShareCategory" parameter for the buyItem() method.
    "dynmcTaxCategory" False 30 Tax Category of dynamic product
    Same value as the "DynmcTaxCategory" parameter for the buyItem() method.

    Table 17. Verify Product request parameters

  • response parameters:

    Parameter Type Mandatory Length Description
    "status" String True 9 Possible values:
    • “100000” (Success)
    • “ErrorCode” (Failure)

      • Refer to the embedded Error Code file
    "result" String True 100 Result Message (displayed at Smart TV screen))
    “Success” or “Error Short Message”
    "resultLongMesg" String False 200 Error Long Message for developer when Debug mode is true

    Table 18. Verify Product response parameters

Country and Currency Codes

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

Country Name Country Code Currency Currency Code
Aland Islands AX Euro Member Countries EUR
Albania AL United States Dollar USD
Algeria DZ Algeria Dinar DZD
Argentina AR Argentina Peso ARS
Australia AU Australia Dollar AUD
Austria AT Euro Member Countries EUR
Bahrain BH Bahraini dinar BHD
Belarus BY Belarus Ruble BYN
Belgium BE Euro Member Countries EUR
Bolivia, Plurinational State of BO United States Dollar USD
Bosnia and Herzegovina BA United States Dollar USD
Brazil BR Brazil Real BRL
Bulgaria BG Bulgaria Lev BGN
Canada CA Canada Dollar CAD
Chile CL Chile Peso CLP
Colombia CO Colombia Peso COP
Costa Rica CR United States Dollar USD
Croatia HR Croatia Kuna HRK
Czech Republic CZ Czech Republic Koruna CZK
Denmark DK Denmark Krone DKK
Dominican Republic DO United States Dollar USD
Ecuador EC United States Dollar USD
Egypt EG Egypt Pound EGP
Estonia EE Euro Member Countries EUR
Faroe Islands FO Denmark Krone DKK
Finland FI Euro Member Countries EUR
France FR Euro Member Countries EUR
Germany DE Euro Member Countries EUR
Greece GR Euro Member Countries EUR
Greenland GL Denmark Krone DKK
Guatemala GT Guatemala Quetzal GTQ
Guernsey GG United Kingdom Pound GBP
Hong Kong HK Hong Kong Dollar HKD
Hungary HU Hungary Forint HUF
Iceland IS United States Dollar USD
India IN India Rupee INR
Indonesia ID Indonesia Rupiah IDR
Iraq IQ Iraqi dinar IQD
Ireland IE Euro Member Countries EUR
Isle of Man IM United Kingdom Pound GBP
Israel IL Israel Shekel ILS
Italy IT Euro Member Countries EUR
Jersey JE United Kingdom Pound GBP
Jordan JO Jordanian dinar JOD
Kazakhstan KZ Kazakhstan Tenge KZT
Korea, Republic of KR Korea (South) Won KRW
Kuwait KW Kuwait Dinar KWD
Kyrgyzstan KG United States Dollar USD
Latvia LV Euro Member Countries EUR
Lebanon LB Lebanon Pound LBP
Libya LY Libyan Dinar LYD
Lithuania LT Euro Member Countries EUR
Luxembourg LU Euro Member Countries EUR
Macedonia, the Former Yugoslav Republic of MK United States Dollar USD
Malaysia MY Malaysia Ringgit MYR
Mexico MX Mexico Peso MXN
Moldova, Republic of MD United States Dollar USD
Mongolia MN United States Dollar USD
Montenegro ME United States Dollar USD
Morocco MA Moroccan Dirham MAD
Netherlands NL Euro Member Countries EUR
New Zealand NZ New Zealand Dollar NZD
Norway NO Norway Krone NOK
Oman OM Oman Rial OMR
Pakistan PK United States Dollar USD
Panama PA United States Dollar USD
Peru PE Peru Nuevo Sol PEN
Philippines PH Philippines Peso PHP
Poland PL Poland Zloty PLN
Portugal PT Euro Member Countries EUR
Qatar QA Qatar Riyal QAR
Romania RO Euro Member Countries EUR
Russian Federation RU Russia Ruble RUB
Saudi Arabia SA Saudi Arabia Riyal SAR
Serbia RS Serbia Dinar RSD
Singapore SG Singapore Dollar SGD
Slovakia SK Euro Member Countries EUR
Slovenia SI Euro Member Countries EUR
South Africa ZA South Africa Rand ZAR
Spain ES Euro Member Countries EUR
Sweden SE Sweden Krona SEK
Switzerland CH Switzerland Franc CHF
Taiwan TW Taiwan New Dollar TWD
Tajikistan TJ United States Dollar USD
Thailand TH Thailand Baht THB
Tunisia TN Tunisian dinar TND
Türkiye TR Türkiye Lira TRY
Turkmenistan TM United States Dollar USD
Ukraine UA Ukraine Hryvna UAH
United Arab Emirates AE United Arab Emirates dirham AED
United Kingdom GB United Kingdom Pound GBP
United States US United States Dollar USD
Uzbekistan UZ United States Dollar USD
Venezuela, Bolivarian Republic of VE United States Dollar USD
Vietnam VN Viet Nam Dong VND
Yemen YE Yemen Rial YER

Table 19. Country and currency codes

Changing Subscription Plans

Getting the Available Products for a Subscription Plan Change

Get the list of products that can be changed in this subscription.

To call the Subscription Plan Change Changeable-products API:

// Generate checkValue
var reqParams = detailObj.AppID + detailObj.SubscriptionID + detailObj.Timestamp;
/* Required Parameters
  [subscription/plan-change/changeable-products] Request : appId + subscriptionID + timestamp
  [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/plan-change/changeable-products",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Plan Change Changeable-products API request and response data are in a JSON format:

  • Subscription Plan Change Changeable-products API request parameters:
    Parameter Mandatory Description
    "Content-Type"
    True
    		 Indicates a data type located in the body of a request or response message.
    • Allowed : [ application/json;charset=UTF-8 | application/x-www-form-urlencoded ]
    • For example, Content-Type: application/json;charset=UTF-8
      Content-Type: application/x-www-form-urlencoded
    When using the [application/x-www-form-urlencoded] type, be careful not to include any spaces (' ') in the message body.
    "Accept" Media Type used for the Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • For example, Accept: application/json;charset=UTF-8

Table 20-1. Subscription Plan Changeable-products request parameters (Header)

Parameter Type Mandatory Description
"AppID"
String
True
 Application ID
"SubscriptionID" Subscription ID
"ProductIDList"
String[]
False
 Products present in this list are included in the response even if the product value is "optional", otherwise they are not included.
"Timestamp"
String
True
 Format:"yyyy-MM-dd HH:mm:ss".

The time needs to be within 10 minutes from the current time, based on UTC.
"CheckValue" Encrypted value with "AppID + SubscriptionID + Timestamp" and appSecretKey.
Refer to Generating Check Values for more information.
Table 20-2. Subscription Plan Changeable-products request parameters (Body)
  • Subscription Plan Change Changeable-products API response parameters:
    Parameter Type Mandatory Description
    "CPStatus" String True Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "ChangeableProducts" JSON True
      "Seq" Number True Sequence number
    • Range: 1 ~ TotalCount
    "ItemID" String Product ID
    "ItemTitle" Product name
    "ItemType" Number Product type:
    • "1": CONSUMABLE
    • "2": NON-CONSUMABLE
    • "3": LIMITED-PERIOD
    • "4": SUBSCRIPTION
    The response "ItemType" value differs from the request "ItemType" value. The response value contains more detail.
    "Period" Number False Limited period product duration, in minutes
    "Price" True Product price, in the "xxxx.yy" format
    "CurrencyID" String Currency code (ISO 4217)
    "SubscriptionInfo" JSON False Mandatory for subscription products
      "ProductGroupID" String True Subscription Product Group ID
    "ProductLevel" Number Product Level in the Subscription Product Group
    "PaymentCyclePeriod" String Subscription payment period:
    • "W": Weeks
    • "M": Months
    • "Y": Years

    "PaymentCycleFrq" Number Payment cycle frequency
    "PaymentCycle" Number of payment cycles
    "freeTrialDayCount" Number of free trial days for a product

Table 21. Subscription Plan Changeable-products response parameters

Pre-checking Subscription Plan Changes

You can pre-check the impact of changing subscription products.

To call the Subscription Plan Change Pre-check API:

// Generate checkValue
var reqParams = detailObj.AppID + detailObj.SubscriptionID + detailObj.AfterProductID + detailObj.Timestamp;
/* Required Parameters
  [subscription/plan-change/pre-check] Request : appId + subscriptionId + afterProductId + timestamp
  [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/plan-change/pre-check",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Plan Change Pre-check API request and response data are in a JSON format:

  • Subscription Plan Change Pre-check API request parameters:

    Parameter Mandatory Description
    "Content-Type"
    True
    		 Indicates a data type located in the body of a request or response message.
    • Allowed : [ application/json;charset=UTF-8 | application/x-www-form-urlencoded ]
    • For example, Content-Type: application/json;charset=UTF-8
      Content-Type: application/x-www-form-urlencoded
    When using the [application/x-www-form-urlencoded] type, be careful not to include any spaces (' ') in the message body.
    "Accept" Media Type used for the Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • For example, Accept: application/json;charset=UTF-8

    Table 22-1. Subscription Plan Change Pre-check request parameters (Header)

    Parameter Type Mandatory Description
    "AppID"
    String
    True
    		 Application ID
    "SubscriptionID" Subscription ID
    "AfterProductID" Product ID
    "Timestamp" Format: "yyyy-MM-dd HH:mm:ss".
    The time needs to be within 10 minutes from the current time, based on UTC.
    "CheckValue" Encrypted value with "AppID + SubscriptionID + AfterProductID + Timestamp" and appSecretKey.
    Refer to Generating Check Values for more details.

Table 22-2. Subscription Plan Change Pre-check request parameters (Body)

  • Subscription Plan Change Pre-check API response parameters:
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    		 Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "CurrentProductName" Product name currently in use
    "CurrentBenefit"
    JSON
    False
    		 Mandatory if there is a benefit currently in use
      "Type"
    String
    True
    		 Benefit type currently in use
    • FREE_TRIAL
    • COUPON
    "FreeTrialDays"
    Integer
    		 Number of free trial days for products currently in use.
    '0' is returned if free trial is not in use.
    "CouponName"
    String
    False
    		 Coupon name applied to the products currently in use
    "EndDate"
    True
    		 Format: "yyyy-MM-dd"
    • [Type:FREE_TRIAL] The free trial end date
    • [Type:COUPON] The end date of coupon benefit
    "AfterProductName" Product name after change
    "AfterProductPrice"
    Number
    		 Product Price
    "AfterProductPriceTaxIncluded"
    Boolean
    • [If product price includes tax] true
    • [If product price doesn't include tax] false
    "AfterProductFirstPaymentDate"
    String
    		 Estimated date of first payment of changed product (in the format "yyyy-MM-dd").
    Adds the free trial days of the product to be changed.
    [For cases other than upgrade] Adds the benefit period currently in use.
    "ProductCurrencyCode" Currency Code
    "DaysUntilFirstPaymentDate"
    Integer
    False
    		 Mandatory for an upgrade case.
    The number of days the upgraded product can be used without any additional payment.
    Includes any free trial days for the product to be upgraded.
    '0' is returned if a free trial period is currently active and in this case, no free trial benefits of products to be upgraded are returned.

Table 23. Subscription Plan Change Pre-check response parameters

Reserving Subscription Plan Changes

To call the Subscription Plan Change Reserve API:

// Generate checkValue
var reqParams = detailObj.AppID + detailObj.SubscriptionID + detailObj.AfterProductID + detailObj.Timestamp;
/* Required Parameters
  [subscription/plan-change/reserve] Request : appId + subscriptionId + afterProductId + timestamp
  [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/plan-change/reserve",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Plan Change Reserve API request and response data are in a JSON format:

  • Subscription Plan Change Reserve API request parameters:
    Parameter Mandatory Description
    "Content-Type"
    True
    		 Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8 | application/x-www-form-urlencoded ]
    • For example, Content-Type: application/json;charset=UTF-8
      Content-Type: application/x-www-form-urlencoded
    When using the [application/x-www-form-urlencoded] type, be careful not to include any spaces (' ') in the message body.
    "Accept" Media Type used for the Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • For example, Accept: application/json;charset=UTF-8

Table 24-1. Subscription Plan Change Reserve request parameters (Header)

Parameter Type Mandatory Description
"AppID"
String
True
 Application ID
"SubscriptionID" Subscription ID
"AfterProductID" Product ID
"Timestamp" Format: "yyyy-MM-dd HH:mm:ss".
The time needs to be within 10 minutes from the current time, based on UTC.
"CheckValue" Encrypted value with "AppID + SubscriptionID + AfterProductID + Timestamp" and appSecretKey.
Refer to Generating Check Values.
"MailLang"
False
 Mail language code to send to users (ISO 639-1 code, in lowercase).
Use 'en' as the default for unsupported languages. (default: en)

Table 24-2. Subscription Plan Change Reserve request parameters (Body)

  • Subscription Plan Change Reserve API response parameters:
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    		 Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "CurrentProductName" Product name currently in use
    "CurrentBenefit"
    JSON
    False
    		 Mandatory if there is a benefit currently in use
      "Type"
    String
    True
    		 Benefit type currently in use
    • FREE_TRIAL
    • COUPON
    "FreeTrialDays"
    Integer
    		 Number of free trial days for products currently in use.
    '0' is returned if a free trial is not in use.
    "CouponName"
    String
    False
    		 Coupon name applied to the products currently in use
    "EndDate"
    True
    		 Format: "yyyy-MM-dd"
    • [Type:FREE_TRIAL] The end date of the free trial
    • [Type:COUPON] The end date of the coupon benefit
    "AfterProductName" Product name after the change
    "AfterProductPrice"
    Number
    		 Product price
    "AfterProductPriceTaxIncluded"
    Boolean
    • [If product price includes tax] true
    • [If product price doesn't include tax] false
    "AfterProductFirstPaymentDate"
    String
    		 Estimated date of first payment for the changed product (in the format "yyyy-MM-dd").
    Adds the free trial days of the product to be changed.
    [For cases other than upgrade] Adds the benefit period currently in use.
    "ProductCurrencyCode" Currency Code
    "DaysUntilFirstPaymentDate"
    Integer
    False
    		 Mandatory for an upgrade case.
    The number of days that the upgraded product can be used without any additional payment.
    Includes any free trial days of the product to be upgraded.
    '0' is returned if a free trial period is currently active and in this case, no free trial benefits of products to be upgraded are returned.

Table 25. Subscription Plan Change Reserve response parameters

Getting Subscription Plan Change Reservation Status

To call the Subscription Plan Change Reservation Status API:

// Generate checkValue
var reqParams = detailObj.AppID;
for (let subscriptionID of detailObj.SubscriptionIDList) {
  reqParams += subscriptionID;
}
for (let customID of detailObj.CustomIDList) {
  reqParams += customID;
}
reqParams += detailObj.Timestamp;
/* Required Parameters
  [subscription/plan-change/reserve-status] Request : appId + subscriptionIdList[0] + ... + subscriptionIdList[N] + customIdList[0] + ... + customIdList[N] + timestamp
  [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/plan-change/reservation-status",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Plan Change Reservation Status API request and response data are in a JSON format:

  • reservation-status API request parameters:

    Parameter Mandatory Description
    "Content-Type"
    True
    		 Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8 | application/x-www-form-urlencoded ]
    • For example, Content-Type: application/json;charset=UTF-8
      Content-Type: application/x-www-form-urlencoded
    When using the [application/x-www-form-urlencoded] type, be careful not to include any spaces (' ') in the message body.
    "Accept" Media Type used for the Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

Table 26-1. Subscription Plan Reservation-status request parameters (Header)

Parameter Type Mandatory Description
"AppID"
String
True
 Application ID
"SubscriptionIDList"
String[]
False
 Subscription ID List.
At least one of 'SubscriptionIDList' or 'CustomIDList' must exist.
"CustomIDList" Custom ID (Unique Customer ID) List.
At least one of 'SubscriptionIDList' or 'CustomIDList' must exist.
"Timestamp"
String
True
 Format: "yyyy-MM-dd HH:mm:ss".

The time needs to be within 10 minutes from the current time, based on UTC.
"CheckValue" Encrypted value with "AppID + SubscriptionIDList[0] + ... + SubscriptionIDList[N] + CustomIDList[0] + ... + CustomIDList[N] + Timestamp" and appSecretKey
Refer to Generating Check Values for more information.

Table 26-2. Subscription Plan Reservation-status request parameters (Body)

  • reservation-status API response parameters:
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    		 Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code
    "ReservedSubscriptions"
    JSON[]
    False
    		 Mandatory if there are reserved subscriptions to change the product
      "SubscriptionID"
    String
    True
    		 Subscription ID
    "CustomID" Custom ID (Unique Customer ID) List
    "AfterProductID" Product ID
    "AfterProductName" Product name after the change
    "ApplyDate" Estimated application date of the product to be changed
    (Format: "yyyy-MM-dd HH:mm:ss")

Table 27. Subscription Plan Reservation-status response parameters

Canceling Subscription Plan Change Reservation

You can cancel a reserved subscription product change.

To call the Subscription Plan Change Cancel Status API:

// Generate checkValue
var reqParams = detailObj.AppID + detailObj.SubscriptionID + detailObj.Timestamp;
/* Required Parameters
  [subscription/plan-change/cancel] Request : appId + subscriptionId + timestamp
  [CheckValue] required
*/

var hash = CryptoJS.HmacSHA256(reqParams, securityKey);
var checkValue = CryptoJS.enc.Base64.stringify(hash);

detailObj.CheckValue = checkValue;
var paymentDetails = JSON.stringify(detailObj);

// Call API
$.ajax({
  url: strUrlDPI + "/subscription/plan-change/cancel",
  type: "POST",
  contentType: "application/json;charset=UTF-8",
  dataType: "JSON",
  data: paymentDetails,
  timeout:10000,
  success: function(res) {
    // For implementation details, see the Samsung Checkout Sample Application
    console.log("success : " + JSON.stringify(res));
  },
  error: function(jqXHR, ajaxOptions, thrownError, request, error) {
    console.log("[Error] thrownError:"+thrownError+";error:"+error+";[Message]:"+jqXHR.responseText);
  },
  complete:function() {
    console.log("complete");
  },
  failure:function() {
    console.log("failure");
  }
});

The Subscription Plan Change Cancel API request and response data are in a JSON format:

  • Subscription Plan Change Cancel API request parameters:
    Parameter Mandatory Description
    "Content-Type"
    True
    		 Indicates data type located in a body of request or response message.
    • Allowed : [ application/json;charset=UTF-8 | application/x-www-form-urlencoded ]
    • For example, Content-Type: application/json;charset=UTF-8
      Content-Type: application/x-www-form-urlencoded
    When using the [application/x-www-form-urlencoded] type, be careful not to include any spaces (' ') in the message body.
    "Accept" Media Type used for the Client
    • Allowed : [ application/json;charset=UTF-8 ]
    • ex) Accept: application/json;charset=UTF-8

Table 28-1. Subscription Plan Change Cancel request parameters (Header)

Parameter Type Mandatory Description
"AppID"
String
True
 Application ID
"SubscriptionID" Subscription ID
"Timestamp" Format: "yyyy-MM-dd HH:mm:ss".
The time needs to be within 10 minutes from the current time, based on UTC.
"CheckValue" Encrypted value with "AppID + SubscriptionID + AfterProductID + Timestamp" and appSecretKey.
Refer to Generating Check Values for more information.
"MailLang"
False
 Mail language code to send to users (ISO 639-1 code, in lowercase).
Use 'en' as the default for unsupported languages. (default: en)

Table 28-2. Subscription Plan Change Cancel request parameters (Body)

  • Subscription Plan Change Cancel API response parameters:
    Parameter Type Mandatory Description
    "CPStatus"
    String
    True
    		 Result code:
    • “100000”: Success
    • “ErrorCode”: Failure
    "CPResult" Result message:
    • "SUCCESS"
    • Other message corresponding to the "CPStatus" error code

Table 29. Subscription Plan Change Cancel response parameters