Appstore SDK IAP用レシート検証サービス
Amazonアプリ内課金（IAP）用レシート検証サービス（RVS）では、アプリのユーザーによる購入を検証できます。RVSの概要については、レシート検証サービスの概要を参照してください。
RVSのセットアップ
RVSには、アプリが開発／テスト段階にあるか、Amazonアプリストアで公開されているかに応じて、2つの環境オプションが用意されています。
- RVS Cloud Sandbox： アプリの開発中およびテスト中は、RVS Sandbox環境を使用して、App Testerテストツールで生成されたレシートを検証します。RVS Cloud Sandboxをセットアップするには、RVS Cloud Sandboxの使用を参照してください。
- RVS本番サーバー： アプリをAmazonアプリストアに公開した後は、Amazon RVS本番サーバーを使用できます。Appstore SDK IAP用RVS本番環境のセットアップを参照してください。
RVSリクエストの構文
RVSは、PurchaseResponseオブジェクト（英語のみ）またはPurchaseUpdatesResponseオブジェクト（英語のみ）を検証するために使用します。これらのレスポンスオブジェクトから、ユーザーを一意に識別するユーザーIDを抽出できます。PurchaseResponseオブジェクトにはReceiptIdが含まれています。これをユーザーIDと共に使用して、サーバー側で購入の検証を実行します。アプリサーバーから送信するリクエストには、共有シークレットを渡す必要があります。これによって身元確認が行われ、セキュリティが確保されます。
リクエストの形式は次のとおりです。
{protocol}//{server}[/{sandbox}]/version/{operation-version-number}/verifyReceiptId/developer/{shared-secret}/user/{user-id}/receiptId/{receipt-id}
中かっこに囲まれているのはプレースホルダーとリクエストパラメーターです。検証対象のトランザクションに応じた値に置き換えてください。次の表は、必須パラメーターの説明をまとめたものです。
| パラメーター | 説明 |
|---|---|
| protocol | サーバーまたはRVS Sandboxとの通信に使用するプロトコル（httpsなど）。 |
| server | 通信相手となるRVSサーバーのURL。RVS Cloud SandboxサーバーとRVS本番サーバーはどちらも「appstore-sdk.amazon.com」というURLを使用します。 |
| sandbox | RVS Cloud Sandboxサーバーを使用している場合は、「sandbox」という値を使用します。RVS本番サーバーを使用している場合は、このパラメーターを省略します。 |
| operation-version-number | verifyReceiptIdオペレーションのバージョン番号。このバージョン番号は、IAPのバージョン番号とは関係ありません。現在のverifyReceiptIdバージョン番号は「1.0」です。 |
| shared-secret | リクエストを発行した開発者を識別するための共有シークレット。共有シークレットは、開発者コンソールの [共有キー] ページ（https://developer.amazon.com/sdk/shared-key.html）で確認できます。RVS Cloud Sandboxの場合は、空でない任意の文字列を共有シークレットとして使用できます。 |
| user-id | Amazonアプリストアで公開したアプリを使用する個々のAmazonユーザーを表すID。ユーザーIDは、PurchaseResponse.getUserData().getUserId()から取得します。 |
| receipt-id | 購入のグローバルに一意のID。レシートIDは、PurchaseResponse.getReceipt().getReceiptId()またはPurchaseUpdatesResponse.getReceipts() → Receipt.getReceiptId()から取得します。 |
RVSレスポンスの構文
RVSは、RESTfulなJSON APIインターフェイスを提供します。ベストプラクティスとして、RVSサーバーから返されたJSONレスポンスを読み取るには、JSONパーサークラスを使用することをお勧めします。
トランザクションの検証をリクエストすると、RVSサーバーまたはRVS Sandboxから、リクエストが成功したかどうかを示すレスポンスコードが返されます。成功した場合、JSONレスポンスにはトランザクションに関する情報が含まれています。
以下は、リクエストに成功した場合のレスポンスの例です。
{
"autoRenewing":false,
"betaProduct":false,
"cancelDate":null,
"cancelReason":null,
"freeTrialEndDate":null,
"fulfillmentDate":null,
"fulfillmentResult":null,
"gracePeriodEndDate":null,
"parentProductId":null,
"productId":"com.amazon.iapsamplev2.gold_medal",
"productType":"CONSUMABLE",
"promotions":null,
"purchaseDate":1399070221749,
"purchaseMetadataMap":null,
"quantity":1,
"receiptId":"wE1EG1gsEZI9q9UnI5YoZ2OxeoVKPdR5bvPMqyKQq5Y=:1:11",
"renewalDate":null,
"term":null,
"termSku":null,
"testTransaction":true
}
RVSのレスポンスコード
レシート検証サービスは、応答として次のいずれかのコードを返します。各コードは、検証チェックの結果を示しています。
| レスポンスコード | 説明 |
|---|---|
| HTTP 200 | 成功しました。 レシートID、ユーザーID、共有シークレットがすべて有効です。商品タイプは次のいずれかです。 ENTITLED（非消費型アイテム）、CONSUMABLE（消費型アイテム）、SUBSCRIPTION（定期購入型アイテム） |
| HTTP 400 | このreceiptIdで表されるトランザクションが無効です。または、このreceiptIdに対応するトランザクションが見つかりませんでした。 |
| HTTP 410 | このreceiptIdで表されるトランザクションは無効になりました。キャンセルされたレシートとして処理してください。 |
| HTTP 429 | リクエストがスロットリングされました。呼び出しの頻度を減らして、しばらくしてから再試行してください。 |
| HTTP 496 | 共有シークレットが無効です。 |
| HTTP 497 | ユーザーIDが無効です。 |
| HTTP 500 | 内部サーバーエラーが発生しました。 |
成功したトランザクションのRVSレスポンスフィールド
次の表は、成功したトランザクションのRVSレスポンスに含まれるフィールドとその説明をまとめたものです。
| フィールド | データ型 | 説明 |
|---|---|---|
autoRenewing |
ブール型 | ユーザーの定期購入が自動更新されるかどうかを示します。 |
betaProduct |
ブール型 | 購入商品がライブアプリテスト商品かどうかを示します。 |
cancelDate |
長整数 | 購入をキャンセルした日、または定期購入の期限が切れた日。購入がキャンセルされていない場合、このフィールドはnullになります。時間はミリ秒単位です。 |
cancelReason |
整数 | 商品がキャンセルされた理由を示します。有効な値は、null、0、1、2のいずれかです。それぞれの整数はキャンセルの理由を表します。 null - 購入がキャンセルされていない。0 - 現時点ではキャンセル理由が特定されていないため、後で表示される。1 - ユーザーが注文をキャンセルした。2 - 購入がAmazonのシステムによってキャンセルされた（定期購入型アイテム購入時のユーザーの支払いが無効で、その購入が猶予期間内に完了しなかった場合など）。このコードは、Amazonカスタマーサポートがユーザーのリクエストに応じて注文をキャンセルした場合にも返されます。 |
freeTrialEndDate |
長整数 | 定期購入が無料体験期間中であることを示します。定期購入の無料体験期間の終了日をエポック（ミリ秒）単位で提供します。定期購入が無料体験期間中でない場合、このフィールドはnullになります。 |
fulfillmentDate |
長整数 | 定期購入でアイテム付与完了が通知された日付。エポックからのミリ秒数として格納されます。定期購入のアイテム付与が確認されていない場合はnullになります。消費型アイテムと非消費型アイテムでは常にnullです。 |
fulfillmentResult |
文字列 | 定期購入でのアイテム付与のステータス。有効な値は次のとおりです。
|
gracePeriodEndDate |
長整数 | 定期購入が猶予期間中であることを示します。定期購入の猶予期間の終了日をエポック（ミリ秒）単位で提供します。定期購入が猶予期間中でない場合、このフィールドはnullになります。 |
parentProductId |
文字列 | null。将来使用するために予約されています。 |
productId |
文字列 | アプリ内でこのアイテムに対して定義したSKU。 |
productType |
文字列 | 購入された商品のタイプ。有効な商品タイプは、CONSUMABLE（消費型アイテム）、SUBSCRIPTION（定期購入型アイテム）、ENTITLED（非消費型アイテム）です。 |
promotions |
リスト<Promotion> | 定期購入型アイテムのプロモーション価格またはリテンションオファーの詳細。プロモーションがない場合はnullになります。RVSのプロモーションを参照してください。 |
purchaseDate |
長整数 | 購入日。エポックからのミリ秒数として格納されます。定期購入型アイテムの場合、purchaseDateは最初の購入日を表します。それ以降の更新日を表すものではありません。 |
purchaseMetadataMap |
[マップ] <文字列, 文字列> | 購入がクイック定期購入を通じて開始された場合、値は{"QuickSubscribe":true}になります。それ以外の場合はnullになります。 |
quantity |
整数 | 購入された数量。常にnullまたは1になります。 |
receiptId |
文字列 | 購入のグローバルに一意の識別子。 |
renewalDate |
長整数 | 定期購入型アイテムの更新が必要となる日付。エポックからのミリ秒で計算されます。 |
term |
文字列 | 定期購入型IAPアイテムの有効期間（期間は購入日から始まります）。数字と期間（日、週、月、年）で構成されます（「1週間」、「2か月」など）。 |
termSku |
文字列 | 定期購入期間に対応する一意のSKU。 |
testTransaction |
ブール型 | この購入が、Amazonによる公開・テストプロセスの一部として実行されたものかどうかを示します。 |
RVSのプロモーション
プロモーション価格を設定する方法の詳細については、プロモーション価格の設定を参照してください。リテンションオファーの設定方法については、リテンションオファーを参照してください。ユーザーが定期購入型アイテムをプロモーション価格で購入した場合、またはリテンションオファーを使用して定期購入型アイテムを更新した場合、RVSから返されるレシートにはプロモーションの詳細が含まれます。前のセクションで説明したJSONレスポンスには、promotionsフィールドが含まれています。このセクションでは、このpromotionsフィールドについて詳しく説明します。ユーザーが定期購入型アイテムをプロモーション価格またはリテンションオファー割引価格で購入した場合のみ、そのレシートにプロモーションの詳細が表示されます。
レシートに関連付けられたプロモーションがない場合、promotionsフィールドはnullになります。プロモーションが関連付けられている場合は、このフィールドにPromotionオブジェクトのリストが含まれ、次のフィールドも表示されます。
| フィールド | データ型 | 説明 |
|---|---|---|
promotionType |
文字列 | プロモーションのタイプ。有効な値は次のとおりです。
|
promotionStatus |
文字列 | このユーザーのプロモーションのステータス。有効な値は次のとおりです。
|
以下に例を示します。
"promotions": [
{
"promotionType":"Introductory Price - All Customers",
"promotionStatus":"Completed"
}
]
有効な値の説明
promotionTypeフィールドで有効な値は次のとおりです。
Introductory Price - All Customers- すべてのユーザー（新規ユーザーおよび休眠ユーザーを含む）に提供される価格。Promotional Price - Lapsed Customers- 休眠ユーザーにのみ提供される価格。Retention Offer- 対象ユーザーが定期購入をキャンセルしようとしている場合に提供される価格。
promotionStatusフィールドで有効な値は次のとおりです。
Queued- ユーザーが定期購入型アイテムをプロモーション価格で購入しました。現在は無料体験期間であり、まだプロモーション期間は始まっていません。このフィールドはリテンションオファーには適用されません。InProgress- ユーザーは現在、プロモーション価格またはリテンションオファーを利用しています。Completed- ユーザーのプロモーション価格の適用期間が終了しました。このフィールドはリテンションオファーには適用されません。
プロモーションに関するよくある質問（FAQ）
RVSでのプロモーション価格に関するよくある質問（FAQ）を以下に示します。
- Q： ユーザーの定期購入型アイテムのレシートには必ずプロモーションの詳細が表示されているのですか？
- いいえ。プロモーションの詳細は、定期購入型アイテムをプロモーション価格で購入したレシートにのみ表示されます。
- Q： プロモーションの詳細は、レシートがキャンセルされた後も表示されますか？
- はい。プロモーション価格を提示されたユーザーが定期購入をキャンセルした場合、プロモーションの詳細が
Completedと表示されます。ただし、ユーザーがリテンションオファーを利用した後、定期購入を通常価格で更新した場合、レシートにはプロモーションの詳細が表示されません。 - Q： プロモーション価格について、ユーザーが無料体験中に定期購入型アイテムをキャンセルし、プロモーションプランを更新しなかった場合、プロモーションのステータスはどうなりますか？
- ユーザーのプロモーション期間が開始しなかったため、レシートには関連付けられているプロモーションの詳細がありません。
キャンセル日と更新日
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になります。
RVS SandboxとRVS本番環境の例
Appstore SDK IAP用RVSの例を参照してください。
Last updated: 2024年6月12日