开发者控制台
登录
登录
开发者控制台

适用于订阅的RVS

适用于订阅的RVS

适用于亚马逊应用商店计费兼容性SDK的收据验证服务 (RVS) 可让您验证您应用的用户进行的购买。有关RVS的概述，请参阅收据验证服务概述。

适用于亚马逊应用商店计费兼容性SDK的RVS有两个REST API，一个用于验证消费品和权利购买，另一个用于验证订阅购买。本页介绍用于订阅购买的REST API的请求和响应。

purchases.subscriptionsv2.get API请求

使用purchases.subscriptionsv2.get API来验证通过亚马逊应用商店计费兼容性SDK进行的订阅购买的收据。

成功购买商品后，亚马逊应用商店计费兼容性SDK会返回Purchase对象。要对购买进行服务器端验证，请从该对象中提取购买令牌并将其连同应用程序包名称和共享密钥一起传递至RVS服务器。出于安全考虑，当您从服务器发出请求时，必须传递共享密钥以确认您的身份。

请求使用以下格式：

https://appstore-sdk.amazon.com/version/{operation-version-number}/developer/{shared-secret}/applications/{package-name}/purchases/subscriptionsv2/tokens/{token}

花括号包含请求参数的占位符。在您的请求中，将占位符替换为要验证的交易的值。下表列出了请求参数的描述。

请求参数 描述
operation-version-number purchases.subscriptionsv2.get操作的版本号。此版本号独立于亚马逊应用商店计费兼容性SDK版本号。当前purchases.subscriptionsv2.get版本号为“1.0”。
shared-secret 用于标识发出请求的开发者的共享密钥。可在开发者控制台共享密钥页面上找到共享密钥：https://developer.amazon.com/zh/sdk/shared-key.html。
package-name 用于销售应用内产品的应用程序的程序包名称。例如“com.amazon.sample.iap.consumable”。您可以通过调用getApplicationContext().getPackageName()从您的应用中获取程序包名称，也可以在AndroidManifest.xml文件中找到它。
token 从Purchase对象的getPurchaseToken()方法中获得的购买的唯一ID。

purchases.subscriptionsv2.get API响应

purchases.subscriptionsv2.get API提供了一个RESTful JSON API接口。作为最佳实践，使用JSON解析器类（例如OkHttp或Apache HttpClient）从RVS服务器读取JSON响应。

向RVS服务器发出验证交易的请求后，RVS服务器会返回响应代码来指示请求是否成功。如果成功，则返回的JSON响应包括有关交易的信息。

下例展示了一个成功响应：

{
    "cancelDate": 1638906732000,
    "canceledStateContext": {
        "developerInitiatedCancellation": null,
        "replacementCancellation": null,
        "systemInitiatedCancellation": {},
        "userInitiatedCancellation": null
    },
    "deferredDate": null,
    "freeTrialEndDate": null,
    "fulfillmentDate": null,
    "fulfillmentResult": null,
    "gracePeriodEndDate": null,
    "kind": "androidpublisher#subscriptionPurchaseV2",
    "lineItems": [
        {
            "autoRenewingPlan": {
                "autoRenewEnabled": true
            },
            "deferredItemReplacement": null,
            "expiryTime": "1638906732000",
            "offerDetails": {
                "basePlanId": "amzn1.appstore.iap.compatibility.baseplan.termsku.pom.subscription.weekly",
                "offerId": "amzn1.appstore.iap.compatibility.offer.termsku.pom.subscription.weekly"
            },
            "productId": "pom.subscription"
        }
    ],
    "promotions": null,
    "purchaseTimeMillis": "1638465681000",
    "purchaseToken": "s_gaorSDP-W8R0xucVkDIcR5gQuHrqX37cn8MzQoOHo=:3:14",
    "renewalDate": null,
    "startTime": "Tue Dec 07 17:21:21 UTC 2021",
    "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
    "term": "1 Day",
    "testPurchase": null,
    "testTransaction": false
}

响应代码和错误消息

收据验证服务会使用以下代码之一进行响应，这些代码可以指示验证检查的结果。

HTTP响应代码 描述
200 此次购买有效。
400 购买令牌无效。
401 开发者密钥无效或与给定的购买令牌不匹配。
404 程序包名称无效或与给定的购买令牌不匹配。
410 此receiptId表示的交易不再有效。请将其作为已取消的收据。
429 该请求已被限制节流。请降低您的调用速率并稍后重试。
500 出现内部服务器错误。

成功交易的响应字段

下表描述了成功交易的purchases.subscriptionsv2.get响应中包含的字段。有些字段的名称和数据类型与Google的purchases.subscriptionsv2.get API相同。这些字段列在与Google的purchases.subscriptionsv2.get API相匹配的字段下。其他字段下列出的字段与Google API不同，它们显示了亚马逊应用商店提供的购买详情。

字段 数据类型 描述
与Google的purchases.subscriptionsv2.get API相匹配的字段
kind 字符串 表示androidpublisher服务中的SubscriptionPurchaseV2对象。
lineItems List<SubscriptionPurchaseLineItem> 订阅购买的商品级别信息。
startTime 字符串 授予订阅的时间。
subscriptionState Enum (SubscriptionState) 订阅的当前状态。
canceledStateContext CanceledStateContext 有关取消的订阅的其他上下文信息。仅当订阅当前的subscriptionState为SUBSCRIPTION_STATE_EXPIRED时才存在。
testPurchase TestPurchase 指明此订阅购买是否为测试购买。
其他字段
purchaseTimeMillis 字符串 购买日期，以纪元（1970年1月1日）以后的毫秒数存储。purchaseTimeMillis代表初始购买日期，而不是后续续订的购买日期。
cancelDate 长整数 取消购买的日期，或订阅到期的日期。如果购买未取消，则此字段为null。时间以毫秒为单位。
testTransaction 布尔值 表明此购买是否作为亚马逊发布和测试过程的一部分进行。
renewalDate 布尔值 需要续订订阅购买的日期。日期以纪元以后的毫秒数存储。
purchaseToken 字符串 购买的唯一标识符。
term 字符串 IAP商品的订阅期持续时间。该期限从购买之日开始。期限由数字和时间段（天、周、月、年）构成，如1周或2个月。
deferredDate 长整数 将当前productId替换为新productId的日期。
freeTrialEndDate 长整数 表示订阅处于免费试用期内。提供订阅免费试用的结束日期，以epoch（毫秒）为单位。如果订阅不在免费试用期内，则此字段为null。
gracePeriodEndDate 长整数 表示订阅处于宽限期内。提供订阅宽限期的结束日期，以epoch（毫秒）为单位。如果订阅不在宽限期内，则此字段为null。
purchaseMetadataMap [映射] <字符串，字符串> 始终为null。预留以供将来使用。
promotions [列表] <促销> 订阅购买的留存优惠的详细信息。如果没有留存优惠，则为null。请参阅RVS中的促销。
fulfillmentDate 字符串 在订阅购买中，为确认履行的日期。以纪元以后的毫秒数存储。如果未确认订阅履行，则为null。
fulfillmentResult 长整数 在订阅购买中，履行的状态。有效值：
  • FULFILLED： 您提供了内容，并且客户使用了内容。
  • UNAVAILABLE： 您无法向客户提供内容。
如果未确认订阅履行，则为null。

RVS中的促销

上一节所述的JSON响应包含一个promotions（促销）字段。本节将更详细地介绍promotions字段。如果客户以留存优惠折扣续订订阅，则通过RVS返回的收据包括促销详情。有关如何设置留存优惠的详细信息，请参阅留存优惠。

促销详情仅显示在与客户以留存优惠折扣进行的购买相对应的收据上。如果没有与收据相关联的促销，则promotions字段为空。否则，该字段将包含Promotion（促销）对象列表，其中包含以下字段。

字段 数据类型 描述
promotionType 字符串 促销类型。有效值：
Retention Offer
promotionStatus 字符串 该客户的促销状态。有效值：
InProgress - 客户目前正在享受留存优惠。

示例：

"promotions": [
    {
        "promotionType":"Retention Offer",
        "promotionStatus":"InProgress"
    }
]

数据类型

以下部分描述了您在purchases.subscriptionsv2.get响应中可能遇到的数据类型。

SubscriptionPurchaseLineItem

订阅购买的商品级别信息。

字段 数据类型 描述
productId 字符串 所购买产品的产品ID。
expiryTime 字符串 除非延长访问权限（续订订阅），否则订阅到期或将要到期的时间。
autoRenewingPlan AutoRenewingPlan 该商品自动续订。
offerDetails OfferDetails 此商品的优惠详情。
deferredItemReplacement DeferredItemReplacement 始终为null。预留以供将来使用。

AutoRenewingPlan

与自动续订计划相关的信息。

字段 数据类型 描述
autoRenewEnabled 布尔值 表示客户的订阅是否会自动续订。

OfferDetails

与购买单项商品相关的优惠详情。

字段 数据类型 描述
basePlanId 字符串 基本计划ID。对所有基本计划和优惠存在。
offerId 字符串 优惠ID。仅对折扣优惠存在。

SubscriptionState

表示订阅的当前状态。例如，订阅是有效还是已过期。

枚举 描述
SUBSCRIPTION_STATE_UNSPECIFIED 未指定的订阅状态
SUBSCRIPTION_STATE_ACTIVE 订阅已激活
SUBSCRIPTION_STATE_IN_GRACE_PERIOD 订阅处于宽限期
SUBSCRIPTION_STATE_EXPIRED 订阅已过期

CanceledStateContext

特定于处于取消状态的订阅的信息。

字段 数据类型 描述
userInitiatedCancellation UserInitiatedCancellation 用户取消了订阅。
systemInitiatedCancellation SystemInitiatedCancellation 例如，由于计费问题，系统取消了订阅。
developerInitiatedCancellation DeveloperInitiatedCancellation 始终为null。预留以供将来使用。
replacementCancellation ReplacementCancellation 始终为null。预留以供将来使用。

UserInitiatedCancellation

特定于用户发起的取消的信息。

字段 数据类型 描述
cancelTime 字符串 用户取消订阅的时间。

SystemInitiatedCancellation

此类型没有字段。

特定于亚马逊系统发起的取消的信息。

TestPurchase

此类型没有字段。

如果订阅购买是测试购买，则此项显示为空对象{}。如果不是测试购买，则为Null。

purchases.subscriptionsv2.get API不支持的字段

亚马逊应用商店计费兼容性RVS API在响应中不支持Google Play开发者API提供的以下字段。

  • regionCode
  • lineItems[].autoRenewingPlan.priceChangeDetails
  • lineItems[].prepaidPlan
  • lineItems[].offerDetails.offerTags
  • latestOrderId
  • linkedPurchaseToken
  • pausedStateContext
  • canceledStateContext.userInitiatedCancellation.cancelSurveyResult
  • acknowledgementState
  • externalAccountIdentifiers
  • subscribeWithGoogleInfo

取消日期和续订日期

cancelDate字段包含订阅购买到期的日期或亚马逊客户服务取消购买的日期。取消日期表示客户失去相应内容访问权限的日期。如果客户通过关闭自动续订来取消其订阅，则取消日期是之前原定的续订日期。

renewalDate字段包含自动续订订阅购买下一次需要续订的日期。此字段仅适用于订阅购买。如果客户按月订阅，则订阅会每月在与客户首次订阅相同的日期续订。如果下个月不包括该确切日期，则预订日期为距其最近的前一个日期。例如：

  • 如果客户在1月2日订阅，则接下来的三个续订日期为2月2日、3月2日和4月2日。
  • 如果客户在1月31日订阅，接下来的三个续订日期为2月28日（如果是闰年，则为2月29日）、3月31日和4月30日。

renewalDate和cancelDate字段以毫秒为单位存储。可以使用java.util.Date(timeInMillis) 将值转换为日期对象。

消费品或权利购买

在有效的收据中，取消日期和续订日期都包含null值。如果取消日期字段不为null，则会包含亚马逊客户服务取消购买的日期。

订阅购买

在有效的订阅收据中，取消日期为null。如果cancelDate字段不为null，则会包含订阅到期的日期或亚马逊客户服务取消购买的日期。

renewalDate字段包含自动续订订阅购买下一次需要续订的日期。如果订阅未设置为自动续订，则字段值为null。

在以下示例中，用户拥有已取消的订阅：

  • 订阅的有效期为2023年1月1日至2023年3月1日。在此收据中，此订阅的purchaseDate设置为2023年1月1日，cancelDate设置为2023年3月3日。
  • 如果此订阅后来于2023年4月1日重新激活，则订阅会有第二个收据。第二个收据会显示purchaseDate为2023年4月1日，cancelDate为null。

本页面的部分内容基于Google创建和共享的作品进行了修改，并且在使用相应内容时依照知识共享署名4.0许可中所述的条款。资料来源：https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2/get、https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2。

Last updated: 2024年6月17日