Filter
-
Content Type
-
Category
Mobile/Wearable
Visual Display
Digital Appliance
Platform
Recommendations
Filter
tutorials
blogintroduction the samsung iap subscription server apis empower developers to efficiently manage samsung in-app purchase (iap) subscriptions, including cancellation, refund, revocation, and status check. these apis serve as the foundation for implementing subscription management features within your application management server. integrating the samsung iap server apis with your backend server simplifies subscription management. this integration allows you to cancel subscriptions and prevent further billing for users, revoke access to subscription-based content, process refunds based on user requests, and check subscription status to determine validity and current state. a well-structured backend implementation streamlines subscription management, ensuring customers receive reliable service and minimizing potential issues related to billing, access, and refunds. prerequisites to establish server-to-server communication between the samsung iap service and your server, follow these essential steps. develop a subscription application – ensure your application supports subscription operations. upload binary for beta testing – submit your application for testing in seller portal. create subscriptions – set up subscription products in seller portal for user subscriptions. completing these steps ensures a seamless integration of samsung iap into your application. for detailed guidance, visit register an app and in-app items in seller portal. implementation of the samsung subscription apis the samsung iap subscription server apis are used to manage subscription-related operations, including cancellations, revocations, refunds, and status checks. to leverage these apis effectively, setting up a backend server is essential. this secure server-to-server communication facilitates efficient handling of all subscription-related operations between the samsung iap service and your server. api overview the samsung iap subscription server api provides endpoints for efficiently managing subscription-based operations. it allows developers to cancel, revoke, refund, and check the status of subscriptions. this api also facilitates robust operations and efficient management of user subscriptions, all while ensuring security and authentication through the use of appropriate headers. base endpoint the samsung iap subscription server apis need a secure endpoint for managing subscriptions. https://devapi.samsungapps.com/iap/seller/v6/applications/<packagename>/purchases/subscriptions/<purchaseid> more detailed information is available through the support documentation. headers to ensure secure communication with the samsung iap service, the following headers must be included in every request. content-type – defines the format of the request body. for json content, use application/json. authorization – uses an access token for authentication. the format should be (bearer <access_token>). refer to the create an access token page for details on generating an access token. service account id – obtained from seller portal under assistance > api service. this id is required to generate a json web token (jwt). for more detailed information, visit the create a service account section in seller portal. these headers collectively ensure secure and authenticated api requests, enabling seamless integration with the samsung iap service. supported methods the samsung iap subscription server api enables efficient subscription management. developers can cancel, revoke, or refund subscriptions using patch requests, and check subscription status using get requests. configuring the server you can develop a spring boot server for this purpose. here are the guidelines for setting it up. create a spring boot project - for detailed steps, refer to developing your first spring boot application. set up the server endpoint: create a controller for samsung iap subscription apis within your ide after importing the spring boot project. this controller manages all in-app subscription activities. the controller performs patch and get requests with the samsung iap service, ensuring communication with your server. performing a patch request the patch request is used to cancel, refund, or revoke a subscription. follow these steps to proceed. creating a request body to cancel, refund, or revoke a subscription, a specific request body must be created for each operation. when interacting with samsung iap service, you send a well-structured api request tailored to the specific action you wish to execute. below are the request formats for various subscription operations. // cancel a subscription requestbody body = requestbody.create( mediatype.parse("application/json"), "{\"action\" : \"cancel\"}" ); // revoke a subscription requestbody body = requestbody.create( mediatype.parse("application/json"), "{\"action\" : \"revoke\"}" ); // refund a subscription requestbody body = requestbody.create( mediatype.parse("application/json"), "{\"action\" : \"refund\"}" ); building the patch request (cancel, revoke or refund subscription) the patch method in rest apis is used for partial updates of resources, enabling you to send only the specific fields that need modification rather than the entire resource. the patch request needs a request body to specify the intended action. to execute a subscription management request, you must construct a secure http request that includes all necessary headers and authentication details. request request = new request.builder() .url(api_url) .patch(body) .addheader("content-type", "application/json") .addheader("authorization", "bearer " + access_token) .addheader("service-account-id", service_account_id) .build(); executing the patch request once the patch request is prepared, execute it using the okhttpclient, ensuring proper request handling and response processing. @crossorigin(origins = "*") @requestmapping(value = "/cancel", method = requestmethod.patch ) public void patchrequest(){ // set request body as json with required action. // initialize patch request, set body, add headers, and finalize setup. client.newcall(request).enqueue(new callback() { @override public void onfailure(call call, ioexception e) { // handle exception } @override public void onresponse(call call, response response) throws ioexception { // handle response response.close(); } }); } example response this response indicates that the request was processed successfully and without errors. { "code" : "0000", "message" : "success" } performing a get request the get request is used to retrieve the status of a subscription. follow these steps to proceed. building the get request the get method is primarily used to retrieve or read data from a server. to check the status of a subscription, the get method is required to retrieve detailed item information. this type of request does not require a request body; only the necessary headers for authentication are needed. request request = new request.builder() .url(api_url) .addheader("content-type", "application/json") .addheader("authorization", "bearer " + access_token) .addheader("service-account-id", service_account_id) .build(); executing the get request once the get request is prepared, execute it using the okhttpclient to retrieve and efficiently process the response data. @getmapping("/get") public void getrequest(){ // initialize get request, add headers, and finalize setup. client.newcall(request).enqueue(new callback() { @override public void onfailure(call call, ioexception e) { // handle exception } @override public void onresponse(call call, response response) throws ioexception { // handle response } }); } example response if the get request executes successfully, it returns the status of the subscription as a response. { "subscriptionpurchasedate": "2025-04-28 04:54:06 utc", "subscriptionenddate": "2025-04-28 05:54:06 utc", "subscriptionstatus": "cancel", "subscriptionfirstpurchaseid": "55541a3d363c9dee6194614024ee2177c72a9dec51fe8dba5b44503f57dc9aec", "countrycode": "usa", "price": { "localcurrencycode": "usd", "localprice": 15, "supplyprice": 15 }, ... } deploying and testing the server for the server to perform api calls, it can use a publicly accessible url. you can deploy the project to obtain the url. for testing purposes, you might deploy it on a platform like codesandbox, which provides a publicly accessible url similar to https://abcde-8080.csb.app/iap/xxxx. conclusion by properly integrating the samsung iap subscription server apis, developers can ensure seamless handling of subscription-related actions within their applications. the implementation of secure server-to-server communication guarantees efficient subscription management and significantly enhances the overall user experience. references download sample server source code samsung iap subscription documentation integrate the samsung in-app purchase orders api with your application
Md. Hossain
tutorials
blogsamsung in-app purchase (iap) offers developers a robust solution for handling digital transactions within mobile applications available on galaxy store. whether it is selling digital goods, handling subscriptions, or managing refunds, samsung iap is designed to offer a smooth, secure experience. the samsung iap orders api expands the scope of these benefits. you can fetch all the payments and refunds history according to specified dates on your server to easily manage your application. this content guides you through the essential components for implementing both the samsung iap and samsung iap orders apis. figure 1: sample application ui in this tutorial, we provide a sample android application called book spot, which offers users the option to subscribe to their favorite books and consumable items, such as text fonts, for purchase. this user application is provided to help you to integrate samsung iap sdk with your applicaiton. finally, we also provide a sample server application to view all the payment and refund history on specific dates by calling the samsung iap orders api from the back-end server. prerequisites before implementing the samsung iap order api on your server, you need to perform iap functionalities to retrieve purchase history. you need to integrate samsung iap with your application. if you don't have an app yet, follow these steps to ensure a smooth and effective process. step 1: implement samsung iap in your app to integrate the iap system into your application, follow this general flow. integrate the samsung iap sdk into your application. initiate item purchase by calling startpayment() with the necessary parameters, such as the item id and a listener to handle the results. after the transaction, verify whether the purchase is successful with iap/v6/receipt. this involves checking if the purchase id is valid. follow the ensuring secure purchases using the samsung iap server api for more details. once the purchase is confirmed, allow the item to be consumed using consumepurchaseitems(). this step ensures that the item can be repurchased if needed. for more information about the iap sdk integration, you can follow the integration of samsung iap services in android apps article. also get help from the sample android application. step 2: upload your application upload the application for beta testing on galaxy store. a step-by-step guide with screenshots has been provided in the documentation. for more details, see the section “production closed beta test” in the test guide. step 3: purchase items finally, create products in seller portal so that users can purchase or subscribe to them while using the application. for more details about the available items that seller portal supports, see the programming guide. implementation of the samsung iap orders api the samsung iap orders api is used to view all payments and refunds on a specific date. it does this by fetching the payments and refunds history within the date you specified. let’s implement the samsung iap orders api and create a server to listen to its response. through server-to-server communication, the api returns all order data for the application. overview of the orders api to view all payments and refunds: you must make a post request to the samsung iap orders api endpoint with the required headers specified below. if you specify a date, all the payment history within this date is returned. otherwise, it only returns all the data from the day before the current date. api endpoint: https://devapi.samsungapps.com/iap/seller/orders method: post headers: add the following fields to the request header. for more information, see the create an access token page, which will help you understand how to create the access token in detail. the token is used for authorization. you can also get the service account id by clicking the assistance > api service tabs on seller portal. for more details, read the section create a service account and visit seller portal. header name description required/optional values content-type format of the request body required application/json authorization authorization security header required bearer: access_token service account id this id can be created in seller portal and is used to generate the json web token (jwt) required service-account-id parameters: the following parameters can be used to build your post request. name type required/optional description sellerseq string required your seller deeplink, which is found in your profile in seller portal and consists of a 12-digit number. packagename string optional used to view payment and refund data. you can provide the application package name. when a package name is not specified, the data for all applications is shown. requestdate string optional specify a date from which to view the payment and refund data. if the date is not specified, the data from a day before your current date is returned. continuationtoken string optional use this if you want to check if there is a continuation for the data on the next page. if there is no more data, the response is null. configuring the server you can develop a spring boot server for this purpose. here are the guidelines on how to set up this server. set up a spring boot project. for more information, follow the steps in developing your first spring boot application. set up your server endpoint. create a controller for the samsung iap orders api in an integrated development environment (ide) after importing the spring boot project you created. this helps managing all in-app order-related activities and processing them within your application. the controller receives post requests sent from samsung’s iap orders service ensuring the communication with your application. to ensure smooth communication with the samsung iap orders api, it's essential to structure your server requests effectively. below is a clear and concise breakdown of the process. 1. setup dependencies to implement rest api support, add the following okhttp library dependencies to your application's build.gradle file. implementation 'com.squareup.okhttp3:okhttp: version' implementation 'com.google.code.gson:gson: version' 2. define parameters encapsulate request parameters for cleaner handling. public class orderrequest { private final string sellerseq; public orderrequest(string sellerseq) { this.sellerseq = sellerseq; } public string tojson() { return string.format("{\"sellerseq\":\"%s\"}", sellerseq); } } 3. build the http request centralize request configuration for maintainability. public class orderservice { private static final string api_url = "https://devapi.samsungapps.com/iap/seller/orders"; private static final string token = "0djt9yzryukdogbvulxxxxxx"; private static final string service_account_id = "85412253-21b2-4d84-8ff5-xxxxxxxxxxxx"; private final okhttpclient client = new okhttpclient(); public void sendorderrequest(string sellerseq) { orderrequest orderrequest = new orderrequest(sellerseq); requestbody body = requestbody.create(orderrequest.tojson(), mediatype.parse("application/json; charset=utf-8")); request request = new request.builder() .url(api_url) .post(body) .addheader("authorization", "bearer " + token) .addheader("service-account-id", service_account_id) .addheader("content-type", "application/json") .build(); executerequest(request); } } 4. handle response ensure robust error handling for api calls. private void executerequest(request request) { client.newcall(request).enqueue(new callback() { @override public void onfailure(@notnull call call, @notnull ioexception e) { system.err.println("request failed: " + e.getmessage()); } @override public void onresponse(@notnull call call, @notnull response response) throws ioexception { try (responsebody responsebody = response.body()) { if (!response.issuccessful()) { system.err.printf("unexpected response [%d]: %s%n", response.code(), responsebody.string()); return; } system.out.println("response: " + responsebody.string()); } } }); } congratulations! you have just built the spring boot server to handle api post requests using the okhttpclient to manage http requests and responses for your sample application. example api response as previously mentioned, a json-formatted response is returned to your request. for detailed descriptions of each response body element, see the “response” section of the samsung iap orders api documentation. the following output format is a sample in which only some of the response-body data is presented. the continuationtoken parameter key returns null because there is no continuation for the data on the next page. the orderitemlist parameter key lists all the orders with specific details, such as orderid, countryid, packagename, among others. { "continuationtoken": null, "orderitemlist": [ { "orderid": "s20230210kr019xxxxx", "purchaseid": "a778b928b32ed0871958e8bcfb757e54f0bc894fa8df7dd8dbb553cxxxxxxxx", "contentid": "000005059xxx", "countryid": "usa", "packagename": "com.abc.xyz" }, { "orderid": "s20230210kr019xxxxx", "purchaseid": "90a5df78f7815623eb34f567eb0413fb0209bb04dad1367d7877edxxxxxxxx", "contentid": "000005059xxx", "countryid": "usa", "packagename": "com.abc.xyz" }, ] } usually, the responses contain all the relevant information about user purchases, such as the in-app product title, price, and payment status. therefore, you can use the information and create views for an easier order management. noteif the iap operating mode is configured to test mode, the api response is empty. this is because the api is configured to operate and return a response only in production mode. conclusion you have learned how to implement product purchase, consumption, and registration, as well as how to integrate the samsung iap orders api and configure a server to fetch all the payment and refund history within specific dates. integrating the samsung iap orders api functionality into your server is an essential step in managing your application payments history to ensure a seamless experience to users. now, you can implement the samsung iap orders api into your application to track all payments, refunds and make your business more manageable. related resources for additional information on this topic, see the resources below: android sample application source code sample server application source code add samsung in-app purchase service to your app samsung iap orders api integration of samsung iap services in android apps
Md. Hossain
tutorials
blogin-app purchases are crucial for many applications, and the samsung in-app purchase (iap) service helps developers manage purchases, subscriptions, and refunds efficiently. to keep your server in sync with user transactions, samsung iap instant server notification (isn) sends real-time notifications to your backend server when purchase-related events occur. isn for samsung iap is a method used by samsung's system to notify your server about user activities related to in-app items and subscriptions. when a change occurs, samsung sends a notification to your server. a list of all events that trigger a notification is available here. in this article, we will build a spring boot server that handles these notifications. prerequisites to implement isn for samsung iap, it is important to focus on the requirements that helps you to most easily implement the process: create an iap public key in the seller portal. this key is used to authenticate the notifications you receive and verify that they are from the samsung iap isn system. the steps you need to follow are outlined in the create an iap public key in seller portal documentation. create an in-app item in the seller portal. follow the related documentation to create an in-app item. isn structure the isn for samsung iap service sends a notification to the application developer server. the structure of the notification is always a base64-encoded json web token (jwt) and consists of three parts. the three parts are: header payload signature header the jwt uses a jose (javascript object signing and encryption) header. similar to the envelope of a letter, the header indicates the type of notification being sent. for additional information, refer to the samsung iap isn header article. example encoded header: eyj0exaioijkv1qilcjhbgcioijsxxxxxxxx example decoded header: { "alg" : "rs256", "typ" : "jwt" } payload the payload is the actual content of the message, like the letter inside the envelope. this part contains the crucial information you need, like the user’s subscription details, the product they have subscribed to, and the current status of the subscription. more details about the payload check are available in the following documentation and data claims section. example encoded payload: eyjpc3mioijpyxauc2ftc3vuz2fwchmuy29tiiwic3viijoirvzftlrftkfnrsisimf1zci6wyjjb20ucgfja2fnzs5uyw1lil0sim5izii6mtcxnziwncwiawf0ijoxnze3mja0lcjkyxrhijp7innlbgxlck5hbwuiom51bgwsim nvbnrlbnroyw1lijoitwfydgluzsj9lcj2zxjzaw9uijoxxxxxxxx example decoded payload: { "iss": "iap.samsungapps.com", "sub": "event_name", "aud": ["com.package.name"], "nbf": 1717xxxxxx, "iat": 1717xxxxxx, "data": {..}, "version": "x.0" } signature the signature is the security feature that acts as a digital stamp to prove the message is genuine and hasn’t been tampered with. you can use this signature to verify that the data in the payload is authentic and was created by samsung. further information is provided in the signature documentation. now that we know the structure of the isn for samsung iap, we can configure the server to handle it. server configuration according to the isn for samsung iap requirements, you must set up a server to receive the notifications. below, we create a spring boot server. use your preferred ide (integrated development environment) or online spring initializr to create a spring boot server. follow the steps below to set up your own server. step 1: set up a spring boot project use the spring initializr tool to create a new project. choose the following dependency: spring web generate and download the project. step 2: import the project into ide open the project in the ide (intellij, eclipse, etc.) step 3: set up isn endpoint create a controller for isn notifications in the ide after importing the spring boot project. the controller receives post requests (subscription, refund and cancel) sent from samsung’s iap server. add necessary dependencies in the build.gradle file: { implementation 'com.auth0:java-jwt:4.0.0' //for jwt verifier implementation 'org.json:json:20230227' // for json parsing } load the public key detailed in the prerequisite section: private string loadpublickey(string filename) throws ioexception { classpathresource resource = new classpathresource(filename); stringbuilder contentbuilder = new stringbuilder(); try (inputstream inputstream = resource.getinputstream(); bufferedreader reader = new bufferedreader(new inputstreamreader(inputstream))) { string line; while ((line = reader.readline()) != null) { contentbuilder.append(line).append("\n"); } } return contentbuilder.tostring(); } remove headers, footers, and whitespace from the public key and convert it to the rsapublickey format. private rsapublickey getrsapublickeyfrompem(string pem) throws exception { string publickeypem = pem .replace("-----begin public key-----", "") .replace("-----end public key-----", "") .replaceall("\\s", ""); // remove headers, footers, and whitespace byte[] encoded = base64.getdecoder().decode(publickeypem); keyfactory keyfactory = keyfactory.getinstance("rsa"); x509encodedkeyspec keyspec = new x509encodedkeyspec(encoded); return (rsapublickey) keyfactory.generatepublic(keyspec); } create a jwt verifier with rsapublickey and, finally, verify the jwt. if the verification is successful, decode the jwt to retrieve the decoded json payload. the decoded payload contains the message of the notification. private void verifytoken(string token, rsapublickey publickey) { try { // create jwt verifier with rsa public key algorithm algorithm = algorithm.rsa256(publickey, null); // verify the jwt token jwtverifier verifier = jwt.require(algorithm) .withissuer("iap.samsungapps.com") .build(); decodedjwt jwt = verifier.verify(token); // decode the jwt token string payloadjson = new string(base64.getdecoder().decode(jwt.getpayload())); jsonobject jsonobject = new jsonobject(payloadjson); //print decoded json payload system.out.println("payload as json: " + jsonobject.tostring(4)); } catch (jwtverificationexception e) { system.out.println("invalid token: " + e.getmessage()); } } in this sample project, we have only printed the payload data to the console. you can use this according to your requirements. step 4: deploy the server the server needs a publicly accessible url to receive isn notifications. in our project, we have used codesandbox to get the publicly accessible url for the server. once you deploy the project on codesandbox, you will get a publicly accessible url that looks like this: https://abcde-8080.csb.app/iap/isn. testing with seller portal test your server with samsung galaxy store seller portal: set the codesandbox url as the isn url in seller portal. go to the in-app purchase section and create items with the required details. in the "isn url" field, set the publicly accessible server url. after setting the url, click the test button. a notification will be sent to the specified server immediately. you will also receive a notification on the server that you just deployed in the codesandbox. figure 1: testing with seller portal testing with a sample application now it is time to test the isn for samsung iap from the user application. further details are provided in the integrate the samsung in-app purchase orders api with your application article. download the sample application from this blog and then follow the instructions until you reach the "implementation of item subscription" section. in the sample application, after clicking the "buy" button, startpayment() is called. the onpayment() callback returns an indication of whether the purchase succeeds or fails. if the purchase is successful, the iap server sends a notification to your server. iaphelper.startpayment(itemid, string.valueof(1), new onpaymentlistener() { @override public void onpayment(@nonnull errorvo errorvo, @nullable purchasevo purchasevo) { if (purchasevo != null) { log.d("purchaseid" , purchasevo.getpurchaseid().tostring()); // purchase successfull }else { log.d("purchaseerror" , errorvo.tostring()); } } }); example response after successfully purchasing an item, a json response is returned. for more information on each parameter, you can check the item purchased documentation. example json response: "data" : { "itemid": "example_item_id", "orderid": "xxxx40601kra00xxxxx", "purchaseid": "xxxxx7245d57cc1ba072b81d06e6f86cd49d3da63854538eea689273787xxxxx", "testpayyn": "n", "betatestyn": "n", "passthroughparam": null } notefor different event types, it sends different data claims. for more detailed information regarding data claims, see data claims. conclusion by implementing the isn for samsung iap with your server, you can easily and securely stay in sync with user in-app purchases. integrating isn for samsung iap helps you improve your application management experience and grow your application’s revenue. following this guide will help you smoothly set up the system and provide a better way to manage your application. references for additional information on this topic, see the resources below: download the sample spring boot server samsung iap instant server notification documentation integrate the samsung in-app purchase orders api with your application
Md. Hossain
Develop Samsung IAP
docverify a purchase iap/v6/receipt enables your server and client app to verify that a specified in-app product purchase and payment transaction was successfully completed the api returns a json object with a successful status and details about a successful transaction and the product or with a failure status this api can help to prevent malicious purchases and ensure that purchase and payment transactions were successful when the client app experiences network interruptions after a product purchase and payment transaction request get https //iap samsungapps com/iap/v6/receipt?purchaseid={purchaseid value} query parameters parameter type description purchaseid string required unique identifier of the in-app product purchase transactionnote the purchase id is assigned by samsung iap your app receives it in the purchasevo object of the onpaymentlistener interface your app must send the id to your server independently of samsung iap example get http //iap samsungapps com/iap/v6/receipt?purchaseid=7efef23271b0a48746a9d7c391e367c7a802980d391d7f9b75010e8138c66c36 response noteresponse parameters may be added, changed, and deleted parameters parameter type description itemid string unique identifier of the in-app product registered in seller portal paymentid string unique identifier assigned to the in-app product payment transaction when it was successful orderid string unique identifier assigned to the purchase receipt packagename string package name of the app with a completed transaction itemname string title of the in-app product registered in seller portal itemdesc string brief explanation of the in-app product registered in seller portal purchasedate string date and time of the product purchase and payment transaction yyyy-mm-dd hh mm ss gmt paymentamount string total amount, including the in-app product price and all applicable taxes, billed to the user status string processing result of the request for the receipt "success" success"fail" failed"cancel" the purchase transaction was cancelednote for canceled transactions, the old iap/getpurchasereceipt only passed "fail", but the iap/v6/receipt passes "cancel" and transaction information together paymentmethod string type of payment option used to purchase the product"credit card", "mobile micro purchase", "prepaid card", "psms", "carrier billing" and others mode string iap operating mode in effect at the time of purchase "test" developer test mode which always returns success or fail result"production" production mode consumeyn string for consumable items only, whether or not the item has been reported as consumed and is available for purchase again "y" consumed"n" not consumed comsumedate string date and time when the consumable item was reported as consumed yyyy-mm-dd hh mm ss gmt consumedevicemodel string model name of the device that reported the item as consumed acknowledgeyn string whether or not acknowledge that the user has been granted entitlement for the purchased non-consumable item or subscription "y" acknowledged"n" not acknowledged acknowledgedate string date and time when the purchase of non-consumable item or subscription was acknowledged yyyy-mm-dd hh mm ss gmt acknowledgedevicemodel string model name of the device that acknowledged non-consumable item or subscription passthroughparam string deprecated since iap 6 4 0transaction id created by your app for securityreturned only if the pass-through parameter was set note the old iap/getpurchasereceipt passed the base64 encoded value, but the iap/v6/receipt passes the value as it is set in the game currencycode string currency code 3 characters of the purchaser's local currency for example, eur, gbp, usd currencyunit string symbol of the purchaser's local currency for example, €, £, or $ canceldate string for canceled transaction only, date and time the purchase transaction was canceled yyyy-mm-dd hh mm ss gmt note added since iap/v6/receipt errorcode integer for failed request only, error code errormessage string for failed request only, detailed error message example success { "itemid" "57515", "paymentid" "20191129013006730832tran", "orderid" "s20191129kra1908197", "packagename" "com samsung android test", "itemname" "test pack", "itemdesc" "iap test item best value!", "purchasedate" "2019-11-29 01 32 41", "paymentamount" "100 000", "status" "success", "paymentmethod" "credit card", "mode" "production", "consumeyn" "y", "consumedate" "2019-11-29 01 33 28", "consumedevicemodel" "sm-n960n", "acknowledgeyn" "y", "acknowledgedate" "2025-03-20 06 58 06", "acknowledgedevicemodel" "sm-n960n", "passthroughparam" "test_pass_through", "currencycode" "krw", "currencyunit" "￦" } fail errorcode errormessage 1 "fail" 1000 detailed message about an unexpected system error for example, "parsing error" 9135 "not exist order" 9153 "wrong param invalid purchaseid " { "status" "fail", "errorcode" 9135, "errormessage" "not exist order" } canceled purchase transaction { "itemid" "57515", "paymentid" "zpmtid20191128kra1908196", "orderid" "s20191128kra1908196", "itemname" "test pack", "itemdesc" "iap test item best value!", "purchasedate" "2019-11-28 10 18 09", "paymentamount" "0 000", "paymentmethod" "free", "mode" "production", "consumeyn" "y", "consumedate" "2019-11-28 10 18 11", "consumedevicemodel" "sm-g965f", "acknowledgeyn" "y", "acknowledgedate" "2025-03-20 06 58 06", "acknowledgedevicemodel" "sm-n960n", "passthroughparam" "test_pass_through", "currencycode" "krw", "currencyunit" "￦", "status" "cancel", "canceldate" "2019-11-29 00 01 52" } additional samsung iap server apis additional samsung iap server-to-server apis are provided as part of the galaxy store developer api and have different requirements purchase acknowledgment - consume or acknowledge a purchased product check status of subscription - get the subscription status, including subscription information and purchase information the following samsung iap server soap apis have been deprecated and are no longer supported create a service token soap check subscription status soap
Develop Smart TV
apibilling api to use samsung product api, <script type="text/javascript" src="$webapis/webapis/webapis js"></script> should be loaded in index html this module defines the billing samsung checkout functionalities provided by the tizen samsung product api since 2 4 product tv privilege level public privilege http //developer samsung com/privilege/billing summary of interfaces and methods interface method billingmanagerobject billingmanager void buyitem domstring appid, tvservertype servertype, domstring paymentdetails, billingbuydatasuccesscallback onsuccess, optional errorcallback? onerror ;void getproductslist domstring appid, domstring countrycode, domstring pagesize, domstring pagenumber, domstring checkvalue, tvservertype servertype, billingproductslistcallback onsuccess, optional errorcallback? onerror ;void applyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingapplyinvoicecallback onsuccess, optional errorcallback? onerror ;void verifyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingverifyinvoicecallback onsuccess, optional errorcallback? onerror ;void getservicecountryavailability domstring appid, domstring[] countrycodes, domstring checkvalue, tvservertype servertype, billinggetservicecountryavailabilitycallback onsuccess, optional errorcallback? onerror ;void getuserpurchaselist domstring appid, domstring customid, domstring countrycode, domstring pagenumber, domstring checkvalue, tvservertype servertype, billinggetuserpurchaselistcallback onsuccess, optional errorcallback? onerror ;void cancelsubscription domstring appid, domstring invoiceid, domstring customid, domstring countrycode, tvservertype servertype, billingcancelsubscriptioncallback onsuccess, optional errorcallback? onerror ;void isserviceavailable tvservertype servertype, billingisserviceavailablecallback onsuccess, optional errorcallback? onerror ;domstring getversion ; billingbuydatasuccesscallback void onsuccess billingbuydata data ; billingbuydata billingproductslistcallback void onsuccess productslistdata data ; billingapplyinvoicecallback void onsuccess applyinvoicedata data ; billingverifyinvoicecallback void onsuccess verifyinvoicedata data ; billinggetuserpurchaselistcallback void onsuccess userpurchasedata data ; billinggetservicecountryavailabilitycallback void onsuccess servicecountryavailabilitydata data ; billingcancelsubscriptioncallback void onsuccess cancelsubscriptiondata data ; billingisserviceavailablecallback void onsuccess serviceavailabledata data ; 1 type definitions 1 1 tvservertype specifies billing server types enum tvservertype { "dev", "prd" }; the following values are supported dev staging server prd operating server 1 2 historytype specifies product types for the purchase history enum historytype { "all", "subscription", "non-subscription" }; the following values are supported all all product types this type is not supported since 2019 product subscription subscription products only non-subscription non-subscription products only 1 3 productslistdata defines a dictionary for product list data returned by the getproductslist api dictionary productslistdata { domstring apiresult; }; the following values are supported apiresult getproductslist api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in productslistapiresult format at the below 1 4 productslistapiresult defines a dictionary for the productslistdata dictionary apiresult parameter dictionary productslistapiresult { domstring cpstatus; domstring? cpresult; long totalcount; domstring checkvalue; itemdetails[]? itemdetails; }; the following values are supported cpstatus dpi result code returns "100000" on success and other codes on failure cpresult [optional] optional additional message "eof" last page of the product list "hasnext true" product list has further pages other error message, depending on the dpi result code totalcount total number of invoices checkvalue security check value itemdetails [optional] optional dictionary in json format 1 5 itemdetails defines a dictionary for the productslistapiresult dictionary 'itemdetails' parameter dictionary itemdetails { long seq; domstring itemid; domstring itemtitle; long itemtype; long? period; long price; domstring currencyid; productsubscriptioninfo? subscriptioninfo; }; the following values are supported seq sequence number 1 ~ totalcount itemid product id itemtitle product name itemtype product type "1" consumable "2" non-consumable "3" limited-period "4" subscription period [optional] limited period product duration, in minutes price product price, in "xxxx yy" format currencyid currency code subscriptioninfo [optional] subscription information mandatory for subscription products 1 6 productsubscriptioninfo defines a dictionary for the itemdetails dictionary 'subscriptioninfo' parameter dictionary productsubscriptioninfo { domstring paymentcycleperiod; long paymentcyclefrq; long paymentcycle; }; the following values are supported paymentcycleperiod subscription payment period "d" days "w" weeks "m" months paymentcyclefrq payment cycle frequency paymentcycle number of payment cycles 1 7 applyinvoicedata defines a dictionary for data returned by the applyinvoice api dictionary applyinvoicedata { domstring apiresult; }; the following values are supported apiresult applyinvoice api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in applyinvoiceapiresult format at the below 1 8 applyinvoiceapiresult defines a dictionary for the applyinvoicedata dictionary 'apiresult' parameter dictionary applyinvoiceapiresult { domstring cpstatus; domstring? cpresult; domstring appliedtime; }; the following values are supported cpstatus dpi result code returns "100000" on success and other codes on failure cpresult [optional] optional additional message "success" other error message, depending on the dpi result code appliedtime time product applied, in 14-digit utc time 1 9 verifyinvoicedata defines a dictionary for data returned by the verifyinvoice api dictionary verifyinvoicedata { domstring apiresult; }; the following values are supported apiresult verifyinvoice api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in verifyinvoiceapiresult format at the below 1 10 verifyinvoiceapiresult defines a dictionary for the verifyinvoicedata dictionary 'apiresult' parameter dictionary verifyinvoiceapiresult { domstring cpstatus; domstring? cpresult; domstring appid; domstring invoiceid; }; the following values are supported cpstatus dpi result code returns "100000" on success and other codes on failure cpresult [optional] optional additional message "success" other error message, depending on the dpi result code appid application id invoiceid invoice id that you want to verify whether a purchase was successful 1 11 userpurchasedata defines a dictionary for data returned by the getuserpurchaselist api dictionary userpurchasedata { domstring apiresult; }; the following values are supported apiresult getuserpurchaselist api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in getuserpurchaselistapiresult format at the below 1 12 getuserpurchaselistapiresult defines a dictionary for the userpurchasedata dictionary 'apiresult' parameter dictionary getuserpurchaselistapiresult { domstring cpstatus; domstring? cpresult; long totalcount; domstring checkvalue; invoicedetails[]? invoicedetails; }; the following values are supported cpstatus it returns "100000" in success, [errorcode] in failure refer to dpi error code cpresult [optional] optional additional message "eof" last page of the product list "hasnext true" product list has further pages other error message, depending on the dpi result code totalcount total number of invoices checkvalue security check value invoicedetails [optional] optional dictionary in json format 1 13 invoicedetails defines a dictionary for the getuserpurchaselistapiresult dictionary 'invoicedetails' parameter dictionary invoicedetails { long seq; domstring invoiceid; domstring itemid; domstring itemtitle; long itemtype; domstring ordertime; long? period; long price; domstring ordercurrencyid; boolean cancelstatus; boolean appliedstatus; domstring? appliedtime; domstring? limitendtime; domstring? remaintime; purchasesubscriptioninfo? subscriptioninfo; }; the following values are supported seq sequence number 1 ~ totalcount invoiceid invoice id of this purchase history itemid product id itemtitle product name itemtype product type "1" consumable "2" non-consumable "3" limited-period "4" subscription ordertime payment time, in 14-digit utc time period [optional] limited period product duration, in minutes price product price, in "xxxx yy" format ordercurrencyid currency code cancelstatus cancellation status "true" sale canceled "false" sale ongoing appliedstatus product application status "true" applied "false" not applied appliedtime [optional] time product applied, in 14-digit utc time limitendtime [optional] limited period product end time, in 14-digit utc time remaintime [optional] limited period product time remaining, in seconds subscriptioninfo [optional] subscription information mandatory for subscription products 1 14 purchasesubscriptioninfo defines a dictionary for the invoicedetails dictionary 'subscriptioninfo' parameter dictionary purchasesubscriptioninfo { domstring subscriptionid; domstring subsstarttime; domstring subsendtime; domstring subsstatus; }; the following values are supported subscriptionid id of subscription history subsstarttime subscription start time, in 14-digit utc time subsendtime subscription expiry time, in 14-digit utc time subsstatus subscription status "00" active "01" subscription expired "02" canceled by buyer "03" canceled for payment failure "04" canceled by cp "05" canceled by admin 1 15 servicecountryavailabilitydata defines a dictionary for data returned by the getservicecountryavailability api dictionary servicecountryavailabilitydata { domstring apiresult; }; the following values are supported apiresult getservicecountryavailability api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in getuserpurchaselistapiresult format at the below 1 16 getservicecountryavailabilityapiresult defines a dictionary for the servicecountryavailabilitydata dictionary 'apiresult' parameter dictionary getservicecountryavailabilityapiresult { domstring cpstatus; domstring? cpresult; countries[]? countryavailability; }; the following values are supported cpstatus it returns "100000" in success, [errorcode] in failure refer to dpi error code cpresult [optional] returns "success" on success countryavailability [optional] list of countries with information of service availability 1 17 countries defines a dictionary for the getservicecountryavailabilityapiresult dictionary 'countryavailability' parameter dictionary countries { domstring countrycode; boolean isbillingsupported; }; the following values are supported countrycode countrycode to check service availability isbillingsupported status "true" service is available "false" service is not available 1 18 cancelsubscriptiondata defines a dictionary for subscription cancellation data returned by the cancelsubscription api dictionary cancelsubscriptiondata { domstring apiresult; }; the following values are supported apiresult cancelsubscription api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in cancelsubscriptionapiresult format at the below 1 19 cancelsubscriptionapiresult defines a dictionary for the cancelsubscriptiondata dictionary apiresult parameter dictionary cancelsubscriptionapiresult { domstring cpstatus; domstring? cpresult; domstring invoiceid; domstring? subscanceltime; domstring? subsstatus; }; the following values are supported cpstatus dpi result code returns "100000" on success and other codes on failure cpresult [optional] optional additional message "success" other error message, depending on the dpi result code invoiceid invoice id of subscription that you want to cancel subscanceltime [optional] optional time subscription canceled, in 14-digit utc time subsstatus [optional] optional subscription status "00" active "01" subscription expired "02" canceled by buyer "03" canceled for payment failure "04" canceled by cp "05" canceled by admin 1 20 showregisterpromotionalcodedata this defines data set that is coming from showregisterpromotionalcode api dictionary showregisterpromotionalcodedata { domstring opendeeplinkresult; domstring opendeeplinkdetail; }; the following values are supported opendeeplinkresult it returns "success" in success, "fail" in failure opendeeplinkdetail it returns the detail information of coupon or gift card it is a dictionary in json format, so you have to parse it to use for more information, please refer to "promotionalcodedetail" at the below 1 21 promotionalcodedetail this defines data set of promotionalcodedetail parameter that contains showregisterpromotionalcodedata dictionary dictionary promotionalcodedetail { domstring appliedcouponcount; domstring[] appliedcouponlist; domstring registedbenefitcount; domstring[] registedbenefitlist; }; the following values are supported appliedcouponcount it returns the number of applied coupon count appliedcouponlist it returns the list of applied coupon registedbenefitcount it returns the number of benefit registedbenefitlist it returns the list of benefit code 1 22 showregistercreditcarddata this defines data set that is coming from showregistercreditcard api dictionary showregistercreditcarddata { domstring opendeeplinkresult; domstring? opendeeplinkdetail; }; the following values are supported opendeeplinkresult it returns "success" in success, "fail" in failure opendeeplinkdetail [optional] it is optional and not used now 1 23 showpurchasehistorydata this defines data set that is coming from showpurchaseshistory api dictionary showpurchasehistorydata { domstring opendeeplinkresult; domstring opendeeplinkdetail; }; the following values are supported opendeeplinkresult it returns "success" in success, "fail" in failure opendeeplinkdetail it returns the detail information of refund or cancel it is a dictionary in json format, so you have to parse it to use for more information, please refer to "purchasehistorydetail" at the below 1 24 purchasehistorydetail this defines data set of purchasehistorydetail parameter that contains showpurchasehistorydata dictionary dictionary purchasehistorydetail { domstring invoicerefundcount; domstring[] invoicerefundlist; domstring subscriptioncancelcount; domstring[] subscriptioncancellist; }; the following values are supported invoicerefundcount it returns the number of product that user make refunded invoicerefundlist it returns array that contains the list of refunded invoice id subscriptioncancelcount it returns the number of subscription product that user make cancelled subscriptioncancellist it returns array that contains the list of cancelled subscription 1 25 serviceavailabledata defines a dictionary for data returned by the isserviceavailable api dictionary serviceavailabledata { domstring apiresult; }; the following values are supported apiresult isserviceavailable api result dictionary in json format this value is json string type data, so please use it by json parsing after you parse this value, you can use it in serviceavailableapiresult format at the below 1 26 serviceavailableapiresult defines a dictionary for the serviceavailabledata dictionary 'apiresult' parameter dictionary serviceavailableapiresult { domstring status; domstring result; domstring serviceyn; }; the following values are supported status returns "100000" on success and other codes on failure result returns "success" on success serviceyn returns "y" if the service is available 2 interfaces 2 1 billingmanagerobject defines a webapi object instance of the tizen samsung product api the webapis billing object enables access to billing api functionality [nointerfaceobject] interface billingmanagerobject { readonly attribute billingmanager billing; }; webapi implements billingmanagerobject; since 2 4 attributes readonly billingmanager billing billing api namespace 2 2 billingmanager provides methods for billing functionalities [nointerfaceobject] interface billingmanager { void buyitem domstring appid, tvservertype servertype, domstring paymentdetails, billingbuydatasuccesscallback onsuccess, optional errorcallback? onerror ; void getproductslist domstring appid, domstring countrycode, domstring pagesize, domstring pagenumber, domstring checkvalue, tvservertype servertype, billingproductslistcallback onsuccess, optional errorcallback? onerror ; void applyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingapplyinvoicecallback onsuccess, optional errorcallback? onerror ; void verifyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingverifyinvoicecallback onsuccess, optional errorcallback? onerror ; void getservicecountryavailability domstring appid, domstring[] countrycodes, domstring checkvalue, tvservertype servertype, billinggetservicecountryavailabilitycallback onsuccess, optional errorcallback? onerror ; void getuserpurchaselist domstring appid, domstring customid, domstring countrycode, domstring pagenumber, domstring checkvalue, tvservertype servertype, billinggetuserpurchaselistcallback onsuccess, optional errorcallback? onerror ; void cancelsubscription domstring appid, domstring invoiceid, domstring customid, domstring countrycode, tvservertype servertype, billingcancelsubscriptioncallback onsuccess, optional errorcallback? onerror ; void isserviceavailable tvservertype servertype, billingisserviceavailablecallback onsuccess, optional errorcallback? onerror ; domstring getversion ; }; methods buyitem enables implementing the samsung checkout client module within the application after authenticating the purchase information through the application, the user can proceed to purchase payment void buyitem domstring appid, tvservertype servertype, domstring paymentdetails, billingbuydatasuccesscallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id servertype billing server type paymentdetails payment parameters orderitemid[mandatory]/ordertitle[mandatory]/ordertotal[mandatory]/ordercurrencyid[mandatory]/orderid[optional]/ordercustomid[mandatory] onsuccess returns "payresult" and "paydetail" if there is no internal error occurs until client to server data communication payresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it paydetail, can have additional data when it's returned, such as invoiceid please refer to the development guide of "buyitem" for details onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if other error occur, such as internal error or "billing client already running" error exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 2 4 code example var strappid = ""; var struid = webapis sso getloginuid ; var paymentdetails = new object ; paymentdetails orderitemid="pid_2_consum_cupn"; paymentdetails ordertitle="hello consum us coupon"; paymentdetails ordertotal="2"; paymentdetails ordercurrencyid="usd"; paymentdetails ordercustomid=struid; var stringifyresult = json stringify paymentdetails ; var onsuccess = function data {}; var onerror = function error {}; webapis billing buyitem strappid, "dev", stringifyresult, onsuccess, onerror ; getproductslist retrieves the list of products registered on the billing dpi server void getproductslist domstring appid, domstring countrycode, domstring pagesize, domstring pagenumber, domstring checkvalue, tvservertype servertype, billingproductslistcallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id countrycode tv country code pagesize number of products retrieved per page maximum 100 pagenumber requested page number 1 ~ n checkvalue security check value required parameters = "appid" + "countrycode" the check value is used by the dpi service to verify api requests it is a base64 hash generated by applying the hmac sha256 algorithm on a concatenated string of parameters using the dpi security key you can see the example how to generate checkvalue from the following code example you can use any open library to generate the hmac sha256 hash the following example uses the cryptojs library servertype billing server type onsuccess returns the product list if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 4 0 code example var strsecuritykey = ""; // the dpi security key is issued at the dpi portal var strappid = ""; var strcountrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; var reqparams = strappid + strcountrycode; var hash = cryptojs hmacsha256 reqparams, strsecuritykey ; var strcheckvalue = cryptojs enc base64 stringify hash ; var onsuccess = function data {}; var onerror = function error {}; webapis billing getproductslist strappid, strcountrycode, "100", "1", strcheckvalue, "dev", onsuccess, onerror ; applyinvoice updates the apply status of purchase item to dpi server void applyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingapplyinvoicecallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id customid same value as "ordercustomid" parameter for the buyitem api samsung account uid invoiceid invoice id of purchased item that you want to update apply status countrycode tv country code servertype billing server type onsuccess returns purchase apply status if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 4 0 code example var strappid = ""; var struid = webapis sso getloginuid ; var invoiceid = ""; // issued by getproductslist var strcountrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; var onsuccess = function data {}; var onerror = function error {}; webapis billing applyinvoice strappid, struid, invoiceid, strcountrycode, "dev", onsuccess, onerror ; verifyinvoice checks whether a purchase, corresponding to a specific "invoiceid", was successful void verifyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingverifyinvoicecallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id customid same value as "ordercustomid" parameter for the buyitem api samsung account uid invoiceid invoice id that you want to verify whether a purchase was successful countrycode tv country code servertype billing server type onsuccess returns the payment status if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 4 0 code example var strappid = ""; var struid = webapis sso getloginuid ; var invoiceid = ""; // issued by getproductslist var strcountrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; var onsuccess = function data {}; var onerror = function error {}; webapis billing verifyinvoice strappid, struid, invoiceid, strcountrycode, "dev", onsuccess, onerror ; getservicecountryavailability get service country availability for samsung checkout void getservicecountryavailability domstring appid, domstring[] countrycodes, domstring checkvalue, tvservertype servertype, billinggetservicecountryavailabilitycallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id countrycodes to check multiple countrycodes available add as array, only uppercase allowed ex countrycodes=["de","us","kr"] checkvalue security check value required parameters = "appid" + "countrycodes" the check value is used by the dpi service to verify api requests it is a base64 hash generated by applying the hmac sha256 algorithm on a concatenated string of parameters using the dpi security key you can see the example how to generate checkvalue from the following code example you can use any open library to generate the hmac sha256 hash the following example uses the cryptojs library servertype billing server type onsuccess returns the service availability status of each country if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 5 5 code example var strsecuritykey = ""; // the dpi security key is issued at the dpi portal var strappid = ""; var countrycodes = ["de","us","kr"]; var reqparams = strappid + "deuskr"; var hash = cryptojs hmacsha256 reqparams, strsecuritykey ; var strcheckvalue = cryptojs enc base64 stringify hash ; var onsuccess = function data {}; var onerror = function error {}; webapis billing getservicecountryavailability strappid, countrycodes, strcheckvalue, "dev", onsuccess, onerror ; getuserpurchaselist retrieves the user's purchase list void getuserpurchaselist domstring appid, domstring customid, domstring countrycode, domstring pagenumber, domstring checkvalue, tvservertype servertype, billinggetuserpurchaselistcallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id customid same value as "ordercustomid" parameter for the buyitem api samsung account uid countrycode tv country code pagenumber requested page number 1 ~ n checkvalue security check value required parameters = "appid" + "customid" + "countrycode" + "itemtype" + "pagenumber" itemtype, must use 2 as value "all items" the check value is used by the dpi service to verify api requests it is a base64 hash generated by applying the hmac sha256 algorithm on a concatenated string of parameters using the dpi security key you can see the example how to generate checkvalue from the following code example you can use any open library to generate the hmac sha256 hash the following example uses the cryptojs library servertype billing server type onsuccess returns the purchase list if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 4 0 code example var strsecuritykey = ""; // the dpi security key is issued at the dpi portal var strappid = ""; var struid = webapis sso getloginuid ; var strcountrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; var strpagenumber = "1"; var reqparams = strappid + struid + strcountrycode + "2" + strpagenumber; var hash = cryptojs hmacsha256 reqparams, strsecuritykey ; var strcheckvalue = cryptojs enc base64 stringify hash ; var onsuccess = function data {}; var onerror = function error {}; webapis billing getuserpurchaselist strappid, struid, strcountrycode, strpagenumber, strcheckvalue, "dev", onsuccess, onerror ; cancelsubscription cancels a subscription product void cancelsubscription domstring appid, domstring invoiceid, domstring customid, domstring countrycode, tvservertype servertype, billingcancelsubscriptioncallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters appid application id invoiceid invoice id of subscription that you want to cancel customid same value as "ordercustomid" parameter for the buyitem api samsung account uid countrycode tv country code servertype billing server type onsuccess returns the subscription cancellation status if there is no internal error occurs until client to server data communication apiresult, can still contains error when billing server confirms that the given parameters does not have expected value or have problem while processing it when cpstatus value from apiresult is "100000", it means server communication is done properly and other values are valid in returns onerror [optional][nullable] optional callback method to invoke if an error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if servertype contains an invalid value since 4 0 code example var strappid = ""; var struid = webapis sso getloginuid ; var invoiceid = ""; // issued by getproductslist var strcountrycode = webapis productinfo getsystemconfig webapis productinfo productinfoconfigkey config_key_service_country ; var onsuccess = function data {}; var onerror = function error {}; webapis billing cancelsubscription strappid, invoiceid, struid , strcountrycode , "dev", onsuccess, onerror ; isserviceavailable checks whether the billing server is available however, this api will be replaced by getservicecountryavailability after deprecation void isserviceavailable tvservertype servertype, billingisserviceavailablecallback onsuccess, optional errorcallback? onerror ; product tv privilege level public privilege http //developer samsung com/privilege/billing parameters servertype billing server onsuccess returns the server availability onerror [optional][nullable] optional callback method to invoke if an internal error occurs before the client to server data communication securityerror, if the application does not have the privilege to call this method unknownerror, if any other error occurs exceptions webapiexception with error type typemismatcherror, if any of input parameter is not compatible with its expected type with error type invalidvalueserror, if any input parameter contains an invalid value since 4 0 deprecated 5 5 code example var onsuccess = function data {}; var onerror = function error {}; webapis billing isserviceavailable "dev", onsuccess, onerror getversion retrieves the billing api version domstring getversion ; product tv privilege level public privilege http //developer samsung com/privilege/billing return value domstring billing api version exceptions webapiexception with error type securityerror, if the application does not have the privilege to call this method with error type notsupportederror, if this feature is not supported with error type unknownerror, for any other error since 4 0 code example var version = webapis billing getversion ; 2 3 billingbuydatasuccesscallback defines the payment success callback [callback = functiononly, nointerfaceobject] interface billingbuydatasuccesscallback { void onsuccess billingbuydata data ; }; methods onsuccess callback method returning the payment status void onsuccess billingbuydata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data payment status code example void onsuccess data { if data payresult == 'success' { // implement success logic } else { // implement cancel or fail logic } } 2 4 billingbuydata defines the payment result and information [nointerfaceobject] interface billingbuydata { attribute domstring payresult; attribute domstring paydetail; }; attributes domstring payresult payment result domstring paydetail payment information it is same with paymentdetails param of buyitem 2 5 billingproductslistcallback defines the product list success callback [callback = functiononly, nointerfaceobject] interface billingproductslistcallback { void onsuccess productslistdata data ; }; methods onsuccess callback method returning the product list request status void onsuccess productslistdata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes getproductlist api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { var resproductslist = json parse data apiresult ; if resproductslist cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 6 billingapplyinvoicecallback defines the apply invoice success callback [callback = functiononly, nointerfaceobject] interface billingapplyinvoicecallback { void onsuccess applyinvoicedata data ; }; methods onsuccess callback method returning the apply invoice request status void onsuccess applyinvoicedata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes applyinvoice api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { resapplyproduct = json parse data apiresult ; if resapplyproduct cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 7 billingverifyinvoicecallback defines the payment verification success callback [callback = functiononly, nointerfaceobject] interface billingverifyinvoicecallback { void onsuccess verifyinvoicedata data ; }; methods onsuccess callback method returning the payment verification request status void onsuccess verifyinvoicedata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes verifyinvoice api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { resverifypurchase = json parse data apiresult ; if resverifypurchase cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 8 billinggetuserpurchaselistcallback defines the purchase history success callback [callback = functiononly, nointerfaceobject] interface billinggetuserpurchaselistcallback { void onsuccess userpurchasedata data ; }; methods onsuccess callback method returning the purchase history request status void onsuccess userpurchasedata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes getuserpurchaselist api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { respurchaseslist = json parse data apiresult ; if respurchaseslist cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 9 billinggetservicecountryavailabilitycallback defines the get service country availability callback [callback = functiononly, nointerfaceobject] interface billinggetservicecountryavailabilitycallback { void onsuccess servicecountryavailabilitydata data ; }; methods onsuccess callback method returning availability of country list status void onsuccess servicecountryavailabilitydata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes getservicecountryavailability api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { resservicecountryavailability = json parse data apiresult ; if resservicecountryavailability cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 10 billingcancelsubscriptioncallback defines the subscription cancel success callback [callback = functiononly, nointerfaceobject] interface billingcancelsubscriptioncallback { void onsuccess cancelsubscriptiondata data ; }; methods onsuccess callback method returning the subscription cancel request status void onsuccess cancelsubscriptiondata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes cancelsubscription api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { rescancelsubscription = json parse data apiresult ; if rescancelsubscription cpstatus == "100000" { // implement success logic } else { // implement cancel or fail logic } } 2 11 billingisserviceavailablecallback defines the service availability check success callback [callback = functiononly, nointerfaceobject] interface billingisserviceavailablecallback { void onsuccess serviceavailabledata data ; }; deprecated 5 5 methods onsuccess callback method returning the service availability check status void onsuccess serviceavailabledata data ; privilege level public privilege http //developer samsung com/privilege/billing parameters data it includes isserviceavailable api result but you can't use it as it is you have to parse it as json format data code example void onsuccess data { resjson = json parse data apiresult if resjson serviceyn == "y" { // implement success logic } else { // implement cancel or fail logic } } 3 full webidl module billing { enum tvservertype { "dev", "prd" }; enum historytype { "all", "subscription", "non-subscription" }; dictionary productslistdata { domstring apiresult; }; dictionary productslistapiresult { domstring cpstatus; domstring? cpresult; long totalcount; domstring checkvalue; itemdetails[]? itemdetails; }; dictionary itemdetails { long seq; domstring itemid; domstring itemtitle; long itemtype; long? period; long price; domstring currencyid; productsubscriptioninfo? subscriptioninfo; }; dictionary productsubscriptioninfo { domstring paymentcycleperiod; long paymentcyclefrq; long paymentcycle; }; dictionary applyinvoicedata { domstring apiresult; }; dictionary applyinvoiceapiresult { domstring cpstatus; domstring? cpresult; domstring appliedtime; }; dictionary verifyinvoicedata { domstring apiresult; }; dictionary verifyinvoiceapiresult { domstring cpstatus; domstring? cpresult; domstring appid; domstring invoiceid; }; dictionary userpurchasedata { domstring apiresult; }; dictionary getuserpurchaselistapiresult { domstring cpstatus; domstring? cpresult; long totalcount; domstring checkvalue; invoicedetails[]? invoicedetails; }; dictionary invoicedetails { long seq; domstring invoiceid; domstring itemid; domstring itemtitle; long itemtype; domstring ordertime; long? period; long price; domstring ordercurrencyid; boolean cancelstatus; boolean appliedstatus; domstring? appliedtime; domstring? limitendtime; domstring? remaintime; purchasesubscriptioninfo? subscriptioninfo; }; dictionary purchasesubscriptioninfo { domstring subscriptionid; domstring subsstarttime; domstring subsendtime; domstring subsstatus; }; dictionary servicecountryavailabilitydata { domstring apiresult; }; dictionary getservicecountryavailabilityapiresult { domstring cpstatus; domstring? cpresult; countries[]? countryavailability; }; dictionary countries { domstring countrycode; boolean isbillingsupported; }; dictionary cancelsubscriptiondata { domstring apiresult; }; dictionary cancelsubscriptionapiresult { domstring cpstatus; domstring? cpresult; domstring invoiceid; domstring? subscanceltime; domstring? subsstatus; }; dictionary showregisterpromotionalcodedata { domstring opendeeplinkresult; domstring opendeeplinkdetail; }; dictionary promotionalcodedetail { domstring appliedcouponcount; domstring[] appliedcouponlist; domstring registedbenefitcount; domstring[] registedbenefitlist; }; dictionary showregistercreditcarddata { domstring opendeeplinkresult; domstring? opendeeplinkdetail; }; dictionary showpurchasehistorydata { domstring opendeeplinkresult; domstring opendeeplinkdetail; }; dictionary purchasehistorydetail { domstring invoicerefundcount; domstring[] invoicerefundlist; domstring subscriptioncancelcount; domstring[] subscriptioncancellist; }; dictionary serviceavailabledata { domstring apiresult; }; dictionary serviceavailableapiresult { domstring status; domstring result; domstring serviceyn; }; [nointerfaceobject] interface billingmanagerobject { readonly attribute billingmanager billing; }; webapi implements billingmanagerobject; [nointerfaceobject] interface billingmanager { void buyitem domstring appid, tvservertype servertype, domstring paymentdetails, billingbuydatasuccesscallback onsuccess, optional errorcallback? onerror ; void getproductslist domstring appid, domstring countrycode, domstring pagesize, domstring pagenumber, domstring checkvalue, tvservertype servertype, billingproductslistcallback onsuccess, optional errorcallback? onerror ; void applyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingapplyinvoicecallback onsuccess, optional errorcallback? onerror ; void verifyinvoice domstring appid, domstring customid, domstring invoiceid, domstring countrycode, tvservertype servertype, billingverifyinvoicecallback onsuccess, optional errorcallback? onerror ; void getservicecountryavailability domstring appid, domstring[] countrycodes, domstring checkvalue, tvservertype servertype, billinggetservicecountryavailabilitycallback onsuccess, optional errorcallback? onerror ; void getuserpurchaselist domstring appid, domstring customid, domstring countrycode, domstring pagenumber, domstring checkvalue, tvservertype servertype, billinggetuserpurchaselistcallback onsuccess, optional errorcallback? onerror ; void cancelsubscription domstring appid, domstring invoiceid, domstring customid, domstring countrycode, tvservertype servertype, billingcancelsubscriptioncallback onsuccess, optional errorcallback? onerror ; void isserviceavailable tvservertype servertype, billingisserviceavailablecallback onsuccess, optional errorcallback? onerror ; domstring getversion ; }; [callback = functiononly, nointerfaceobject] interface billingbuydatasuccesscallback { void onsuccess billingbuydata data ; }; [nointerfaceobject] interface billingbuydata { attribute domstring payresult; attribute domstring paydetail; }; [callback = functiononly, nointerfaceobject] interface billingproductslistcallback { void onsuccess productslistdata data ; }; [callback = functiononly, nointerfaceobject] interface billingapplyinvoicecallback { void onsuccess applyinvoicedata data ; }; [callback = functiononly, nointerfaceobject] interface billingverifyinvoicecallback { void onsuccess verifyinvoicedata data ; }; [callback = functiononly, nointerfaceobject] interface billinggetuserpurchaselistcallback { void onsuccess userpurchasedata data ; }; [callback = functiononly, nointerfaceobject] interface billinggetservicecountryavailabilitycallback { void onsuccess servicecountryavailabilitydata data ; }; [callback = functiononly, nointerfaceobject] interface billingcancelsubscriptioncallback { void onsuccess cancelsubscriptiondata data ; }; [callback = functiononly, nointerfaceobject] interface billingisserviceavailablecallback { void onsuccess serviceavailabledata data ; }; };
Develop Samsung IAP
docdeprecated apis deprecated apis are not supported!the apis documented on this page are deprecated, should not be used, and are not supported this documentation is retained for historical and archival purposes only create a service token soap deprecated end of 2024 createservicetoken generates and returns access token value that your server must use to authenticate getsubscriptionstatus soap requests each token is valid for 30 days noteif a token expires during the processing of a soap api request, your server must get a new token and resubmit the soap api reqeust request post https //iap samsungapps com/iap/ws/rtcservice?wsdl <soapenv envelope xmlns soapenv="http //schemas xmlsoap org/soap/envelope/" xmlns ws="http //ws iap samsung com/"> <soapenv header/> <soapenv body> <ws createservicetoken> <secret>{secret}</secret> </ws createservicetoken> </soapenv body> </soapenv envelope> parameters parameter type description secret string required unique id up to 12 numerical digits assigned by samsung to each selleryour secret is your seller deeplink in seller portal go to your profile page and scroll to the information for seller page table example post /iap/ws/rtcservice?ws http/1 1 host iap samsung com <soapenv envelope xmlns soapenv="http //schemas xmlsoap org/soap/envelope/" xmlns ws="http //ws iap samsung com/"> <soapenv header/> <soapenv body> <ws createservicetoken> <secret>123456789012</secret> </ws createservicetoken> </soapenv body> </soapenv envelope> response noteresponse parameters may be added, changed, and deleted <soap envelope xmlns soap="http //schemas xmlsoap org/soap/envelope/"> <soap body> <ns2 createservicetokenresponse xmlns ns2="http //ws iap samsung com/"> <output>{output}</output> </ns2 createservicetokenresponse> </soap body> </soap envelope> parameters parameter type description output string value of your service token id 96 alphanumeric characters example <soap envelope xmlns soap="http //schemas xmlsoap org/soap/envelope/"> <soap body> <ns2 createservicetokenresponse xmlns ns2="http //ws iap samsung com/"> <output>de4d8cd4843eb59388a8834ac833c4bfbaf </output> </ns2 createservicetokenresponse> </soap body> </soap envelope> check subscription status soap deprecated end of 2024 use the iap subscription api, check status of subscription, instead getsubscriptionstatus gets subscription status, item information, and purchase information of a specified auto recurring subscription ars item that was purchased previously request post https //iap samsungapps com/iap/ws/rtcservice?wsdl <soapenv envelope xmlns soapenv="http //schemas xmlsoap org/soap/envelope/" xmlns ws="http //ws iap samsung com/"> <soapenv header/> <soapenv body> <ws getsubscriptionstatus> <purchaseid>{purchase_id}</purchaseid> <servicetoken>{service_token}</servicetoken> </ws getsubscriptionstatus> </soapenv body> </soapenv envelope> parameters parameter type description purchaseid string required unique identifier assigned by samsung iap to the in-app item purchase of the subscription item servicetoken string required value of your service token id 96 alphanumeric characters obtained by calling createservicetoken example post /iap/ws/rtcservice?ws http/1 1 host iap samsung com <soapenv envelope xmlns soapenv="http //schemas xmlsoap org/soap/envelope/" xmlns ws="http //ws iap samsung com/"> <soapenv header/> <soapenv body> <ws getsubscriptionstatus> <purchaseid>asd040f7c36e98d5ca3edf377a40fb </purchaseid> <servicetoken>22afdc3cd60279fad4cf59b17ed85833b9 </servicetoken> </ws getsubscriptionstatus> </soapenv body> </soapenv envelope> response noteresponse parameters may be added, changed, and deleted <soap envelope xmlns soap="http //schemas xmlsoap org/soap/envelope/"> <soap body> <ns2 getsubscriptionstatusresponse xmlns ns2="http //ws iap samsung com/"> <output> <subscriptionpurchasedate>{subscription_purchase_date}</subscriptionpurchasedate> <subscriptionenddate>{subscription_end_date}</subscriptionenddate> <subscriptiontype>{subscription_type}</subscriptiontype> <subscriptionstatus>{subscription_status}</subscriptionstatus> <subscriptionfirstpurchaseid>{subscription_first_purchase_id|</subscriptionfirstpurchaseid> <countrycode>{country_code}</countrycode> <localcurrencycode>{local_currency_code}</localcurrencycode> <localprice>{local_price}</localprice> <supplyprice>{supply_price}</supplyprice> <itemid>{item_id}</itemid> <freetrial>{free_trial}</freetrial> <realmode>{real_mode}</realmode> <latestorderid>{latest_order_id}</latestorderid> <totalnumberoftieredpayment>{total_number_of_payment}</totalnumberoftieredpayment> <currentpaymentplan>{current_payment_plan}</currentpaymentplan> <totalnumberofrenewalpayment>{total_number_of_renewal_payment}</totalnumberofrenewalpayment> <subscriptionfirstpaymentdate>{subscription_first_payment_date}</subscriptionfirstpurchasedate> <cancelsubscriptiondate>{cancel_subscription_date}</cancelsubscriptiondate> <cancelsubscriptionreason>{cancel_subscription_reason}</cancelsubscriptionreason> </output> </ns2 getsubscriptionstatusresponse> </soap body> </soap envelope> parameters parameter type description output nestedobject container for the elements subscriptionpurchasedate string date and time of the item's initial purchase and payment transaction yyyy-mm-dd hh mm ss gmt subscriptionenddate string date and time of the subscription expiration yyyy-mm-dd hh mm ss gmt subscriptiontype string type of subscription itembelow value is always returned item_type_auto_recurring_subscription subscriptionstatus string current status of the item subscription"active" the subscription is current and in effect "cancel" the user canceled the subscription check the subscriptionenddate to see if the subscription period has ended as the canceled item is still valid until the current suscription period has ended subscriptionfirstpurchaseid string unique identifier of the initial purchase of the item countrycode string country code 3 alphabetic characters of the purchaser's location for example, kor, usa localcurrencycode string currency code 3 alphabetic characters of the purchaser's local currency paid for the item for example, eur, gbp, usd localprice double cost in the user's local currency that the user paid the in-app item price supplyprice double total amount of the item price plus the applied tax itemid string unique identifier of the in-app item registered in seller portal freetrial string whether or not the in-app item's subscription is currently in a free trial period "y" free trial period"n" regular price period realmode string for regular purchases, whether the actual payment was made when the user purchased the item "y" samsung iap was set to production mode the actual payment was made "n" samsung iap was set to test mode the actual payment was not made latestorderid string identifier 19 alphanumeric characters of the most recent payment it can be an initial payment or a renewal payment order ids are displayed in the user's renewal receipt totalnumberoftieredpayment string total number of tiered price payments currentpaymentplan string current period the subscription is in - "f" free trial period- "r" regular price period- "t" tiered lower price period totalnumberofrenewalpayment string total number of payments made for initial and renewal subscriptions subscriptionfirstpaymentdate string date and time the initial subscription started yyyy-mm-dd hh mm ss gmt cancelsubscriptiondate string date and time the subscription was stopped yyyy-mm-dd hh mm ss gmt cancelsubscriptionreason string cause of the subscription stoppage "1" user canceled the subscripton "2" system canceled the subscription for example, renewal test was finished "3" billing error for example, user payment information was no longer valid "4" item is not available for purchase at the time of renewal "5" unknown errors example <soap envelope xmlns soap="http //schemas xmlsoap org/soap/envelope/"> <soap body> <ns2 getsubscriptionstatusresponse xmlns ns2="http //ws iap samsung com/"> <output> <subscriptionpurchasedate>2019-07-14 04 28 52</subscriptionpurchasedate> <subscriptionenddate>2020-09-21 04 28 52</subscriptionenddate> <subscriptiontype>item_type_auto_recurring_subscription</subscriptiontype> <subscriptionstatus>active</subscriptionstatus> <subscriptionfirstpurchaseid>0cc3325d051cd83981abe6c33eb3a5b41404</subscriptionfirstpurchaseid> <countrycode>usa</countrycode> <localcurrencycode>usd</localcurrencycode> <localprice>1 000</localprice> <supplyprice>1 010</supplyprice> <itemid>subscriptionitem104</itemid> <freetrial>y</freetrial> <realmode>y</realmode> <latestorderid>p20190814us15845453</latestorderid> <totalnumberoftieredpayment>0</totalnumberoftieredpayment> <currentpaymentplan>r</currentpaymentplan> <totalnumberofrenewalpayment>1</totalnumberofrenewalpayment> <subscriptionfirstpaymentdate>2019-07-21 04 28 52</subscriptionfirstpaymentdate> </output> </ns2 getsubscriptionstatusresponse> </soap body> </soap envelope> error response error code error message description 10 missing_parameter a required parameter is missing 15 invalid_parameter_value a parameter value is invalid 300 invalid_secret the service token is invalid 301 expired_service_token the service token has expired -1 unknown_error a server error has occurred example <soap envelope xmlns soap="http //schemas xmlsoap org/soap/envelope/"> <soap body> <soap fault> <faultcode>soap server</faultcode> <faultstring>fault occurred while processing </faultstring> <detail> <ns1 webserviceexception xmlns ns1="http //ws iap samsung com/"> <errorcode xsi type="xs int" xmlns ns2="http //ws iap samsung com/" xmlns xs="http //www w3 org/2001/xmlschema" xmlns xsi="http //www w3 org/2001/xmlschema-instance"> 301 </errorcode> <errormessage xmlns ns2="http //ws iap samsung com/"> expired_service_token </errormessage> </ns1 webserviceexception> </detail> </soap fault> </soap body> </soap envelope>
Develop Smart TV
doctesting samsung checkout on tv for testing in-app purchases and payments in your application, please follow below process pre-conditions before starting test join in samsung seller office and register your applications set 'billing' field to 'use' and 'samsung checkout on tv' field to 'yes' prerequisites join dpi portal and create product for verifying subscription plan add new subscription group and plan register test buyer testing basic checkout purchase workflow launch your application request the purchase list to dpi server request the product list to dpi server call samsung checkout to buyitem when the user selects “buy” in the application, provide a common purchase gui through samsung checkout the user can enter a voucher or coupon code to modify the purchase price the user confirms the purchase by entering a pin on the common purchase gui, or biometric information on samsung pay request the purchase list to dpi server call verify purchase api to dpi server call apply the product api to dpi server testing upgrade/downgrade the subscription plan launch your application get the list of products that can be changed in this subscription subscription plan change changeable-products api pre-check the impact of changing subscription products subscription plan change pre-check api reserve subscription plan changes subscription plan change reserve api get subscription plan change reservation status subscription plan change reservation status api cancel subscription plan change reservation subscription plan change cancel status api
Develop Smart TV
api'tizen tv service billing' namespace reference enumerations billingrequestpurchasehistorytype purchase history list type more billingrequestservertype billing server type more billingdeeplinktype deep-link page type more functions enumerations billingrequestpurchasehistorytype enumerator all all purchases subscription subscription purchases nonsubscription non-subscription purchases purchase history list type privilege http //developer samsung com/privilege/billing privilege level public product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n billingrequestservertype enumerator prd operating server dev development server dummy dummy payment server billing server type privilege http //developer samsung com/privilege/billing privilege level public product tv version 4 4 0 sdk support n billingdeeplinktype enumerator registercreditcard credit card registration page purchaseshistory purchase history page registerpromotionalcode promotional code registration page paymentinfo payment information page deep-link page type privilege http //developer samsung com/privilege/billing privilege level public product tv deprecated deprecated since 5 5 0 version 4 4 0 sdk support n functions
tutorials mobile, game
blogin-app purchases and subscriptions are the most common and popular ways to monetize an app. samsung in-app purchase (iap) is a payment service, which allows you to sell your in-app items that are distributed through the samsung galaxy store. samsung iap offers an sdk for android, plugins for unity and unreal applications, and server apis. in this article, we will learn about how to implement samsung iap server api in your app’s server. why you need to have your own server in some cases, your app may experience network interruptions after an item purchase and payment transaction. malicious attacks can happen which may create security issues in your app. moreover, malicious users may get your premium contents without buying it if the content is embedded within the app. so, you can reduce these problems by using a server for your app to validate the purchase receipt, provide contents from the server and store the payment related data. why iap server apis are required samsung provides iap server apis to prevent malicious purchases and to handle these challenging scenarios. these apis let you verify a purchase and get detailed information about a subscription. you will be able to know whether a subscription is going to expire soon, or the cause of the subscription cancellation from server apis. it will help you to manage subscriptions and to promote your content based on this data. it is not mandatory to implement iap server apis. you can communicate with the iap server directly from your app. however, if you want to validate the purchase receipt and get detailed information about a subscription then iap server apis offer great flexibility. a server-side application is required for implementing iap server apis. your application requests the server to fetch some data from the iap server. your server gets this data from the iap server by using server apis and returns the data to your app. we will discuss this data flow process between an app, server and iap server in two parts. in this blog, we discuss how to integrate samsung’s iap server api into your app’s server. in the second part, we will cover communication between your app and server. please go through the documentation of samsung iap sdk to integrate samsung iap sdk into your app. to know about server apis, read samsung iap server api. the following scenario gives you a snapshot of the communication between your app, server and iap server. figure 1: overview diagram of samsung iap server api here, we assume that you have completed your app successfully by implementing samsung iap sdk and registered it in the seller office to test in-app items. now you are ready to create your app server. get started at first, let’s create a java dynamic web application by using servlet for the app server. server api will be implemented here to communicate with the samsung iap server. for simplicity, we have created two servlets for processing the two requests. one is for validating a purchase of an item and another is to check out the status of a subscription item. the client app sends the request to the respective servlet. the respective servlet processes the request and returns the output. the client app executes a task as per the result from the servlet. figure 2: communication with servlets servlets in java, a servlet is a type of java class which runs in a java-enabled server and handles http requests. we will need a web container that supports servlet technology, so we have used apache tomcat 7.0 as a server. we have already mentioned creating two servlets for the two processes. each servlet has three parts: getting purchase id from the client app processing the specific task using this purchase id returning the result to the client app getting purchase id from client app the purchase id of an item is required to verify payment transaction and to call getsubscriptionstatus. we need to send purchase id from the client app to our server. servlet receives that purchase id in dopost() method. int length = request.getcontentlength(); byte[] input = new byte[length]; servletinputstream in = request.getinputstream(); int c, count = 0 ; while ((c = in.read(input, count, input.length - count)) != -1) { count += c; } in.close(); string recievedstring = new string(input); response.setstatus(httpservletresponse.sc_ok); string purchasestatus = purchaseverification(recievedstring); // to verify a purchase string subscriptionstatus = serverstatusverification(recievedstring); // to get status of subscription item verify a purchase iap/v6/receipt enables your server and client app to verify that a specified in-app item purchase and payment transaction was successfully completed. here, we use http request to validate the purchase. a json object is returned with detailed information of a purchase. see the following code snippet in purchaseverification() method for validating a purchase: string purchasestatus=""; string url="https://iap.samsungapps.com/iap/v6/receipt?purchaseid="+purchaseid; url obj = new url(url); httpurlconnection con = (httpurlconnection) obj.openconnection(); bufferedreader in = new bufferedreader(new inputstreamreader(con.getinputstream())); string inputline; stringbuffer res = new stringbuffer(); while ((inputline = in.readline()) != null) { res.append(inputline); } in.close(); jsonobject myresponse = new jsonobject(res.tostring()); purchasestatus = myresponse.get("status").tostring(); create a service token a service token is needed to authenticate getsubscriptionstatus soap requests. at first, we need to create a soap web service client from a wsdl file. so, we have generated jax-ws portable artifacts from wsdl that can be packaged in a web application archive (war) file. jax-ws-stubs (artifacts) can be generated from a given wsdl using the wsimport. the wsdl link is: https://iap.samsungapps.com/iap/ws/rtcservice?wsdl after generating jax-ws portable artifacts, we have written a class called subscriptiondetails to create service token using secret id. to know your secret id, go to your profile page and scroll to the information for seller page table. rtcservice rtcservice = new rtcservice(); rtcservice2 rtcimpl = rtcservice.getrtcserviceimplport(); createservicetokenresponse servicetokenoutput = new createservicetokenresponse(); createservicetoken servicetoken = new createservicetoken(); servicetoken.setsecret(secretid); try { servicetokenoutput.setoutput(rtcimpl.createservicetoken(servicetoken.getsecret())); } catch(exception e) { } check subscription status getsubscriptionstatus is used to get subscription status, item information, and purchase information of a specified auto recurring subscription (ars) item that was previously purchased. after getting the service token, we have used soap request to get subscription status in subscriptiondetails class. getsubscriptionstatusws subscriptionstatus = new getsubscriptionstatusws(); try { subscriptionstatus = rtcimpl.getsubscriptionstatus(purchaseid, servicetokenoutput.getoutput()); } catch(exception e) {} return subscriptionstatus; finally, using the following code snippet in serverstatusverification() method we can get the subscription status: subscriptiondetails sub = new subscriptiondetails(); getsubscriptionstatusws subscriptionstatus = new getsubscriptionstatusws(); subscriptionstatus = sub.soapdata(purchaseid); string status = subscriptionstatus.getsubscriptionstatus().tostring(); return status; return the result to client app now return the result of purchaseverification() or serverstatusverification() method to the client app. outputstreamwriter writer = new outputstreamwriter(response.getoutputstream()); writer.write(status); writer.flush(); writer.close(); testing let’s test the application. call purchaseverification() or serverstatusverification() method by passing a purchase id in doget() method and call doget() method in dopost() by passing the request and response. protected void doget(httpservletrequest request, httpservletresponse response) throws servletexception, ioexception { string x = serverstatusverification("3fc70af0a118909d0c8b04eaa1eaee823795c982fc8e39f87faa12c58be43f05"); } run the app on the apache tomcat 7.0 server. if your servlet works perfectly then create a .war file for this java application. there are many cloud service providers such as aws, heroku which you can use for your server. after creating a .war file, deploy it on a cloud. get the url of your app from the cloud service provider and use that url to test the server apis by using any browser. conclusion server application is not only useful for security issues but also helpful for marketing. if you provide same premium contents in the multiple platforms, then you can use this server application for all applications. you can keep a record of the detailed information of purchased items and subscriptions which can be helpful for your business in many aspects. for example, you can store your user’s subscription status. based on this data, you can promote a new item, provide offers to potential users and give recommendations to the new users. we are at the end of this article and hope you found the information helpful. see the next blog for part two. follow up this site has many resources for developers looking to build for and integrate with samsung devices and services. stay in touch with the latest news by creating a free account or by subscribing to our monthly newsletter. visit the marketing resources page for information on promoting and distributing your apps. finally, our developer forum is an excellent way to stay up-to-date on all things related to the galaxy ecosystem.
Jakia Sultana
Develop Samsung IAP
docsamsung iap subscription api the samsung iap subscription api is used to cancel, refund, revoke, and check the status of samsung in-app purchase iap subscriptions before you can start using the iap subscription api, you must meet all requirements, use the required authorization header parameters, and use the required url path paremeters in your requests see get started with the iap apis for more information the following is a quick reference to the iap subscription apis name method description cancel subscription patch cancel the subscription corresponding to the given purchaseid when a subscription is canceled, automatic payments are no longer made after the current subscription period ends customers can use the subscription until the end of the current subscription period refund subscription patch reimburse the most recent payment for the subscription corresponding to the given purchaseid the current subscription continues revoke subscription patch immediately cancel the subscription and reimburse the most recent payment for the subscription corresponding to the given purchaseid when a subscription is revoked, customers instantly lose the ability to use the subscription, even if the current subscription period has not ended and, automatic payments are no longer made after the current subscription period ends check status of subscription get check the subscription status cancel, refund, or revoke subscription cancel, refund, or revoke a subscription see the table below for a description of each action request patch /iap/seller/v6/applications/<packagename>/purchases/subscriptions/<purchaseid> notesee url path parameters for more information about the <packagename> and <purchaseid> parameters body parameter name type description action string required the task to perform must be one of the following cancel end the subscription when a subscription is cancelled, the customer can still access the subscription until the end of the current subscription period after the current subscription period ends, access to the subscription should be blocked refund reimburse the most recent payment to the subscriber the subscriber can still use the subscription use this if there is a service error or you want to issue a complimentary coupon revoke immediately cancel the subscription and immediately refund the most recent payment when a subscription is cancelled, the customer instantly loses the ability to use the subscription, even if the current subscription period has not ended access to the subscription should be blocked immediately curl -i -x patch \ -h "content-type application/json" \ -h "authorization bearer <your-access-token>" \ -h "service-account-id <your-service-account-id>" \ -d '{"action" "cancel | refund | revoke"}' \ 'https //devapi samsungapps com/iap/seller/v6/applications/<packagename>/purchases/subscriptions/<purchaseid>' response name type description code string success code, iap internal error code, or http status code message string detailed information about error or http reason { "code" "0000", "message" "success" } see failure response codes for a list of possible response codes when a request fails check status of subscription get the subscription status, including subscription information and purchase information, which can be used to verify the purchase of a subscription request get /iap/seller/v6/applications/<packagename>/purchases/subscriptions/<purchaseid> notesee url path parameters for more information about the <packagename> and <purchaseid> parameters curl -i -x get \ -h "content-type application/json" \ -h "authorization bearer <your-access-token>" \ -h "service-account-id <your-service-account-id>" \ 'https //devapi samsungapps com/iap/seller/v6/applications/<packagename>/purchases/subscriptions/<purchaseid>' response parameters parameter type description subscriptionpurchasedate string date and time of the subscription's initial purchase and payment transaction yyyy-mm-dd hh mm ss gmt subscriptionenddate string date and time when the subscription expires yyyy-mm-dd hh mm ss gmt subscriptionstatus string current status of the subscription"active" the subscription is current and in effect "cancel" the user canceled the subscription check the subscriptionenddate to see if the subscription period has ended as the canceled subscription is still valid until the current suscription period has ended subscriptionfirstpurchaseid string unique identifier of the initial purchase of the subscription countrycode string country code 3 alphabetic characters of the purchaser's location for example, kor, usa price[] localcurrencycode string currency code 3 alphabetic characters of the purchaser's local currency paid for the subscription for example, eur, gbp, usd price[] localprice double cost in the user's local currency that the user paid for the subscription price[] supplyprice double total amount of the subscription price plus the applied tax itemid string unique identifier of the subscription registered in seller portal freetrial string whether or not the subscription is currently in a free trial period "y" free trial period"t"tiered lower/introductory price period"n" regular price period realmode string for regular purchases, whether the actual payment was made when the user purchased the subscription "y" samsung iap was set to production mode the actual payment was made "n" samsung iap was set to test mode the actual payment was not made latestorderid string identifier 19 alphanumeric characters of the most recent payment it can be an initial payment or a renewal payment order ids are displayed in the user's renewal receipt totalnumberoftieredpayment string total number of tiered price payments currentpaymentplan string current period the subscription is in "f" free trial period"r" regular price period"t" tiered lower price period totalnumberofrenewalpayment string total number of payments made for initial and renewal subscriptions cancelsubscriptiondate string date and time the subscription was stopped yyyy-mm-dd hh mm ss gmt cancelsubscriptionreason string cause of the subscription stoppage "1" user canceled the subscripton "2" system canceled the subscription for example, renewal test was finished "3" billing error for example, user payment information was no longer valid "4" subscription is not available for purchase at the time of renewal "5" unknown errors graceperiodyn string whether or not the subscription is currently in a grace period "y" the subscription is in a grace period"n" the subscription is not in a grace period graceperiodenddate string the end date and time of the grace period yyyy-mm-dd hh mm ss gmt if the subscription is not in a grace period graceperiodyn = "n" , this value is set to null pricechange[] pricechangemode string the mode of the price change "1" price increase which requires the user’s consent"2" price increase which does not require the user’s consent"3" price decrease, which does not require the user’s consent pricechange[] pricechangestatus string the status of the price change "waiting" waiting for the subscriber to answer"confirmed" the price change is acknowledged by the subscriber either the subscriber consented or did not consent to the increase in price "applied" the subscriber is charged the new price pricechange[] pricechangeconsentdate string date and time the subscriber consented yyyy-mm-dd hh mm ss gmt pricechange[] expectednewpricechargedate string date and time the new price will affect the subscriber yyyy-mm-dd hh mm ss gmt pricechange[] newprice[] localcurrencycode string local currency code 3 alphabetic characters of the changed price for example, eur, gbp, usd pricechange[] newprice[] localprice double cost in the user's local currency that the user paid for the subscription success { "subscriptionpurchasedate" "2024-05-31 01 30 13 gmt", "subscriptionenddate" "2024-06-03 01 03 30 gmt", "subscriptionstatus" "cancel", "subscriptionfirstpurchaseid" "649922f760188d759c19636c4efe130d0743bd6f5446504e0a8e68b0010e0ab7", "countrycode" "kor", "price" { "localcurrencycode" "krw", "localprice" 1000 0, "supplyprice" 1000 0 }, "itemid" "subsc_30min", "freetrial" "n", "realmode" "y", "latestorderid" "s20240531kr01924958", "totalnumberoftieredpayment" "0", "currentpaymentplan" "r", "totalnumberofrenewalpayment" "3", "cancelsubscriptiondate" "2024-06-03 01 03 29 gmt", "cancelsubscriptionreason" "2", "graceperiodyn" "y", "graceperiodenddate" "2024-06-10 01 03 29 gmt", "pricechange" { "pricechangemode" "1", "pricechangestatus" "waiting", "pricechangeconsentdate" null, "expectednewpricechargedate" "2024-05-31 02 22 02 gmt", "newprice" { "localcurrencycode" "krw", "localprice" 1500 0 } } } see failure response codes for a list of possible response codes when a request fails failure response codes status code and message 400bad request slr_4001 seller does not matchslr_4014 subscription does not existslr_4015 missing required parameterslr_4016 purchase id does not exist slr_4017 unknown action parameterslr_4018 the purchase id cannot be refunded 401unauthorized slr_4008 failed to verify gateway server authorization 404not found slr_4006 application id does not exist 406not acceptable slr_4019 the purchase id has already been suspended and will not be renewed slr_4020 the purchase id has already been refunded slr_4021 failed to cancel the subscription for an unknown reason slr_4022 failed to refund the subscription for an unknown reason slr_4023 failed to revoke the subscription for an unknown reason
We use cookies to improve your experience on our website and to show you relevant advertising. Manage you settings for our cookies below.
These cookies are essential as they enable you to move around the website. This category cannot be disabled.
These cookies collect information about how you use our website. for example which pages you visit most often. All information these cookies collect is used to improve how the website works.
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and tailor the website to provide enhanced features and content for you.
These cookies gather information about your browser habits. They remember that you've visited our website and share this information with other organizations such as advertisers.
You have successfully updated your cookie preferences.