en zh

Samsung IAP 服务器 API

验证购买

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

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

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

请求

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

查询参数

参数

 类型

 说明
purchaseID

 String

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

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

示例

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

响应


参数

参数

 类型

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

 将项目报告为已消耗的设备的型号名称
acknowledgeYN

 String

 Whether or not acknowledge that the user has been granted entitlement for the purchased non-consumable item or subscription:
"Y" Acknowledged
"N" Not Acknowledged
acknowledgeDate

 String

 Date and time when the purchase of non-consumable item or subscription was acknowledged
(YYYY-MM-DD HH:mm:ss GMT)
acknowledgeDeviceModel

 String

 Model name of the device that acknowledged non-consumable item or subscription
passThroughParam

 String

 自 IAP 6.4.0 起已弃用
您的应用程序出于安全原因而创建的交易 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",
   "acknowledgeYN": "Y",
   "acknowledgeDate": "2025-03-20 06:58:06",
   "acknowledgeDeviceModel": "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",
    "acknowledgeYN": "Y",
    "acknowledgeDate": "2025-03-20 06:58:06",
    "acknowledgeDeviceModel": "SM-N960N",
    "passThroughParam": "TEST_PASS_THROUGH",
    "currencyCode": "KRW",
    "currencyUnit": "￦",
    "status": "cancel",
    "cancelDate": "2019-11-29 00:01:52"
}

创建服务令牌

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

请求

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>

响应

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

检查订阅状态

Gets the subscription status, including item information and purchase information, which can be used to verify the purchase of an item.

This call requires the purchase ID of the subscription item and a service token for authentication and checks the user’s subscription information on the server.

Information is returned in a REST response. This API only provides meaningful information after a subscription is purchased.

Subscription-related content includes the purchase date, current subscription status, current price, current subscription pricing option, number of renewals, paid subscription start date, subscription end date, and reason for cancellation.

Before you can start using the IAP Subscription API, you must meet all requirements and use the required authorization header parameters in your requests. See Get Started with the IAP APIs for more information.

See Check status of subscription for more information about this IAP Subscription API.

检查订阅状态

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>

响应

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