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.
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.
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.
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.
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.
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
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.
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.
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 |
|
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.
|
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 |
|
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,
|
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.
- When register multiple products, products can be registered up to 100 at once.
- This function is not supported for the type "Dynamic Product".
-
After the products information setting at Staging Zone, develop and test at Staging Zone.
-
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. -
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.
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.
Product Status Flow and Lifecycle
The following diagram explains product lifecycle.
Please refer to the details of each status at the following table.
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 |
Table 2-9 Product Status Description
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.
-
"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.
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.
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.
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 |
Table 2.12 Transactions List of "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:- Select product ID on subscription on "Manage Subscriptions" menu.
- Select the ID registered on subscription (Invoice ID) that requested for refund.
- Process both the Cancellation on the overall Cycle and Refund side by side.
The following page shows Refund, Cancellation, End date change.
- 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.
Changing the subscription end date to a date earlier than the date of today is not possible.
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.
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 |
Table 3.1 Product Purchase Period
Partner can check all product purchase history on the DPI Portal with no restrictions in time period.
Glossaries
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 |
|
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. |
Table 3.2 Glossary Table