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