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

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.

(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

NoteResponse parameters may be added, changed, and deleted.

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

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