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 an example value. It can be an 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 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 1. Purchase List API request headers

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

  • Purchase List API request parameters:

    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:
    • "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 2. Purchase List API request parameters

  • 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
    For products with recurring payments, use the Subscription ID.

    "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 Original product price, in "xxxx.yy" format
    This is price without promotion.

    "OrderCurrencyID" String Currency code

    "CancelStatus" Boolean Cancelation status:
    • "true": Sale canceled
    • "false": Sale ongoing
    For subscription products, indicates the cancelation 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" is an empty string.

    "RemainTime" Limited period product time remaining, in seconds
    "RemainTime" = "LimitEndTime" – request time
    If the product has not been applied, "RemainTime" is an empty string.

    "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 banned 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
    This is the time calculated based on the billing cycle of the subscription and the subscription start time.

    "NextPaymentTime" Next actual payment time, in 14-digit UTC time
    This is the time when the payment is charged to the user's payment method.

    "IsFreeTrialPeriod" Boolean Whether the subscription is currently in the free trial period:
    • "true": In free trial period
    • "false": Not in free trial period
    If the first payment after the free trial period fails, a second attempt is made the next day, in accordance with Samsung policy.
    During this grace period, the value of "IsFreeTrialPeriod" is "true".

    "CountryCode" String Base country code for the subscription.
    The value is the country set on the TV when the subscription was started.

    Table 3. 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 4. Products List API request headers

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

  • Products List API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "CountryCode" Country code
    The country code must be retrieved from the TV.

    "ProductIDList" String[] False List of product IDs
    Products in this list are always included in the response even when the product value is "optional" and the product is otherwise 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 5. Products List API request parameters

  • 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[N].ItemID"

    "ItemDetails" JSON False Invoice information
    "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

    "OrderTime" String Payment time, in 14-digit UTC time
    "Period" Number False Limited period product duration, in minutes
    "Price" Number True Product price, in "xxxx.yy" format
    If the product is running a flexible offer, the promotion price is shown during the promotion period, otherwise, the original price is shown.

    "OriginalPrice" Original product price, in "xxxx.yy" format
    This field enables you to keep track of the original price during a flexible offer, when the 'Price' field is changed to the promotion price.
    During the promotion period, if buyItem() is called using the original price, eligible users still pay the promotion price.

    "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" Number of free trial days for the product

    Table 6. 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 7. Verify Purchase API request headers

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

  • Verify Purchase API request parameters:

    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 8. Verify Purchase API request parameters

  • 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 9. 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 10. Apply Purchase API request headers

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

  • Apply Product API request parameters:

    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 11. Apply Purchase API request parameters

  • 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 12. Apply Product API response parameters

Modifying Subscription Plans

Retrieve Changeable Products

The Subscription Plan Changeable Products API ("/subscription/plan-change/changeable-products") retrieves the list of products that a user's subscription can be changed to.

To call the Subscription Plan 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 Changeable Products API has the following request headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 13. Subscription Plan Changeable Products API request headers

The Subscription Plan Changeable Products API request and response data are in JSON format:

  • Subscription Plan Changeable Products API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "SubscriptionID" Subscription ID
    "ProductIDList" String[] False List of product IDs
    Products in this list are always included in the response even when the product value is "optional" and the product is otherwise not included.

    "Timestamp" String True Timestamp
    Format: "yyyy-MM-dd HH:mm:ss".
    The time is in UTC time and must be within 10 minutes from the current time.

    "CheckValue" Security check value
    Required parameters: "AppID" + "SubscriptionID" + "Timestamp"

    Table 14. Subscription Plan Changeable Products API request parameters

  • Subscription Plan Changeable Products 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

    "ChangeableProducts" JSON True List of changeable products
    "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 "xxxx.yy" format
    "CurrencyID" String Currency code

    "SubscriptionInfo" JSON False Subscription product information
    "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 the product

    Table 15. Subscription Plan Changeable Products API response parameters

Pre-check Subscription Plan Changes

The Subscription Plan Change Pre-check API ("subscription/plan-change/pre-check") allows you to preview the impact of switching 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 has the following request headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 16. Subscription Plan Change Pre-check API request headers

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

  • Subscription Plan Change Pre-check API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "SubscriptionID" Subscription ID
    "AfterProductID" Product ID of the new product
    "Timestamp" Timestamp
    Format: "yyyy-MM-dd HH:mm:ss".
    The time is in UTC time and must be within 10 minutes from the current time.

    "CheckValue" Security check value
    Required parameters: "AppID" + "SubscriptionID" + "AfterProductID" + "Timestamp"

    Table 17. Subscription Plan Change Pre-check API request parameters

  • 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" Name of the current subscription product
    "CurrentBenefit" JSON False Information about the current benefit
    Mandatory if a benefit is active.

    "Type" String True Benefit type:
    • FREE_TRIAL
    • COUPON

    "FreeTrialDays" Integer Number of free trial days for the product
    If a free trial is not active, the value is '0'.

    "CouponName" String False Name of the coupon applied to the product
    "EndDate" True End date of the free trial or coupon benefit
    Format: "yyyy-MM-dd"

    "AfterProductName" String True Name of the new product
    "AfterProductPrice" Price of the new product
    "AfterProductPriceTaxIncluded" Boolean Whether the new product price includes tax:
    • "true": Includes tax
    • "false": Does not include tax

    "AfterProductFirstPaymentDate" String Estimated date for the first payment on the new product
    Format: "yyyy-MM-dd"
    The date takes into account any free trial days for the new product and, except for subscription upgrades, any benefit period currently active.

    "ProductCurrencyCode" Currency code

    "DaysUntilFirstPaymentDate" Integer False Number of days the upgraded product can be used without additional payment
    Includes any free trial days for the upgraded product.
    If a free trial period is currently active, the value is '0' and no free trial benefits of the upgraded product are returned.
    Mandatory for subscription upgrades.

    Table 18. Subscription Plan Change Pre-check API response parameters

Reserve Subscription Plan Changes

You can use the Subscription Plan Change Reserve API ("subscription/plan-change/reserve") to request changing the customer's subscription plan.

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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 19. Subscription Plan Change Reserve API request headers

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

  • Subscription Plan Change Reserve API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "SubscriptionID" Subscription ID
    "AfterProductID" Product ID of the new product
    "Timestamp" Timestamp
    Format: "yyyy-MM-dd HH:mm:ss".
    The time is in UTC time and must be within 10 minutes from the current time.

    "CheckValue" Security check value
    Required parameters: "AppID" + "SubscriptionID" + "AfterProductID" + "Timestamp"

    "MailLang" False ISO 639-1 language code in lowercase for the language of messages sent to the user
    For unsupported languages, use "en". The default value is "en".

    Table 20. Subscription Plan Change Reserve API request parameters

  • 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" Name of the current subscription product
    "CurrentBenefit" JSON False Information about the current benefit
    Mandatory if a benefit is active.

    "Type" String True Benefit type:
    • FREE_TRIAL
    • COUPON

    "FreeTrialDays" Integer Number of free trial days for the product
    If a free trial is not active, the value is '0'.

    "CouponName" String False Name of the coupon applied to the product
    "EndDate" True End date of the free trial or coupon benefit
    Format: "yyyy-MM-dd"

    "AfterProductName" String True Name of the new product
    "AfterProductPrice" Price of the new product
    "AfterProductPriceTaxIncluded" Boolean Whether the new product price includes tax:
    • "true": Includes tax
    • "false": Does not include tax

    "AfterProductFirstPaymentDate" String Estimated date for the first payment on the new product
    Format: "yyyy-MM-dd"
    The date takes into account any free trial days for the new product and, except for subscription upgrades, the benefit period currently active.

    "ProductCurrencyCode" Currency code

    "DaysUntilFirstPaymentDate" Integer False Number of days the upgraded product can be used without additional payment
    Includes any free trial days for the upgraded product.
    If a free trial period is currently active, the value is '0' and no free trial benefits of the upgraded product are returned.
    Mandatory for subscription upgrades.

    Table 21. Subscription Plan Change Reserve API response parameters

Retrieve Subscription Plan Change Reservation Status

The Subscription Plan Change Reservation Status API ("subscription/plan-change/reserve-status") retrieves the status of any requested subscription changes for a list of subscriptions or customers.

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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 22. Subscription Plan Reservation Status API request headers

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

  • Subscription Plan Change Reservation Status API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "SubscriptionIDList" String[] False List of subscription IDs
    At least one of 'SubscriptionIDList' or 'CustomIDList' must be provided.

    "CustomIDList" List of unique customer IDs
    At least one of 'SubscriptionIDList' or 'CustomIDList' must be provided.

    "Timestamp" String True Timestamp
    Format: "yyyy-MM-dd HH:mm:ss".
    The time is in UTC time and must be within 10 minutes from the current time.

    "CheckValue" Security check value
    Required parameters: "AppID" + "SubscriptionIDList[0]" + … + "SubscriptionIDList[N]" + "CustomIDList[0]" + … + "CustomIDList[N]" + "Timestamp"

    Table 23. Subscription Plan Reservation Status API request parameters

  • Subscription Plan Change 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 List of subscriptions with pending changes
    "Subscription ID" String True Subscription ID
    "CustomID" Unique customer ID
    "AfterProductID" Product ID of the new product
    "AfterProductName" Name of the new product
    "ApplyDate" Estimated date when the new product is applied
    Format: "yyyy-MM-dd"

    Table 24. Subscription Plan Reservation Status API response parameters

Cancel Subscription Plan Change Reservations

The Subscription Plan Change Cancel API ("subscription/plan-change/cancel") cancels a requested subscription product change.

To call the Subscription Plan Change Cancel 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 25. Subscription Plan Change Cancel API request headers

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

  • Subscription Plan Change Cancel API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "SubscriptionID" Subscription ID
    "Timestamp" Timestamp
    Format: "yyyy-MM-dd HH:mm:ss".
    The time is in UTC time and must be within 10 minutes from the current time.

    "CheckValue" Security check value
    Required parameters: "AppID" + "SubscriptionID" + "Timestamp"

    "MailLang" False ISO 639-1 language code in lowercase for the language of messages sent to the user
    For unsupported languages, use "en". The default value is "en".

    Table 26. Subscription Plan Change Cancel API request parameters

  • 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 27. Subscription Plan Change Cancel 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 has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"
  • "application/x-www-form-urlencoded"
For the "x-www-form-urlencoded" data type, the request body must not contain any spaces (' ').

"Accept" Media type accepted by the client:
  • "application/json;charset=UTF-8"

Table 28. Subscription Cancel API request headers

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

  • Subscription Cancel API request parameters:

    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 29. Subscription Cancel API request parameters

  • 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 30. Subscription Cancel API response parameters

Checking Billing Service Availability

The Billing Service Available Country Check API ("/country/checkavailability") retrieves Billing service availability information for the specified country codes.

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 country codes to be checked. You can check multiple codes.

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

The Billing Service Available Country Check API request has the following headers:

Header Mandatory Description
"Content-Type" True Media type of the message:
  • "application/json;charset=UTF-8"

"Accept" Media type accepted by the client:
  • "application/json"

Table 31. Billing Service Available Country Check API request headers

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

  • Billing Service Available Country Check API request parameters:

    Parameter Type Mandatory Description
    "AppID" String True Application ID
    "CountryCodes" Country codes in uppercase for the regions to be checked
    You can check multiple regions with a comma-separated list, for example, "DE,US,KR".

    "CheckValue" Security check value
    Required parameters: "AppID" + "CountryCodes"
    For multiple country codes, remove the commas. For example, if "CountryCodes" is "DE,US,KR", use "DEUSKR" to generate the check value.

    Table 32. Billing Service Available Country Check API request parameters

  • 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 Country information
    "CountryCode" String True Country code

    "IsBillingSupported" Boolean Billing service support status:
    • "true": Billing service supported
    • "false": Billing service not supported

    Table 33. Billing Service Available Country Check API response parameters

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 34. 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 data type to string
detailObj.OrderCurrencyID = productsList.ItemDetails[selectedItem].CurrencyID;
//detailObj.OrderID = "YOUR_ORDER_ID"; // This value is optional
var UniqueCustomId = "123"; // Unique ID for this user. "123" is an example value. It can be an 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 the Samsung Apps TV 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.
    For dynamic products, use this value as "productId" for the Verify Dynamic Product Information API.

    "OrderTitle" 100 Purchase item title
    "ItemTitle" issued by the Products List API.
    For dynamic products, use a customized value.

    "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.
    For dynamic products, use a customized value and use it as "productPrice" for the Verify Dynamic Product Information API.

    "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
    (For dynamic products only)

    100 Unique ID for the dynamic product from a third-party application
    Use this value as "dynmcProductId" for the Verify Dynamic Product Information API.

    "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 35. 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".
    A value is only returned when "payResult" is "SUCCESS".

    Table 36. buyItem() response parameters

Verifying Dynamic Product Information

The Verify Dynamic Product Information API ("cp/verify") is only available when the product type is dynamic product. The API checks the dynamic product information between DPI server and CP CMS. The DPI server calls this API when "Verification" is selected in the DPI Portal.

  • API URL

    Operating Zone (PRD): The "Verify URI" entered in the DPI Portal for the 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 Dynamic Product Information API request parameters:

    Parameter Type Mandatory Maximum length
    (characters)

    Description
    "countryCode" String True 10 Country code in uppercase

    "orderTime" 20 Order time (UTC-0)
    (20140314175900)

    "checkValue" 200 Security check value
    Required parameters: "AppID" + "dynmcProductID" + "productId" + "productPrice" + "productCurrencyCode"

    "productDetail" JSON - Product details
    "appId" String True 30 Application ID
    Same value as the "AppID" parameter for the buyItem() method.

    "productId" Purchase item ID
    Same value as the "OrderItemID" parameter for the buyItem() method.

    "productPrice" 10 Purchase price (Unit price)
    Same value as the "OrderTotal" parameter for the buyItem() method.

    "productCurrencyCode" Currency code
    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 Unique ID or string to track the product from the third-party application
    Same value as the "DynmcProductID" parameter for the buyItem() method.

    "dynmcProductInfo" False Dynamic product information
    Same value as the "DynmcProductInfo" parameter for the buyItem() method.

    "dynmcShareCategory" 20 Share category for the dynamic product
    Same value as the "DynmcShareCategory" parameter for the buyItem() method.

    "dynmcTaxCategory" 30 Tax category for the dynamic product
    Same value as the "DynmcTaxCategory" parameter for the buyItem() method.

    Table 37. Verify Dynamic Product Information API request parameters

  • Verify Dynamic Product Information API response parameters:

    Parameter Type Mandatory Length Description
    "status" String True 9 Result code:
    • "100000": Success
    • "ErrorCode": Failure
    For error code details, see the embedded Error Code file.

    "result" 100 Result message to be displayed
    • "Success" or other short error message

    "resultLongMesg" False 200 Detailed error message when debug mode is active

    Table 38. Verify Dynamic Product Information 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 39. DPI result codes and messages

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

Country and Currency Codes

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

Country Name Country Code
(ISO3166-1 alpha-2)

Currency Currency Code
(ISO 4217)

Aland Islands AX Euro EUR
Albania AL United States dollar USD
Algeria DZ Algerian dinar DZD
Argentina AR Argentinian peso ARS
Australia AU Australian dollar AUD
Austria AT Euro EUR
Bahrain BH Bahraini dinar BHD
Belarus BY Belarusian ruble BYN
Belgium BE Euro EUR
Bolivia BO United States dollar USD
Bosnia and Herzegovina BA United States dollar USD
Brazil BR Brazilian real BRL
Bulgaria BG Bulgarian lev BGN
Canada CA Canadian dollar CAD
Chile CL Chilean peso CLP
Colombia CO Colombian peso COP
Costa Rica CR United States dollar USD
Croatia HR Euro EUR
Czechia CZ Czech koruna CZK
Denmark DK Danish krone DKK
Dominican Republic DO United States dollar USD
Ecuador EC United States dollar USD
Egypt EG Egyptian pound EGP
Estonia EE Euro EUR
Faroe Islands FO Danish krone DKK
Finland FI Euro EUR
France FR Euro EUR
Germany DE Euro EUR
Greece GR Euro EUR
Greenland GL Danish krone DKK
Guatemala GT Guatemalan quetzal GTQ
Guernsey GG British pound GBP
Hong Kong HK Hong Kong dollar HKD
Hungary HU Hungarian forint HUF
Iceland IS United States dollar USD
India IN Indian rupee INR
Indonesia ID Indonesian rupiah IDR
Iraq IQ Iraqi dinar IQD
Ireland IE Euro EUR
Isle of Man IM British pound GBP
Israel IL Israeli shekel ILS
Italy IT Euro EUR
Jersey JE British pound GBP
Jordan JO Jordanian dinar JOD
Kazakhstan KZ Kazakhstani tenge KZT
Korea, Republic of KR South Korean won KRW
Kuwait KW Kuwaiti dinar KWD
Kyrgyzstan KG United States dollar USD
Latvia LV Euro EUR
Lebanon LB Lebanese pound LBP
Libya LY Libya dinar LYD
Lithuania LT Euro EUR
Luxembourg LU Euro EUR
Malaysia MY Malaysian ringgit MYR
Mexico MX Mexican peso MXN
Moldova 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 EUR
New Zealand NZ New Zealand dollar NZD
North Macedonia MK United States dollar USD
Norway NO Norwegian krone NOK
Oman OM Omani rial OMR
Pakistan PK United States dollar USD
Panama PA United States dollar USD
Peru PE Peruvian sol PEN
Philippines PH Philippine peso PHP
Poland PL Polish zloty PLN
Portugal PT Euro EUR
Qatar QA Qatari riyal QAR
Romania RO Euro EUR
Russian Federation RU Russian ruble RUB
Saudi Arabia SA Saudi rial SAR
Serbia RS Serbian dinar RSD
Singapore SG Singapore dollar SGD
Slovakia SK Euro EUR
Slovenia SI Euro EUR
South Africa ZA South African rand ZAR
Spain ES Euro EUR
Sweden SE Swedish krona SEK
Switzerland CH Swiss franc CHF
Taiwan TW New Taiwan dollar TWD
Tajikistan TJ United States dollar USD
Thailand TH Thai baht THB
Tunisia TN Tunisian dinar TND
Türkiye TR Turkish lira TRY
Turkmenistan TM United States dollar USD
Ukraine UA Ukrainian hryvna UAH
United Arab Emirates AE United Arab Emirates dirham AED
United Kingdom GB British pound GBP
United States US United States dollar USD
Uzbekistan UZ United States dollar USD
Venezuela VE United States dollar USD
Vietnam VN Vietnamese dong VND
Yemen YE Yemeni rial YER

Table 40. Country and currency codes