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
响应
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 |
元素的容器 |
subscription |
String | 项目的初次购买和付款交易的日期和时间 (YYYY-MM-DD HH:mm:ss GMT) |
subscription |
String | 订阅过期的日期和时间 (YYYY-MM-DD HH:mm:ss GMT) |
subscriptionType | String | 订阅项目的类型 始终返回以下值: Item_Type_Auto_Recurring_Subscription
|
subscriptionStatus | String | 项目订阅的当前状态"ACTIVE" 订阅处于最新状态并已生效。"CANCEL" 用户取消了订阅。请检查 subscriptionEndDate,以查看订阅期限是否已结束(已取消的项目在当前订阅期限结束前仍一直有效)。
|
subscription |
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 显示在用户的续订收据中。 |
totalNumberOf |
String | 分层价格付款的总数 |
currentPaymentPlan | String | 订阅所处的当前期限: - "F" :免费试用期- "R" :常规价格期限- "T" :分层(低层)价格期限
|
totalNumberOf |
String | 对初次和续订订阅进行付款的总数 |
subscription |
String | 初次订阅开始的日期和时间 (YYYY-MM-DD HH:mm:ss GMT) |
cancelSubscription |
String | 停止订阅的日期和时间 (YYYY-MM-DD HH:mm:ss GMT) |
cancelSubscription |
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>