Samsung IAP Server API
![](https://d3unf4s5rp9dfh.cloudfront.net/SamsungIAP_doc/server2server-v6.jpg)
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.
The API returns a JSON object with a successful status and details about a successful transaction
and the item 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 an item 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 item purchase transaction Note: 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
Parameters
Parameter | Type | Description |
---|---|---|
itemId | String | Unique identifier of the in-app item registered in Seller Portal |
paymentId | String | Unique identifier assigned to the in-app item 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 item registered in Seller Portal |
itemDesc | String | Brief explanation of the in-app item registered in Seller Portal |
purchaseDate | String | Date and time of the item purchase and payment transaction (YYYY-MM-DD HH:mm:ss GMT) |
paymentAmount | String | Total amount, including the in-app item 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 item"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 in-app 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 the consumable item was reported as consumed (YYYY-MM-DD HH:mm:ss GMT) |
consumeDeviceModel | String | Model name of device that reported the item as consumed |
passThroughParam | String | Transaction ID created by your app for security Returned 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", "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", "passThroughParam": "TEST_PASS_THROUGH", "currencyCode": "KRW", "currencyUnit": "₩", "status": "cancel", "cancelDate": "2019-11-29 00:01:52" }
Create a service token
createServiceToken
, along with getSubscriptionStatus
, will be deprecated at the end of 2024. Use the IAP Subscription API, check status of subscription, instead.
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 seller
Your 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
Gets the subscription status, including item information and purchase information, which can be used to verify the purchase of an item.
This call requires the purchase ID of the subscription item and a service token for authentication and checks the user’s subscription information on the server.
Information is returned in a REST response. This API only provides meaningful information after a subscription is purchased.
Subscription-related content includes the purchase date, current subscription status, current price, current subscription pricing option, number of renewals, paid subscription start date, subscription end date, and reason for cancellation.
Before you can start using the IAP Subscription API, you must meet all requirements and use the required authorization header parameters in your requests. See Get Started with the IAP APIs for more information.
See Check status of subscription for more information about this IAP Subscription API.
WarningThis version of the API, which returns information in a SOAP response, will be deprecated by the end of 2024. Use the latest API, shown above, which returns information in a REST response.Check subscription status
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 nested
objectContainer for the elements subscription PurchaseDate String Date and time of the item's initial purchase and payment transaction
(YYYY-MM-DD HH:mm:ss GMT)subscription EndDate String Date and time of the subscription expiration
(YYYY-MM-DD HH:mm:ss GMT)subscriptionType String Type of subscription item
Below 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).subscription FirstPurchaseID 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 periodrealMode 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.totalNumberOf TieredPayment 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 periodtotalNumberOf RenewalPayment String Total number of payments made for initial and renewal subscriptions subscription FirstPaymentDate String Date and time the initial subscription started
(YYYY-MM-DD HH:mm:ss GMT)cancelSubscription Date String Date and time the subscription was stopped
(YYYY-MM-DD HH:mm:ss GMT)cancelSubscription Reason 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>