Skip to main content
Samsung Developer Program

IAP Server API Reference

The Samsung IAP Server API enables you to verify in-app purchases and get the status of subscription in-app items through your app server.

SamsungIAP_v5_Architecture_IapServer.png

 

Your app server can get the following from the IAP server:

  • Information about any in-app purchase to verify whether or not the purchase and payment transaction was successful. 
  • An access token to authorize IAP Server SOAP calls.
  • The current status (active or expired) and other information about any subscription in-app item.
     

getPurchaseReceipt

An HTTP GET request that returns the following in a JSON object: 

  • Information about the specified in-app item purchase and payment transaction, when the transaction was successful.
    or
  • Notification that the transaction failed.
     

Request URL Format 

https://iap.samsungapps.com/iap/getPurchaseReceipt.as
?protocolVersion=[protocolVersion value]
&purchaseID=[purchaseID value]

 

Request Parameters

protocolVersion

String

Required  Version number of Samsung IAP implemented at the time of purchase.

purchaseID

String

Required  Unique identifier of the in-app item purchase and payment transaction

Note: The purchase ID is assigned by Samsung IAP. Your Android app receives it in the PurchaseVo object of the OnPaymentListener interface. Your Android app must provide the ID to your app server using a method that is independent of Samsung IAP.

 

Example Request

https://iap.samsungapps.com/iap/getPurchaseReceipt.as
?protocolVersion=5.0
&purchaseID=d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590

 

Response Parameters

Note: If the purchase and payment transaction was successful, all parameters are returned.  If the transaction failed, only the status parameter is returned.

itemId

String

Unique identifier of the in-app item registered in Seller Office

itemName

String

Title of the in-app item registered in Seller Office

itemDesc

String

Brief explanation of the in-app item registered in Seller Office

paymentId

String

Unique identifier assigned to the in-app item payment transaction when it was successful

orderId

String

Unique identifier of the purchase receipt

purchaseDate

String

Date (YYYY-MM-DD HH:mm:ss) of the in-app item purchase and payment transaction.

paymentAmount

String

Total amount, including the in-app item price and all applicable taxes, billed to the user

status

String

Processing result of the in-app item purchase and payment transaction: 

true - The transaction was successful.

false - The transaction failed.

paymentMethod

String

Type of payment option used to purchase the in-app item: CreditCard, MobileMicroPurchase, PrepaidCard, PSMS, CarrierBilling, and others

mode

String

IAP operating mode in effect at the time of purchase:

TEST - Developer Test Mode or Developer Test Mode (Failure)

REAL - 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 - The item is available for purchase again.

N - The item is not available for purchase.

Note: This is returned only for Samsung IAP v5.0 and later.

consumeDate

String

Date (YYYY-MM-DD HH:mm:ss) the item was reported as consumed

Note: This is returned only for Samsung IAP v5.0 and later.

consumeDeviceModel

String

Type of user's Samsung mobile device

Note: This is returned only for Samsung IAP v5.0 and later.

passThroughParam

String

Identifier assigned by your app to the purchase transaction

When your app assigns the identifier, it is returned by the Samsung server, in order to enhance purchase security.

When your app does not assign an identifier, successful returns do not include this parameter.

currencyCode String Code (3 characters) of the purchaser's local currency
currencyUnit String Symbol of the purchaser's local currency

 

Example Responses

The IAP server returns the results in JSON format.

When the purchase and payment transaction was successful:

 {
    "itemId" : "57515",
    "paymentId":"ZPMTID20131122GBI0015292",
    "orderId":"P20131122GBI0015292",
    "itemName":"Test Pack",
    "itemDesc":"IAP Test Item. Best value!",
    "purchaseDate":"2013-11-22 04:22:36",
    "paymentAmount":"9.000",
    "status":"true",
    "paymentMethod":"CreditCard",
    "mode":"REAL",
    "consumeYN":"Y",
    "consumeDate":"2017-08-08 04:47:38",
    "consumeDeviceModel":"SM-G935K",
    urrencyCode": "USD", 
    "currencyUnit": "$" 
 }

When the purchase and payment transaction failed:

 {"status":"false"}

 

 

createServiceToken

Generates and returns an access token value that you use later to authenticate IAP Server API SOAP requests.
 

HTTP Post Request

https://iap.samsungapps.com/iap/ws/RTCService?wsdl


SOAP Request Parameter

secret

String

Required  Unique ID value (10 alphanumeric characters) assigned by Samsung to you.

You can get the ID in your Seller Office profile (Seller Office > Profile > Information for Seller Page > Seller Deeplink).

 

SOAP Request Body Syntax

<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 value]</secret>
        </ws:createServiceToken>
     </soapenv:Body>
</soapenv:Envelope>

 

 

Example Request

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>vdndh0k80k</secret>
        </ws:createServiceToken>
    </soapenv:Body>
</soapenv:Envelope>

 

Response Parameters

output

String

Value (60 alphanumeric characters) of the access token issued to you

 

Example Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:createServiceTokenResponse xmlns:ns2="http://ws.iap.samsung.com/">
            <output>de4d8cd4843eb59388a8834ac833c4bfbaf94d931e497e035f236cq9f733</output>
        </ns2:createServiceTokenResponse>
    </soap:Body>
</soap:Envelope>

 

getSubscriptionStatus

A SOAP API that returns the current status and other information about the specified subscription in-app item.

For SOAP error responses, see IAP Server SOAP Error Responses.
 

HTTP Post Request

https://iap.samsungapps.com/iap/ws/RTCService?wsdl


SOAP Request Parameter

purchaseID String Required  Unique identifier assigned by Samsung IAP to the in-app item purchase of the subscription item

serviceToken

String

Required  Value (60 alphanumeric characters) of the access token issued by Samsung to your service app

 

SOAP Request Body Syntax

<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 value]</purchaseID>
            <serviceToken>[service token value]</serviceToken>
        </ws:getSubscriptionStatus>
    </soapenv:Body>
</soapenv:Envelope>

 

 

Example Request

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>asd040f7c36e98d5ca3edf377a40fb16bvvbefgc389d7e79170e7</purchaseID>
            <serviceToken>>22afdc3cd60279fad4cf59b17ed85833b9dfgf35ce08ac380</serviceToken>
        </ws:getSubscriptionStatus>
    </soapenv:Body>
</soapenv:Envelope>

 

SOAP Response Parameters

Note: The local currency is the currency of the user's country, and the local price is the in-app item's price in the local currency, at the time of the purchase and payment transaction.

output

Nested object

Value of the access token

subscriptionPurchaseDate Long Date (YYYY-MM-DD HH:mm:ss GMT) of the in-app item's initial or most recent renewal purchase and payment transaction.
subscriptionEndDate Long Date (YYYY-MM-DD HH:mm:ss GMT) that the in-app item's current subscription period will expire

subscriptionType

String

Kind of subscription in-app item

Note: Samsung v5.x only supports auto-recurring subscriptions.  The parameter setting is always Item_Type_Auto_recurring_Subscription.

subscriptionStatus String

State of the in-app item's subscription:

ACTIVE - The subscription is current and in effect.

CANCEL - The subscription has expired (because the user stopped the auto-renewal).

countryCode String Country code (###) of the user's location
localCurrencyCode String Local currency code (###) that the user paid the in-app item price
localPrice Double Cost ([#].### in the user's local currency) that the user paid the in-app item price
supplyPrice  Double Supply price
itemID  String Unique identifier of the in-app item assigned by you

freeTrial 

String

Whether or not the in-app item's subscription is currently in a free trial period:

Y - The subscription is in the free trial period.

N - The subscription is not in the free trial period.

realMode

String

Whether or not the IAP operating mode is the Production Mode:

Y - The mode is the Production Mode; successful in-app item purchases result in actual financial transactions (for example, the user credit card will be billed).

N - The mode is either the Developer Test Mode (Success) or the Developer Test Mode (Failure).  In-app item purchases will not result in actual financial transactions.

 

SOAP Response Body Syntax

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <ns2:getSubscriptionStatusResponse xmlns:ns2="http://ws.iap.samsung.com/">
        <output>
            <subscriptionPurchaseDate>[subscriptionPurchaseDate value]</subscriptionPurchaseDate>
            <subscriptionEndDate>[subscriptionEndDate value]</subscriptionEndDate>
            <subscriptionType>[subscriptionType value]</subscriptionType>
            <subscriptionStatus>[subscriptionStatus value]</subscriptionStatus>
            <countryCode>[countryCode value]</countryCode>
            <localCurrencyCode>[localCurrencyCode value]</localCurrencyCode>
            <localPrice>[localPrice value]</localPrice>
            <supplyPrice>[supplyPrice value]</supplyPrice>
            <itemID>[itemID value]</itemID>
            <freeTrial>[freeTrial value]</freeTrial>
            <realMode>[realMode value]</realMode>
        </output>
    </ns2:getSubscriptionStatusResponse>
</soap:Body>
</soap:Envelope>

 

Example SOAP Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:createServiceTokenResponse xmlns:ns2="http://ws.iap.samsung.com/">
            <output>
                <subscriptionPurchaseDate>1423601486000</subscriptionPurchaseDate>
                <subscriptionEndDate>1423085433000</subscriptionEndDate>
                <subscriptionType>Item_Type_Auto_Recurring_Subscription</subscriptionType>
                <subscriptionStatus>CANCEL</subscriptionStatus>
                <countryCode>USA</countryCode>
                <localCurrencyCode>USD</localCurrencyCode>
                <localPrice>9.990</localPrice>
                <supplyPrice>10.610</supplyPrice>
                <itemID>000001003104</itemID>
                <freeTrial>N</freeTrial>
                <realMode>Y</realMode>
            </output>
        </ns2:createServiceTokenResponse>
    </soap:Body>
</soap:Envelope>