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 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
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
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 |
subscription |
String | Date and time of the item's initial purchase and payment transaction (YYYY-MM-DD HH:mm:ss GMT) |
subscription |
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 |
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. |
totalNumberOf |
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
|
totalNumberOf |
String | Total number of payments made for initial and renewal subscriptions |
subscription |
String | Date and time the initial subscription started (YYYY-MM-DD HH:mm:ss GMT) |
cancelSubscription |
String | Date and time the subscription was stopped (YYYY-MM-DD HH:mm:ss GMT) |
cancelSubscription |
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>