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 を呼び出す必要があります。

また、UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener、BillingProgramReportingDetailsListener のいずれかのコールバックを通じてアプリが受け取る externalTransactionToken は、アプリのダウンロード、一回だけの購入、定期的な購入（定期購入など）の最初の取引のリクエスト本文の一部としても必要になります。これは初回取引と呼ばれます。初期取引の後は、新しい一意の externalTransactionId を指定して後続の取引（定期購入の更新など）を報告します。後続の取引を報告する方法の詳細については、購入に対する後続の取引を報告するをご覧ください。

例:

1. デベロッパーがアプリで代替の課金システムを設定して有効にします。
2. サポートされている国である韓国のユーザー 1 が、product1 を月額 12,634.10 韓国ウォンで、1 か月間の無料トライアル特典付きで購入しようとしています。
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 回限りの購入を表すために使用する必要があります。たとえば、予約購入では、最初に $0 の取引が行われ、予約購入が完了した時点で SKU の価格で 2 回目の取引が行われることがあります。後続の取引を報告する方法の詳細については、購入に対する後続の取引を報告するをご覧ください。
• 初回外部提案取引を報告する際は、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"
 }
}

外部提案

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

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

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

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "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",
   "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 を送信します。これは、新規購入の報告と同様に機能します。

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

外部提案の課金システムでアプリのインストールを報告するには、Externaltransactions.createexternaltransaction を呼び出し、アプリに提供された externalTransactionToken を送信する必要があります。これをゼロコストの 1 回限りの取引として報告します。このプロセスは、初回取引の報告と似ています。リクエスト本文に 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 の上限にはカウントされません。