Google Play 請求サービス以外での収益化に関するバックエンド統合のガイダンス

Google Play Developer API に、課金プログラムとリンク プログラムから 取引を報告する機能が追加されました。このガイドでは、これらの課金プログラムから取引を報告する方法について説明します。

バックエンドからの外部取引を処理するために必要なコンポーネントがいくつかあります。それらをビルドするには、Google Play Developer API を設定するの手順に沿ってバックエンド 統合をセットアップする必要があります。課金プログラムとリンク プログラムに固有ではないデベロッパーのバックエンド機能をビルドするには、Google Play の課金システムをご覧ください。

用語集

このガイドで使用する用語規則:

• 課金プログラムとリンク プログラム: Google Play 以外でのデジタル コンテンツ の購入やアプリのダウンロードを促進するプログラム。これには、 代替の課金システムと外部コンテンツプログラムが含まれます。
• 外部取引 API: 対象となる 課金プログラムとリンク プログラムの取引を報告するために使用される API。
• 外部取引: 代替の課金システムと外部コンテンツ プログラムで定義されている、アプリ外で行われる対象取引。
• 外部取引トークン: ユーザーが外部取引を開始したときに使用するために、Play Billing Library を介して提供されるトークン。このトークンを使用して、承認された外部取引を Google Play に通知します。
• 外部取引 ID: 外部取引を識別するためにデベロッパーが生成した固有識別子。

新しい外部取引を Google Play に報告する

externaltransactions API と統合して、サポートされている国の Google Play の課金システム以外で行われる取引を報告します（無料トライアルでの購入による 0 ドルの取引やアプリのインストールを含む）。代替の課金システムと 外部コンテンツ プログラムの規定に従い、要件を満たすユーザーの国でのみ課金プログラムとリンク プログラムのトランザクションを開始して報告する必要があり、それ以外の場合、API 呼び出しは失敗します。これは、新規購入、更新、チャージ、アップグレード、ダウングレード、アプリのダウンロードなどを含め、すべての取引が該当します。

外部トランザクション レポート

課金プログラムとリンク プログラムで支払いが承認された後、externaltransactions API を呼び出して外部取引を報告する必要があります。 これは、初回の請求、更新、払い戻しなどを含め、すべての取引に適用されます。報告要件については、それぞれの課金プログラムとリンク プログラムのガイドラインをご覧ください。

各外部取引は、外部取引 ID とともに報告されます。定期的な購入（自動更新可能な定期購入など）については、払い戻しを含め、後続の取引のパラメータとして、定期的な購入の最初の取引に関連付けられている外部取引 ID を送信する必要があります。これにより、その購入の一連の取引が記録されます。商品が変更されたとき（アップグレードやダウングレードなど）、または定期的な取引がキャンセルまたは期限切れになり同じ商品が後で再度購入されたときは、購入の新しい外部取引 ID を送信します。この外部取引 ID に個人情報、専有情報、機密情報を含めないでください。

最初の取引を報告する

課金プログラムとリンク プログラムで新しい購入またはアプリのダウンロードが承認されるたびに、externaltransactions API を呼び出す必要があります。

Google Play Billing Library を介してアプリが受け取る externalTransactionToken は、アプリのダウンロード、一回だけの購入、定期的な購入（定期購入など）の最初の取引のリクエスト本文の一部として必要になります。これは最初の取引と呼ばれます。 初期取引の後は、新しい一意の externalTransactionId を指定して後続の取引（定期購入の更新など）を報告します。詳しくは、 購入に対する後続の取引を報告するをご覧ください。

例:

1. デベロッパーがアプリで代替の課金システムを設定して有効にします。
2. ユーザー 1 はサポート対象国である韓国に住んでおり、1 か月無料トライアル付きで、product1 を月額 12,634.10 KRW で購入しようとしています。
3. アプリは product1 の ProductDetails とユーザーが選択した特典の購入フローを開始します。
4. ユーザー 1 がデベロッパーの代替の課金システムを選択します。
5. UserChoiceBillingListener が値 my_token を externalTransactionToken として受け取ります。
6. 次に、デベロッパーがバックエンドに関連情報を送信します（externalTransactionToken 値と購入する商品）。さらに、代替の課金システムで product1 の購入フローを開始します。この取引に、Google Play への報告に使用されるデベロッパー側での一意の取引 ID（ 123-456-789）が割り当てられます。ユーザーが無料トライアルを利用している場合でも、取引 ID は必須です。
7. 購入の取引が代替の課金システムで行われた後、デベロッパーが以下のリクエストで 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"
 }
}

最初の取引を報告する際は、次の点に注意してください。

• subscriptionType には、RECURRING（自動更新の定期購入の場合）または PREPAID（前払いの定期購入の場合）を指定できます。
• OtherRecurringProduct は、複数回のお支払いまたは後払いが必要な 1 回だけの購入を表すために使用する必要があります。たとえば、予約の場合、予約が完了したときに、SKU の価格で 2 回目のトランザクションが行われる前に、最初のトランザクションが 0 ドルになることがあります。後続の取引を報告する方法の詳細については、購入に対する後続の 取引を報告するをご覧ください。
• 最初の外部提案取引を報告する場合は、ExternalOfferDetails を指定する必要があります。後続の取引では 必要ありません。

インド在住のユーザーとの取引で、税額が 行政区域（州や県など）によって異なる場合は、その地域を 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"
 }
}

外部提案

報告する取引が外部提案プログラムの対象となる場合は、取引が一回だけの取引であるか、定期的に繰り返される取引のうちで最初に行った取引であるかに応じて、externalOfferDetails フィールドを設定する必要があります。

• アプリのダウンロード取引を報告する場合は、linkType を LINK_TO_APP_DOWNLOAD に設定し、installedAppPackage と installedAppCategory に適切な値を指定します。詳しくは、 アプリのダウンロードを報告するをご覧ください。
• デジタル コンテンツの提案取引を報告する場合は、linkType を LINK_TO_DIGITAL_CONTENT_OFFER に設定します。
• 外部提案プログラムを通じて外部アプリがインストールされたら、その外部アプリで行われた取引を報告する必要があります。これらの取引を報告する際は、元のアプリのダウンロード イベントにリンクします。
  • アプリのダウンロード イベントから externalTransactionToken を指定します。
  • externalOfferDetails フィールドで、appDownloadEventExternalTransactionId をアプリのダウンロード イベントの externalTransactionId に設定します。externalOfferDetails の他のフィールドは必須ではありません。

外部提案を通じてダウンロードされた外部アプリでの取引のリクエスト例:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "990000", # 0.99 EUR
   "currency" : "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros" : "90000", # 0.09 EUR
   "currency" : "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode" : "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
 }
}

さまざまな取引タイプに関する Google Play サービス手数料の最新情報については、 欧州 経済領域（EEA）のユーザー向け外部提案プログラムの変更をご覧ください。

購入に対する後続の取引を報告する

同じ外部購入に複数のユーザー支払いが関連付けられていることがあります（定期購入の更新やプリペイド プランのチャージなど）。後続の取引は Externaltransactions の同じ API を使用して報告できます。新規購入の報告で説明したように、後続の取引で externalTransactionToken は必要ありません。代わりに、更新またはチャージの取引ごとに、新しい一意の externalTransactionId がクエリ パラメータとして送信されます（initialExternalTransactionId フィールドに初期取引の ID を指定します）。

前の例に続く:

1. ユーザー 1 の初回の更新が代替の課金システムで行われます。最初の取引 ID は 123-456-789 でした。
2. デベロッパーは、URL のクエリ パラメータで、その回の取引を新しい取引の外部取引 ID として報告し、initialExternalTransactionId フィールドの初期取引の外部取引 ID を参照します。

リクエスト例:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "12634000000", # 12634 KRW
   "currency" : "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros" : "1263000000", # 1263 KRW
   "currency" : "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId" : "123-456-789",

   "externalSubscription" : {
     "subscriptionType" : "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode" : "KR"
 }
}

アップグレードまたはダウングレードを報告する

ユーザーが代替の課金システムで定期購入を所有しているときにアップグレードまたはダウングレードを報告するには、Externaltransactions API の同じエンドポイントと関数を使用し、アップグレード取引またはダウングレード取引に関してアプリに提供された externalTransactionToken を送信します。これは、新規購入の報告と同様に機能します 。

アプリのダウンロードを報告する

外部提案の課金システムでアプリのインストールを報告するには、 Externaltransactions.createexternaltransaction を呼び出し、アプリに提供された externalTransactionToken を送信する必要があります。これは、 費用がゼロの一回だけの取引として報告します。このプロセスは、 最初の取引を報告する場合と似ています。リクエスト本文に ExternalOfferDetails を含めるようにしてください。

リクエスト例:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
 "originalTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_token",
 },
 "userTaxAddress" : {
   "regionCode" : "US"
 },
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

代替の課金システムの取引の手動レポートから移行する

自動レポートを使用しない代替の課金システムの提供中に開始され、現在も有効な定期購入を移行するには、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 パートナー プログラムの要件

Google Play メディア エクスペリエンス プログラムなどのパートナー プログラムに参加しているデベロッパーは、外部 取引を報告する際に transaction_program_codeを指定する必要があります。対象となるデベロッパーの場合は、このフィールドの設定方法についてビジネス開発マネージャーにお問い合わせください。

購入の払い戻しを 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 ではAPI 割り当てが すべての呼び出しに適用されます。

また、Externaltransactions API には、Externaltransactions.createexternaltransaction または Externaltransactions.refundexternaltransaction の呼び出しに 1,200 QPM（Queries Per Minute: 1 分あたりのクエリ数）の上限が適用されます。Externaltransactions.getexternaltransaction の呼び出しは、この 1,200 QPM の上限にはカウントされません。