Samsung Checkout DPI Portal

.

Overview

The Samsung Checkout DPI (Digital Product Inventory) Portal is a web service portal designed for the Samsung Smart TV partners, which Samsung helps them sell products and items through Smart TV Apps. From the DPI, partners can register and manage products for sale and access the transaction history logs and sales reports for the applications they own.

DPI Main Services

  • Product management (Standard in-app products, Subscriptions, Paid apps)
  • Order management (purchase history for each user)
  • Sales reports and financial reports
  • Coupon management (creation and issuance)

DPI Service Environment

The Samsung Checkout DPI provides 3 types of environments as followings.

  • Operating Zone (Live / Production Environment)

    • Web Portal: https://dpi.samsungcheckout.com/
    • For the TVs that are made in use of the development board separately provided by Samsung Electronics, DPI Operating Zone environment cannot be used.
    Note

    The payment made in Operating Zone causes a charge on the part of partner when refund is made while being categorized as a real payment. Thus, beware not to use for the sake of test purpose.

  • Staging Zone (Test / Developing Environment)

    • Web Portal: https://sbox-dpi.samsungcheckout.com/
    • The Verification System is a development environment that is separately provided to ease the Billing Linkage Development.
    • An environment that has minimized the exceptional cases of each country when the real payment is made.
    • TV purchased on/off-line (Operating TV) and TV that uses the board provided by Samsung Electronics (Development TV) can all use the DPI Staging environment. The Billing Linkage Development can be done after setting the environment that is in comfort with development.
  • Dummy Payment (Developing Environment)
    • Web Portal: https://sbox-dpi.samsungcheckout.com/
    • For the convenience of partner SW development, we provide function called ‘Dummy Payment’ in only Staging Zone
    • Please note that Dummy Payment is provided only for development, so before submit app to Samsung,
      use Staging Zone(DEV) / Operating Zone(PRD) environment depending on the TV environment instead of Dummy Payment(FAKE).
    • Please refer to Samsung Checkout development guide for more details.
Note

Since the Data on the Operating Zone and the Data in Staging Zone cannot be shared, product type and price on both the Staging Zone and the Operating Zone should correspond when App is put into QA for game release.

Important

When submitting App after completing development integrated with Billing, the submission should be done after setting Staging Zone or Operating Zone to be seen in accordance with TV environment. Refer to the below Example.

Service Initiation Process

An account for the Samsung Apps TV Seller Office is required to use the DPI service. Once registered, partners can use the DPI service by following these steps:

App Registration at the Seller Office

Once a new app is registered, Seller Office will issue an AppID. This AppID is a key value linking the Seller Office and DPI systems for the partner.

For more details, please refer to Application Registration.

Note

When registering the App in the Seller Office, the option of “Use Samsung Billing (found at the 2nd stage at the App registration stage)” should be checked so as to link the DPI and Seller.

Request for Service Approval in DPI

Once an AppID is generated, the partners will be able to see the new app from the “My Apps” Details tab from DPI.

Review Service Approval Request

Please contact the account manager if the permission isn’t granted within 24 hours.

Figure 2.1 Service Approval Request

Figure 2.1 Service Approval Request

Issuance of Security Key

Once app approval is completed in the DPI service, an application security key is issued to safely use the service. The issued key can be viewed under "App Setting".

The key is a security key to use API calls, and this is a protection mechanism for invalid access from/to the app and DPI. The related process is described in the section CheckValue.

Figure 2.2 Security Key Issuance

Figure 2.2 Security Key Issuance

Important

The issued security key is a key to be used for Open API calls made by a Smart TV app. Please be careful not to reveal this key to others.

Sales Products Registration Process

Sales Country

Figure 2.3 Sales Country Registration

Figure 2.3 Sales Country Registration

You can check sales country on “App Setting” menu on the App. When expanding the countries available for service, you should additionally register the country.

The list of countries that are additionally registered by seller is synchronized at UTC – 5 ~ 6 o’ clock every day. (During these hours, access to the site is not available.) In order to equally apply the products to the countries that are newly added, you should process the following procedure on DPI: “Product List” > Click on the products > Enter the information of the country newly added > Save > Press “Confirm” button.

The synchronization on the list of countries to include the countries newly added by the seller can be done not only during the time when the daily automatic synchronization occurs, but also by accessing the “App Setting” menu on the App.

Figure 2.4 Confirmation on the Detailed Information of Product

Figure 2.4 Confirmation on the Detailed Information of Product

Product

For product registration, both individual registration and batch registration are supported. After product registration, the registered product goes into “Inactive” status and can be changed to “Active” status after a confirmation process.

Individual Product

Products can be registered under “Add a New Product” menu.

Figure 2.5 Individual Product Registration

Figure 2.5 Individual Product Registration

The following table explains the details of input fields.

Index Input Field Description
1 Product ID Must be a unique ID within the app.
2 Sales country - List of countries registered on the Seller’s site would be shown. (Refer to [Registration of Sales Country](#sales-products-registration-process)) - Able to select countries on the list for the sales of product
3 Product Name The product name can be entered for each country of sales. If left blank, the product name of the representative country will be applied
4 Product Type Types consist of Consumable, Non-Consumable, Limited Period, Subscription, Free trial + Subscription and Paid App and Dynamic Product.
![Subscription][6]
![Free trial][7]
![Dynamic Product][8]
5 Display Setting Whether to display a product or not can be chosen. Show/Hide settings can be modified on DPI portal. Only the products which are set to be on display will appear on the API of calling on the product list.
6 Expiration Products which have not yet consumed Expiry Date are only displayed on the API of calling on the product list. This is used on the event items which are sold only for a certain period of time.
7 Sales - Enter the price for each country for sales. Prices cannot go beyond the range of maximum price and minimum price, and if a price that is beyond such range, the price will be automatically changed to the maximum price, minimum price. Exchange rate is automatically applied based on the value entered for the representative country. - In case of ‘dynamic product’, only the range (minimum and maximum) is required by country. The information should match the real price range that your products have.

The following table explains the details of "Product Type".

Product Type Description
Consumable Consumers can purchase this type of product anytime. Purchase history can be retrieved for 90 days.
Non-Consumable Consumers can purchase this type of product only once. Purchase history can be retrieved with no time restriction.
Limited Period Once this type of product is purchased, repurchase cannot be made during the time when the product effect set by CP lasts. Purchase history can be retrieved for 90 days. If “Limited Period” product type is chosen, the duration of time for the product effect to last can be entered in the units above minute. The duration time for the product effect to last is allowed for the maximum of 90 days.

Subscription DPI system processes automatic payment on a certain designated cycle.

Free Trial + Subscription Convert to subscription after free trial for 30days. If "Free Trial + Subscription" type of product is chosen, Free Trial days and device number can be entered.
Ex) Free Trial : 30 days / allow 1 time(s) per device : Provide one(1) time per device from the registration date for 30 days for free.

Paid App For paid apps, when you register your app on DPI system you need to select it as paid app.
Dynamic Product In case that pater and Samsung agree on that products and prices will be managed by CMS of partner not Samsung’s DPI, partner should select “Dynamic Product” as a product type. Even though all the information of actual products are on CMS, partner need to register a representative item on DPI once so that our system can display information on Samsung Smart TV App/Game store which is legally required and verify which server we need to call for certain products : CMS or DPI.

If Dynamic Product is chosen,
  • Partner does not register each products on DPI that partner sells in their app actually
  • Partner builds and operates its own CMS to manage products information including prices and to verify purchase requests
  • Additional requirements
    • Verification/No Verification:
      ‘Verification’ is a recommended option otherwise partner has to handle the verification process by themselves and take all the responsibility for all the error cases related to verification process.
      If ‘Verification’ is selected, ‘Verify URI’ is also required. This URI should serve the function of checking product information such as product itself, price and currency

    • Price Setting
      Price range information of products that you actually sells in your app is required by country. It is not used for actual payment for providing the app information on Samsung Smart TV App/Game store which is legally required.
      Thus, it has to be updated when the price range of your products is changed.

Multiple Products

More than one item can be registered at the same time under the "Add Multiple Products" menu. Download the provided CSV template, and enter the details according to the registration form and register the products.

The template which is provided for registration of multiple products is using the same template as the downloaded products list from "Product List" menu. This function can be used to match the products information between Staging Zone and Operating Zone as following way.

Note

  • When register multiple products, products can be registered up to 100 at once.
  • This function is not supported for the type "Dynamic Product".

1. After the products information setting at Staging Zone, develop and test at Staging Zone.

2. Download a verified products list at Staging Zone.

Go to the Portal of Staging Zone (https://sbox-dpi.samsungcloudsolution.com), select "Product List" menu and check the checkbox of products that you want, and click "Download" button.

3. Upload downloaded products list to the Operating Zone.

Go to the Portal of Operating Zone (https://dpi.samsungcheckout.com/), select "Add Multiple Products" and upload the CSV template which is downloaded at the above 2nd step.

At "Product List" menu, check the information of uploaded products, and click the "Confirm Pending Changes" button if all information is correct.

Figure 2.6 Product List > Download products list

Figure 2.6 Product List > Download products list


Figure 2.7 Add Multiple Products

Figure 2.7 Add Multiple Products

The following table explains the details of input fields.

Input Field Description
Product Name
(Representative product name)		 The name of the product used in the representative country must be entered in the Country:Product Name field. This field cannot be left empty.
Product ID Alphanumeric and two special characters ('-', '_') are allowed. (Maximum 20 bytes)
Product Description Describe the product.
Type Following product types are allowed;
Consumable, Non-Consumable, Limited Period, Paid App, Subscription, Free Trial + Subscription
Period If the product type is ‘Limited Period’, a number fewer than 129,600 in minutes is allowed. (Maximum 90 days)
Frequency If the product type is "Subscription" or "Free Trial + Subscription", "Every Week" or "Every Month" are allowed.
Cycles If the product type is "Subscription" or "Free Trial + Subscription", "Until Cancelled" or Number (Range : 2 <= Cycles <= 30) are allowed.
Free Trial Days If the product type is "Free Trial + Subscription", a number in Days is allowed.
DUID Limit Count If the product type is "Free Trial + Subscription", a number is allowed.
Visibility A field indicating whether the product can be shown. "Show" or "Hide" is allowed.
Country:Product Name The country and product name are separated by ':' and a maximum of 50 bytes of product name is allowed. If more than one country is entered, use '|' as a separator. Country codes are based on ISO 3166-1 alpha-2 and unsupported countries are automatically deleted if entered.
Country:Product Price The country and price information are separated by ':', and if more than one country is input, the use of the '|' separator is required. Selling prices are limited to minimum/maximum price ranges supported by the system (reference price for each currency). If a price goes beyond the range, it is automatically reverted to the specified maximum or minimum price. Country codes are based on ISO 3166-1 alpha-2 and unsupported countries are automatically deleted if entered. Price quantity fields for countries registered in sales settings must be entered.

Confirm Changes

This is a step to confirm the products before putting them directly on sale or making changes. If product is registered, modified or deleted, it is not directly set as available for sale and changes are registered in the Pending tab. If the seller checks the list of registered items and confirms its products, the corresponding products are set as available for sale.

In case of "Dynamic Product", the setting of each product has to managed by CMS not DPI. DPI has only a representative product ID so if you make any changes on the product ID here, it will applies every products referring this representative ID

It is possible to check details in “Product List” menu.

Figure 2.8 Sales Confirmation

Figure 2.8 Sales Confirmation

Product Status Flow and Lifecycle

The following diagram explains product lifecycle.

Figure 2.9 Product Status Flow Chart

Figure 2.9 Product Status Flow Chart

Please refer to the details of each status at the following table.

Table 2-9 Product Status Description
Product Status Description Visibility Setting Visible to Users
Inactive Initial status before saving Show No
Inactive Initial status before saving Hide No
Pending (1) After saving a new item Show No
Pending (1) After saving a new item Hide No
Active After accepting the changes Show Yes
Active After accepting the changes Hide No
Pending (2) After making modifications to an active item Show Yes
(Active is shown)
Pending (2) After making modifications to an active item Hide No
Retired Deleted from the list for an item that has been sold at least once N/A No
Deleted Deleted from the list for an item that has never been sold (Removed from the DPI entirely) N/A No

Sales Product Management

Sales Retire

In order to suspend the sales of a particular product, when "Retire" button on the "Product List" > "Product Details" page is pressed, the relevant product is set to be in the Retire status, and the purchase of the product is disenabled since then.

For already made purchases on the product, refund should be considered depending on the policy of partner, and the refund on the purchases should be made by "Transaction List (All Apps)" menu. Return on the products finished with refund should be done in reference to Chapter 1.3.5.

  • "Retire" function is provided on "Product List" > "Product Details" page.
    Figure 2.10 Product Retire

    Figure 2.10 Product Retire

  • "Delete" function is provided on "Product List" menu.
    The products with no purchase history can be done with "Delete" not "Retire", and the products deleted cannot be purchased and cannot be viewed on the "Product List" page.
    Figure 2.11 Product Delete

    Figure 2.11 Product Delete

Refund

To get refund on the purchase history for tests or to request for a refund, partner can directly give refund for each of transaction on "Sales Management" > "Transaction List (All Apps)" page.

Note

If the product type is 'Dynamic Product', please note the each field means as the following.
The DPI only maintains the transaction history along with settlement related information. CMS of partner has to produce content-level sales report if needed.

Figure 2.12 Transactions Refund

Figure 2.12 Transactions Refund

Table 2.12 Transactions List of "Dynamic Product"
Field Description
Product ID Representive ID to identify product type on DPI, not actual product ID on your CMS
Product Name Product Name that has been sold of each transaction

Figure 2.12(a) Transactions Refund : Dynamic Product

Figure 2.12(a) Transactions Refund : Dynamic Product

Check on the Refunds on the App and Retrieval

When calling Request Purchases List API after running the application, purchase history with CancelStatus Parameter on the Response being “true” are deemed to be refunded, and CP should retrieve the product by itself. However, the products with subscription can be checked in a different way, and please refer to the following chapter for details.

Check on the Refunds on the App and Retrieval – Products with Subscription

For the case of the products with subscription, cancellation and refund have different meaning.

  • Cancellation
    Cancellation means payment being disabled from the next Cycle. This means the previous purchase history including the current payment Cycle not being refunded. Thus, the user will be in a status of payment up to the current Cycle.
    If the user wants to use the service again, then the user should purchase a subscription product again.
  • Refund
    Refund can be made for the payments made for each Cycle. Refund and Cancellation are separate. If only Refund is being made, payment for the next following Cycle will continue.
    If a user requests for refund, the request should be distinguished whether the user wants the refund only for the current Cycle, or the user wants no payment for the upcoming Cycle as well.
    If the user wants no payment for the upcoming Cycle, the refund and cancellation should be done as stated below:

    1. Select product ID on subscription on "Manage Subscriptions" menu.
    2. Select the ID registered on subscription (Invoice ID) that requested for refund.
    3. Process both the Cancellation on the overall Cycle and Refund side by side.

The following page shows Refund, Cancellation, End date change.

Figure 2.13 Manage Subscription Transactions

Figure 2.13 Manage Subscription Transactions

  • Click on the "Refund" button and process Refund.
  • Click on the "Cancellation" button and process cancellation on the overall subscription Cycle.
  • Click on the "Change End Date" button and change the subscription end date.
Important

Changing the subscription end date to a date earlier than the date of today is not possible.

Note

In order to check whether the cancellation is being made or not, App code should be configured to identify whether the subscription service period has been expired or not by checking SubsStatus Parameter and SubsEndTime Parameter of the Response when Request Purchases List API was called after running the App.

References

Period of Providing Product Purchase Information

The DPI provides information on the status for the products purchased by users through Request Purchases List API.

In case the purchased product is not applied on the real game, the status can be checked on the “Product Applied Status”. In case the purchased product was refunded to the user, the status can be checked on the “Sales Cancellation Status”.

The period of time the above status information is provided through API to the application can be classified by the product type as shown below.

Table 3.1 Product Purchase Period
Product Type Applied Purchases
(Purchase History)		 Not Applied Purchases Refund/
Cancellation
Consumable (Ex: Potion, Coin) Application Date + 90days All products can be viewed with no restrictions in time period Refund Date+ 90 days
Non-Consumable(Ex: All Stage Lock Released) All products with payment completion can be viewed irrespective of condition All products can be viewed with no restrictions in time period Refund Date+ 90 days
Limited Period(Ex: Two times more of the experience during 24 hours) (Application date + Product Period) + 90days All products can be viewed with no restrictions in time period Refund Date+ 90 days
Subscription (Ex: Provides item pack during monthly $10 subscription) Subscription expiry date (SubsEndTime) + 90days Subscription expiry date (SubsEndTime) + 90 days Subscription expiry date (SubsEndTime) + 90 days
Free Trial + Subscription (Ex: Convert to subscription after free trial for 30days) Subscription expiry date (SubsEndTime) + 90 days Subscription expiry date (SubsEndTime) + 90 days Subscription expiry date (SubsEndTime) + 90 days
Note

Partner can check all product purchase history on the DPI Portal with no restrictions in time period.

Glossaries

Table 3.2 Glossary Table
Term Description
Billing /
Payment Service		 A service created in order to help monetary transactions between service providers and users.
Partner /
App Developer		 Be in charge of creating products suitable for consumers of the Smart TV.
Paid App A service or app that can be only downloaded after making a payment.
In-App Purchase A method to pay for additional products and features within both free apps and paid apps.
PayPal (PayPal) The global payments company headquartered in the United States that provide the payment service via pre-registered payment method.
Digital Product Inventory (DPI) A system provided to developers to enter and manage extra products and items in their own apps. It is directly connected to the App Store.
Samsung Checkout
(Billing Client)		 A payment UI module for consumers to add their choice of payment methods and pay for premium apps or special items.
Operating Zone/ Staging Zone Operating Zone is a live environment where the real users get access to Verification system is a test environment where 3rd party development and QA are conducted. (Sandbox Zone is regarded as Staging Zone.)
Operating TV / Development TV - Operating TV: TV purchased from on/off-line, TV with the same setting environment as the one in general users.
- Development TV: TV that is made in use of a board separately provided by Samsung Electronics, TV that allows a setting environment for development different from the one for general users.
CMS (Content Management System) Product catalogue management server or system including price information. In this document, this word refers to the server for the type “dynamic product” that has all the information of products and handles verification with its own product catalogue. For reference, product information of other product types should be managed in DPI not 3rd party CMS.
DPI will be looking at CMS to pull necessary product information as needed. CMS will be the source of truth regarding content metadata, purchase history (which user bought which title at which resolution of PURCHASE/RENTAL, etc.) whereas DPI will be the source of truth of transactional data (i.e. transaction amount, tax amount). Both systems will be linked by "invoice ID" that is generated by DPI and passed over to CMS for every successful transaction.