開発者コンソール
ログイン
ログイン
開発者コンソール

定期購入型アイテム用RVS

定期購入型アイテム用RVS

Appstore請求サービス対応SDK用レシート検証サービス（RVS）を使用すると、アプリのユーザーが行った購入を検証できます。RVSの概要については、レシート検証サービスの概要を参照してください。

Appstore請求サービス対応SDK用RVSには、2つのREST APIがあります。1つは消費型アイテムと非消費型アイテムの購入を検証するもので、もう1つは定期購入型アイテムの購入を検証するものです。このページでは、定期購入型アイテムの購入に使用されるREST APIのリクエストとレスポンスについて説明します。

purchases.subscriptionsv2.get APIリクエスト

Appstore請求サービス対応SDKを通じて実行された定期購入型アイテムの購入のレシートを検証するには、purchases.subscriptionsv2.get APIを使用します。

アイテムの購入に成功すると、Appstore請求サービス対応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オペレーションのバージョン番号。このバージョン番号は、Appstore請求サービス対応SDKのバージョン番号とは関係ありません。現在のpurchases.subscriptionsv2.getのバージョン番号は「1.0」です。
shared-secret リクエストを発行した開発者を識別するための共有シークレット。共有シークレットは、開発者コンソールの [共有キー] ページ（https://developer.amazon.com/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インターフェイスを提供します。ベストプラクティスとして、RVSサーバーからJSONレスポンスを読み取るには、OkHttp（英語のみ）やApache HttpClient（英語のみ）などの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とは異なるもので、Amazonアプリストアによって提供される購入の詳細を示します。

フィールド データ型 説明
Googleのpurchases.subscriptionsv2.get APIと一致するフィールド
kind 文字列 androidpublisherサービスのSubscriptionPurchaseV2オブジェクトを表します。
lineItems List<SubscriptionPurchaseLineItem> 定期購入型アイテムの購入に関するアイテムレベルの情報。
startTime 文字列 定期購入型アイテムが付与された時刻。
subscriptionState 列挙型（SubscriptionState） 定期購入型アイテムの現在のステータス。
canceledStateContext CanceledStateContext キャンセルされた定期購入型アイテムに関する追加のコンテキスト。定期購入型アイテムの現在のsubscriptionStateがSUBSCRIPTION_STATE_EXPIREDの場合にのみ存在します。
testPurchase TestPurchase この定期購入型アイテムの購入がテスト購入かどうかを示します。
その他のフィールド
purchaseTimeMillis 文字列 エポック（1970年1月1日）からのミリ秒数として格納された購入日。purchaseTimeMillisは最初の購入日を表し、その後の更新の購入日を表すものではありません。
cancelDate 長整数 購入をキャンセルした日、または定期購入の期限が切れた日。購入がキャンセルされていない場合、このフィールドはnullになります。時間はミリ秒数で表されます。
testTransaction ブール型 この購入が、Amazonによる公開・テストプロセスの一部として実行されたものかどうかを示します。
renewalDate ブール型 定期購入型アイテムの更新が必要となる日付。エポックからのミリ秒数として格納されます。
purchaseToken 文字列 購入の一意の識別子。
term 文字列 IAPアイテムの購入期間。期間は購入日から始まります。数字と期間（Day、Week、Month、Year）で構成されます（1 Week、2 Monthsなど）。
deferredDate 長整数 現在のproductIdが新しいproductIdで置き換えられる日付。
freeTrialEndDate 長整数 定期購入が無料体験期間中であることを示します。定期購入の無料体験期間の終了日をエポック（ミリ秒）単位で提供します。定期購入が無料体験期間中でない場合、このフィールドはnullになります。
gracePeriodEndDate 長整数 定期購入が猶予期間中であることを示します。定期購入の猶予期間の終了日をエポック（ミリ秒）単位で提供します。定期購入が猶予期間中でない場合、このフィールドはnullになります。
purchaseMetadataMap Map <String, String> 常にnull。将来使用するために予約されています。
promotions List<Promotion> 定期購入型アイテムのリテンションオファーの詳細。リテンションオファーがない場合はnullになります。RVSにおけるプロモーションを参照してください。
fulfillmentDate 文字列 定期購入でアイテム付与完了が通知された日付。エポックからのミリ秒数として格納されます。定期購入のアイテム付与が確認されていない場合はnullになります。
fulfillmentResult 長整数 定期購入でのアイテム付与のステータス。有効な値は次のとおりです。
  • FULFILLED： コンテンツを提供し、ユーザーがそのコンテンツを使用しました。
  • UNAVAILABLE： ユーザーにコンテンツを提供できませんでした。
定期購入のアイテム付与が確認されていない場合はnullになります。

RVSにおけるプロモーション

前のセクションで説明したJSONレスポンスには、promotionsフィールドが含まれています。このセクションでは、このpromotionsフィールドについて詳しく説明します。ユーザーがリテンションオファーを使用して定期購入型アイテムを更新した場合、RVSから返されるレシートにはプロモーションの詳細が含まれます。リテンションオファーの設定方法については、リテンションオファーを参照してください。

プロモーションの詳細は、ユーザーがリテンションオファー割引価格で購入した場合のレシートにのみ存在します。レシートに関連付けられたプロモーションがない場合、promotionsフィールドはnullになります。プロモーションが関連付けられている場合、このフィールドには、次のフィールドから成る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

この型にはフィールドがありません。

Amazonのシステムによって開始されたキャンセルに固有の情報。

TestPurchase

この型にはフィールドがありません。

定期購入型アイテムの購入がテスト購入の場合、これは空のオブジェクト{}になります。テスト購入でない場合はnullになります。

purchases.subscriptionsv2.get APIでサポートされないフィールド

Google Play Developer APIで利用できる以下のフィールドは、Appstore請求サービス対応RVS APIではサポートされません。

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

キャンセル日と更新日

cancelDateフィールドには、定期購入型アイテムの購入が期限切れになった日付、またはAmazonカスタマーサービスが購入をキャンセルした日付が格納されます。キャンセル日は、ユーザーがコンテンツにアクセスできなくなった日付を表します。ユーザーが自動更新をオフにして定期購入をキャンセルした場合は、次の更新予定日がキャンセル日となります。

renewalDateフィールドには、自動更新される定期購入型アイテムの購入が次に更新される日付が格納されます。このフィールドは、定期購入型アイテムの購入にのみ適用されます。ユーザーが月額制の定期購入型アイテムを所有している場合、その定期購入型アイテムは、初回購入日と同じ日付で毎月更新されます。翌月に同じ日付がない場合は、最も近い前の日付が更新日となります。次に例を示します。

  • ユーザーが1月2日に定期購入型アイテムを購入した場合、次の3か月間の更新日は、2月2日、3月2日、4月2日になります。
  • ユーザーが1月31日に定期購入型アイテムを購入した場合、次の3か月の更新日は、2月28日（うるう年の場合は2月29日）、3月31日、4月30日になります。

renewalDateフィールドとcancelDateフィールドは、ミリ秒単位の時間として格納されます。この値を日付オブジェクトに変換するには、java.util.Date(timeInMillis)を使用します。

消費型アイテムまたは非消費型アイテムの購入

有効なレシートでは、キャンセル日と更新日はどちらもnull値になります。キャンセル日フィールドがnullでない場合、その値は、Amazonカスタマーサービスが購入をキャンセルした日付を表します。

定期購入型アイテムの購入

有効な定期購入型アイテムのレシートでは、キャンセル日はnullになります。cancelDateフィールドがnullでない場合、その値は、定期購入型アイテムが期限切れになった日付、またはAmazonカスタマーサービスが購入をキャンセルした日付を表します。

renewalDateフィールドには、自動更新される定期購入型アイテムの購入が次に更新される日付が格納されます。自動更新が設定されていない定期購入型アイテムでは、このフィールド値はnullになります。

例として、ユーザーがキャンセルした定期購入型アイテムがあるとします。

  • この定期購入型アイテムは、2023年1月1日から2023年3月1日までアクティブでした。レシートでは、この定期購入型アイテムのpurchaseDateは2023年1月1日に設定され、cancelDateは2023年3月1日に設定されます。
  • この定期購入型アイテムが2023年4月1日に再びアクティブになった場合、2つ目のレシートが生成されます。2つ目のレシートでは、purchaseDateは2023年4月1日、cancelDateはnullになります。

このページの一部は、Googleによって作成・共有されている文書を基に編集したもので、Creative Commons 4.0 Attribution Licenseに記載されている条件に従って使用しています。ソースは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年10月14日