en zh

Samsung IAP Server API

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 canceled

Note: 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 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.0
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",
   "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"
}

Create a service token

createServiceToken generates and returns access token value that your server must use to authenticate getSubscriptionStatus SOAP requests. Each token is valid for 30 days.

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

<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.

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

<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
object

 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 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).
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>