Google Play Developer API に、代替の課金システムまたは外部オファー システムから取引を報告する機能が追加されました。このガイドでは、代替の課金システムまたは外部オファーの取引を報告する方法について説明します。
バックエンドからのアプリ内購入を処理するために必要なコンポーネントがいくつかあります。それらをビルドするには、Google Play Developer API を設定するの手順に沿ってバックエンド統合をセットアップする必要があります。代替の課金システムや外部オファーの API 専用ではない、デベロッパーのバックエンド機能については、Google Play 課金システムのドキュメントに記載の手順が適用されます。
新しい外部取引を Google Play に報告する
Externaltransactions APIs と統合して、サポートされている国の Google Play の課金システム以外で行われる取引を報告します（無料トライアルでの購入による 0 ドルの取引を含む）。代替の課金システムまたは外部オファーのシステムでの取引は、代替の課金システムまたは外部オファー プログラムで許可されているユーザーの国でのみ開始し、報告する必要があります。それ以外の場合、API 呼び出しは拒否されます。これは、新規購入、更新、チャージ、アップグレード、ダウングレードなど、すべての取引に適用されます。
外部取引の報告
代替の課金システムまたは外部オファー システムで支払いが承認された後、Externaltransactions API を呼び出して外部取引を報告する必要があります。これは、初回の請求、更新、払い戻しなどを含むすべての取引に適用されます。すべての取引は、トランザクションが発生してから 24 時間以内に報告する必要があります。
各外部取引は、外部取引 ID とともに報告されます。定期的な購入（自動更新可能な定期購入など）については、払い戻しを含め、後続の取引のパラメータとして、定期的な購入の最初の取引に関連付けられている外部取引 ID を送信する必要があります。これにより、その購入の一連の取引が記録されます。商品が変更されたとき（アップグレードやダウングレードなど）、または定期的な取引がキャンセルまたは期限切れになり同じ商品が後で再度購入されたときは、購入の新しい外部取引 ID を送信します。この外部取引 ID に個人情報、専有情報、機密情報を含めないでください。
新規購入を報告する
代替の課金システムまたは外部オファーのシステムで新規購入が成功するたびに、Externaltransactions API を呼び出す必要があります。新たに購入する場合は、バックエンドでの購入に関連付けられている一意の
externalTransactionId をクエリ パラメータとして指定する必要があります。この externalTransactionId は、同じアプリのパッケージ ID 内で再利用できません。
UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener、または ExternalOfferReportingDetailsListener のコールバックを通じてアプリが受け取る externalTransactionToken は、1 回だけの購入と定期的な購入（定期購入など）の初回取引のリクエスト本文の一部としても必要です。いずれの場合も、このトランザクションは初期トランザクションと呼ばれます。最初の取引の後は、externalTransactionToken は不要になるため、新しい一意の externalTransactionId を指定して後続の取引（定期購入の更新など）を報告します。後続の取引を報告する方法の詳細については、購入の後続の取引を報告するをご覧ください。
例:
- デベロッパーがアプリで代替の課金システムを設定して有効にします。
- サポートされている国である韓国のユーザー 1 が、
product1を月額 12,634.10 韓国ウォンで、1 か月間の無料トライアル特典付きで購入しようとしています。 - アプリは
product1のProductDetailsとユーザーが選択した特典の購入フローを開始します。 - ユーザー 1 がデベロッパーの代替の課金システムを選択します。
UserChoiceBillingListenerが値my_tokenをexternalTransactionTokenとして受け取ります。- 次に、デベロッパーがバックエンドに関連情報を送信します（
externalTransactionToken値と購入する商品）。さらに、代替の課金システムでproduct1の購入フローを開始します。この取引に、Google Play への報告に使用されるデベロッパー側での一意の取引 ID（123-456-789）が割り当てられます。ユーザーが無料トライアルを受け取る場合でも、取引 ID は必須です。 - 購入の取引が代替の課金システムで行われた後、デベロッパーが以下のリクエストで Google Play に取引を報告します。ユーザーは 1 か月無料で利用できるため、最初は 0 ドルの取引として報告されます。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
インド在住のユーザーとの取引で、行政区域（州や県など）によって税額が異なる場合は、その地域を必ず userTaxAddress に含めてください。該当する行政区域については、API リファレンス ガイドで事前定義されている文字列のリストをご覧ください。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"transactionTime" : "2023-11-01T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
# Tax varies in India based on state, so include that information in
# administrativeArea
"regionCode": "IN"
"administrativeArea": "KERALA"
}
}
購入に対する後続の取引を報告する
同じ外部購入に複数のユーザー支払いが関連付けられていることがあります（定期購入の更新や前払いプランのチャージなど）。後続の取引は Externaltransactions の同じ API を使用して報告できます。新規購入の報告で説明したように、後続の取引で externalTransactionToken は必要ありません。代わりに、更新またはチャージの取引ごとに、新しい一意の externalTransactionId がクエリ パラメータとして送信されます（initialExternalTransactionId フィールドに初期取引の ID を指定します）。
上記の例では、次のようになります。
- ユーザー 1 の初回の更新が代替の課金システムで行われます。最初の取引 ID は 123-456-789 でした。
- デベロッパーは、URL のクエリ パラメータで、その回の取引を新しい取引の外部取引 ID として報告し、
initialExternalTransactionIdフィールドの初期取引の外部取引 ID を参照します。
リクエスト例:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
"originalPreTaxAmount" : {
"priceMicros": "12634000000",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "1263000000",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId": "123-456-789",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
アップグレードまたはダウングレードを報告する
ユーザーが代替の課金システムで定期購入を所有しているときにアップグレードまたはダウングレードを報告するには、Externaltransactions API の同じエンドポイントと関数を使用し、アップグレード取引またはダウングレード取引に関してアプリに提供された externalTransactionToken を送信します。これは、新規購入の報告と同様に機能します。
代替の課金システムの取引の手動レポートから移行する
自動レポートを使用しない代替の課金システムの提供中に開始され、現在も有効な定期購入を移行するには、initialExternalTransactionId または externalTransactionToken を指定する代わりに、migratedTransactionProgram フィールドを使用して新しく費用がゼロの取引を作成します。transactionTime は、ユーザーが有効な定期購入ごとに最初に登録した時刻に設定します。その後、前述の更新取引の作成に使用した initialExternalTransactionId を指定して、これらの定期購入についてその後の取引を通常どおり API を使用して報告します。定期購入を移行した後、このページで説明する自動化された方法で報告されるようにすると、定期購入についてその後の取引を手動で報告する必要はなくなります。
定期購入を移行するときは、移行によって割り当てが停止しないように、割り当ての上限に注意してください。多くの定期購入を移行する必要がある場合は、複数の日に分散するか、割り当ての増加をリクエストしてください。
migratedTransactionProgram フィールドは、手動レポートから移行する場合にのみ使用できます。手動レポートのサポートが終了すると、このフィールドのサポートも終了します。
リクエスト例:
# Note that the externalTransactionId specified here will used to report subsequent
# transactions.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
# Be sure to set the price to 0 for this transaction since it does not reflect
# an actual subscription renewal.
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
# The transaction time should be set to when the user signed up for this
# subscription.
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"migratedTransactionProgram": "USER_CHOICE_BILLING",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
購入の払い戻しを Google Play に報告する
Externaltransactions API を統合して、Google Play の課金システム以外のユーザーに払い戻しが行われた取引を報告します。払い戻しが行われた取引を Play が正しく識別するには、以前に報告された取引に対応する externalTransactionId を URL パラメータの一部として含める必要があります。
定期購入の払い戻しを報告する場合は、払い戻しされる定期購入の特定の回の externalTransactionId を参照してください。
例: 定期購入に次の取引があるとします。
- 外部取引 ID が ABC.1234-5678-9012-34567 の初期取引
- 外部取引 ID が ABC.1234-5678-9012-34567..0 の 1 回目の取引
- 外部取引 ID が ABC.1234-5678-9012-34567..1 の 2 回目の取引
定期購入のすべての取引の払い戻しを報告するには、3 つの別々の払い戻しリクエスト（初期取引に 1 件、後続の取引に 2 件）を行う必要があります。
このメソッドは、全額払い戻し（ユーザーが元の外部取引で支払った金額と同じ金額）と一部払い戻し（ユーザーが元の外部取引で支払った金額よりも少ない金額）の両方を受け付けます。一部払い戻しの場合は、払い戻された税額を指定する必要があります。
API 割り当て
Google Play Developer API の他のエンドポイントと同様に、Externaltransactions API ではすべての呼び出しに 1 日あたりの API 割り当てが適用されます。
また、Externaltransactions API には、Externaltransactions.createexternaltransaction または Externaltransactions.refundexternaltransaction の呼び出しに 1,200 QPM（Queries Per Minute: 1 分あたりのクエリ数）の上限が適用されます。Externaltransactions.getexternaltransaction の呼び出しは、この 1,200 QPM の上限にはカウントされません。