Samsung IAP 服务器 API

验证购买

iap/v6/receipt 可支持您的服务器和客户端应用程序，以验证所指定的应用程序内项目购买和付款交易是否已成功完成。

API 将返回一个 JSON 对象，其中包含成功状态和有关成功交易及项目的详细信息，
或包含失败状态。

此 API 有助于防止恶意购买，并确保在项目购买和付款交易之后，如果客户端应用程序遇到网络中断，购买和付款交易可成功进行。

请求

GET
https://iap.samsungapps.com/iap/v6/receipt?purchaseID={purchaseID value}

查询参数

参数类型说明

purchaseID

String

参数	类型	说明
purchaseID	String	（必需）应用程序内项目购买交易的唯一标识符注意：购买 ID 由 Samsung IAP 分配。您的应用程序将在 `OnPaymentListener` 接口的 PurchaseVo 对象中收到该 ID。您的应用程序必须独立于 Samsung IAP 将该 ID 发送到服务器。

（必需）应用程序内项目购买交易的唯一标识符

注意：购买 ID 由 Samsung IAP 分配。您的应用程序将在 OnPaymentListener 接口的 PurchaseVo 对象中收到该 ID。
您的应用程序必须独立于 Samsung IAP 将该 ID 发送到服务器。

示例

GET
http://iap.samsungapps.com/iap/v6/receipt?purchaseID=7efef23271b0a48746a9d7c391e367c7a802980d391d7f9b75010e8138c66c36

响应

Note可以添加、更改和删除响应参数。

参数

参数	类型	说明
itemId	String	在卖家门户中注册的应用程序内项目的唯一标识符
paymentId	String	应用程序内项目付款交易成功时分配给交易的唯一标识符
orderId	String	分配给购买收据的唯一标识符
packageName	String	交易已完成的应用程序的程序包名称
itemName	String	在卖家门户中注册的应用程序内项目的标题
itemDesc	String	在卖家门户中注册的应用程序内项目的简要说明
purchaseDate	String	项目购买和付款交易的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
paymentAmount	String	总金额，包括应用程序内项目价格和向用户计费的所有适用税费
status	String	请求收据的处理结果： `"success"`成功 `"fail"` 失败 `"cancel"` 购买交易已取消注意：对于已取消的交易，旧版 `iap/getPurchaseReceipt` 仅传递 `"fail"`，但 `iap/v6/receipt` 同时传递 `"cancel"` 和交易信息。
paymentMethod	String	用于购买项目的付款选项的类型 `"Credit Card"`、`"Mobile Micro Purchase"`、`"Prepaid Card"`、`"PSMS"`、`"Carrier Billing"` 及其他。
mode	String	购买时生效的 IAP 操作模式： `"TEST"`开发者测试模式，始终返回成功或失败结果 `"PRODUCTION"` 生产模式
consumeYN	String	仅适用于消耗性应用程序内项目，无论项目是否报告为已消耗，可以再次购买： `"Y"`已消耗 `"N"` 未消耗
comsumeDate	String	消耗性项目报告为已消耗的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
consumeDeviceModel	String	将项目报告为已消耗的设备的型号名称
passThroughParam	String	您的应用程序出于安全原因而创建的交易 ID 仅当设置了直通参数时返回。注意：旧版 `iap/getPurchaseReceipt` 传递 base64 编码值，但 `iap/v6/receipt` 传递游戏中设置的值。
currencyCode	String	购买者的本地货币的货币代码（3 个字符）。（例如 EUR、GBP、USD）
currencyUnit	String	购买者的本地货币的符号（例如 €、£ 或 $）
cancelDate	String	仅适用于已取消的交易，取消购买交易的日期和时间 (YYYY-MM-DD HH:mm:ss GMT) 注意：`iap/v6/receipt` 之后添加
errorCode	String	仅适用于失败的请求，错误代码
errorMessage	String	仅适用于失败的请求，详细的错误消息

示例

成功

{
   "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": "￦"
}

失败

errorCode	errorMessage
1	“失败”
1000	有关意外系统错误的详细消息（例如，“分析错误”）
9135	“订单不存在”
9153	“参数错误（无效的 purchaseID）”

{
    "status": "fail",
    "errorCode": 9135,
    "errorMessage": "not exist order"
 }

取消的购买交易

{
    "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"
}

创建服务令牌

createServiceToken 生成并返回访问令牌值，您的服务器必须使用该令牌值来对 getSubscriptionStatus SOAP 请求进行身份验证。每个令牌的有效期为 30 天。

Note如果令牌在处理 SOAP API 请求期间过期，您的服务器必须获取新令牌，并重新提交 SOAP API 请求。

请求

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>

参数

参数	类型	说明
secret	String	（必需）Samsung 分配给每个卖家的唯一 ID（最高 12 个数字）您的密码是您在卖家门户中的卖家深层连接（转到您的配置文件页面并滚动到卖家信息页面表）

示例

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>

响应

Note可以添加、更改和删除响应参数。

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

参数

参数	类型	说明
output	String	您的服务令牌 ID 的值（96 个字母数字字符）

示例

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

检查订阅状态

getSubscriptionStatus 获取先前购买的所指定自动定期订阅 (ARS) 项目的订阅状态、项目信息和购买信息。

请求

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>

参数

参数	类型	说明
purchaseID	String	（必需）Samsung IAP 为订阅项目的应用程序内项目购买分配的唯一标识符
serviceToken	String	（必需）您的服务令牌 ID 的值（96 个字母数字字符），通过调用 createServiceToken 获取

示例

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>

响应

Note可以添加、更改和删除响应参数。

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

参数

参数	类型	说明
output	nested object	元素的容器
subscriptionPurchaseDate	String	项目的初次购买和付款交易的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
subscriptionEndDate	String	订阅过期的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
subscriptionType	String	订阅项目的类型始终返回以下值： `Item_Type_Auto_Recurring_Subscription`
subscriptionStatus	String	项目订阅的当前状态 `"ACTIVE"` 订阅处于最新状态并已生效。 `"CANCEL"`用户取消了订阅。请检查 subscriptionEndDate，以查看订阅期限是否已结束（已取消的项目在当前订阅期限结束前仍一直有效）。
subscriptionFirstPurchaseID	String	项目的初次购买的唯一标识符
countryCode	String	购买者位置（例如 KOR、USA）的国家/地区代码（3 个字母字符）
localCurrencyCode	String	购买者针对项目支付的本地货币（例如 EUR、GBP、USD）的货币代码（3 个字母字符）
localPrice	double	用户支付应用程序内项目价格的费用（以用户的本地货币表示）
supplyPrice	double	项目价格加上已收取税费的总金额
itemID	String	在卖家门户中注册的应用程序内项目的唯一标识符
freeTrial	String	应用程序内项目订阅当前是否处于免费试用期内： `"Y"`免费试用期 `"N"` 常规价格期限
realMode	String	对于常规购买，用户购买项目时是否进行了实际付款。 `"Y"` Samsung IAP 设置为生产模式。进行了实际付款。 `"N"`Samsung IAP 设置为测试模式。未进行实际付款。
latestOrderId	String	最近付款的标识符（19 个字母数字字符）。可以是初次付款或续订付款。订单 ID 显示在用户的续订收据中。
totalNumberOfTieredPayment	String	分层价格付款的总数
currentPaymentPlan	String	订阅所处的当前期限： - `"F"` :免费试用期 - `"R"` :常规价格期限 - `"T"` :分层（低层）价格期限
totalNumberOfRenewalPayment	String	对初次和续订订阅进行付款的总数
subscriptionFirstPaymentDate	String	初次订阅开始的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
cancelSubscriptionDate	String	停止订阅的日期和时间 (YYYY-MM-DD HH:mm:ss GMT)
cancelSubscriptionReason	String	订阅停止原因页面： `"1"`用户取消了订阅。 `"2"`系统取消了订阅（例如，已完成续订测试）。 `"3"`计费错误（例如，用户付款信息不再有效）。 `"4"`续订时项目不可供购买。 `"5"`未知错误

示例

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

错误响应

错误代码	错误消息	说明
10	MISSING_PARAMETER	缺少必需参数。
15	INVALID_PARAMETER_VALUE	参数值无效。
300	INVALID_SECRET	服务令牌无效。
301	EXPIRED_SERVICE_TOKEN	服务令牌已过期。
-1	UNKNOWN_ERROR	发生了服务器错误。

示例

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