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 发送到服务器。

参数

类型

说明

purchaseID

String

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

注意：购买 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"
}

创建服务令牌

This SOAP API will be deprecated at the end of 2024createServiceToken, along with getSubscriptionStatus, will be deprecated at the end of 2024. Use the IAP Subscription API, check status of subscription, instead.

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>

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

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

检查订阅状态

This SOAP API will be deprecated at the end of 2024Use the IAP Subscription API, check status of subscription, instead.

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.

检查订阅状态

WarningThis version of the API, which returns information in a SOAP response, will be deprecated by the end of 2024. Use the latest API, check status of subscription, which returns information in a REST response.

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>

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

参数	类型	说明
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"`未知错误

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

Samsung IAP 服务器 API

验证购买

请求

查询参数

示例

响应

参数

示例

创建服务令牌

请求

参数

示例

响应

参数

示例

检查订阅状态

检查订阅状态

请求

参数

示例

响应

参数

示例

错误响应

示例

Manage Your Cookies

Essential Cookies

Analytical/Performance Cookies

Functionality Cookies

Advertising Cookies

Preferences Submitted