Leitfaden zur Back-End-Integration für die Monetarisierung außerhalb von Google Play Billing

Die Google Play Developer API enthält zusätzliche Funktionen zum Melden von Transaktionen aus Abrechnungs- und Link-Programmen. In dieser Anleitung wird beschrieben, wie Sie Transaktionen aus diesen Abrechnungsprogrammen melden.

Es gibt einige Komponenten, die möglicherweise erforderlich sind, um externe Transaktionen von Ihrem Backend aus zu verarbeiten. Um sie zu erstellen, müssen Sie Ihre Backend Integration wie unter Google Play Developer API konfigurieren beschrieben einrichten. Informationen zum Erstellen von Backend-Funktionen für Entwickler, die nicht spezifisch für Abrechnungs- und Link Programme sind, finden Sie unter Abrechnungssystem von Google Play.

Glossar

In dieser Anleitung werden folgende Begriffe verwendet:

  • Abrechnungs- und Link-Programme: Programme, die den Kauf digitaler Inhalte oder App-Downloads außerhalb von Google Play ermöglichen. Dazu gehören die Programme für alternative Abrechnung und externe Inhalte.
  • APIs für externe Transaktionen: APIs, die zum Melden von Transaktionen für berechtigte Abrechnungs- und Link-Programme verwendet werden.
  • Externe Transaktion: Eine gültige Transaktion, die außerhalb der App erfolgt und die Anforderungen der Programme für alternative Abrechnung und externe Inhalte erfüllt.
  • Token für externe Transaktionen: Ein Token, das über die Play Billing Library zur Verfügung gestellt wird und das Sie verwenden können, wenn der Nutzer eine externe Transaktion initiiert. Mit diesem Token wird Google Play über eine autorisierte externe Transaktion informiert.
  • Externe Transaktions-ID: Eine eindeutige Kennung, die von Ihnen generiert wird, um eine externe Transaktion zu identifizieren.

Neue externe Transaktionen an Google Play melden

Integrieren Sie die externaltransactions API, um Transaktionen zu melden, die außerhalb des Abrechnungssystems von Google Play in unterstützten Ländern stattfinden, einschließlich Transaktionen mit einem Wert von 0 $, die aus Käufen von kostenlosen Probeabos und App-Installationen resultieren. Sie sollten Transaktionen für Abrechnungs- und Link Programme nur für berechtigte Nutzerländer starten und melden, wie im Rahmen der Programme für alternative Abrechnung und externe Inhalte zulässig. Andernfalls wird der API Aufruf abgelehnt. Eingeschlossen sind sämtliche Transaktionen für Neukäufe, Verlängerungen, Aufladungen, Upgrades, Downgrades und App-Downloads.

Meldung externer Transaktionen

Sie sollten die externaltransactions API aufrufen, um eine externe Transaktion zu melden, nachdem eine Zahlung über ein Abrechnungs- und Link-Programm autorisiert wurde. Eingeschlossen sind sämtliche Transaktionen, einschließlich Erstbelastungen, Verlängerungen, Erstattungen und Sonstiges. Die Anforderungen für die Meldung finden Sie in den Richtlinien für das jeweilige Abrechnungs- und Link-Programm.

Jede externe Transaktion wird mit einer ID für externe Transaktionen gemeldet. Bei wiederkehrenden Käufen (z. B. Abos mit automatischer Verlängerung) müssen Sie die ID für externe Transaktionen, die mit der ersten Transaktion im wiederkehrenden Kauf verknüpft ist, als Parameter für alle nachfolgenden Transaktionen, einschließlich Erstattungen, senden. Dadurch wird die Reihe von Transaktionen für diesen Kauf erfasst. Sie sollten eine neue ID für externe Transaktionen für Käufe senden, wenn sich das Produkt ändert (z. B. bei einem Upgrade oder Downgrade) oder wenn die wiederkehrende Transaktion storniert oder abgelaufen ist und dasselbe Produkt später noch einmal gekauft wird. Sie dürfen keine personenbezogenen, geschützten oder vertraulichen Informationen als Teil dieser externen Transaktions-ID angeben.

Erste Transaktion melden

Jedes Mal, wenn ein neuer Kauf oder App-Download in Abrechnungs- und Link Programmen autorisiert wird, müssen Sie die externaltransactions API aufrufen.

Das externalTransactionToken, das die App über die Google Play Billing Library erhält, ist als Teil des Anfragetexts für App-Downloads, einmalige Käufe und erstmalige Transaktionen bei einem wiederkehrenden Kauf (z. B. einem Abo) erforderlich. Dies wird als erste Transaktion bezeichnet. Nach der ersten Transaktion melden Sie nachfolgende Transaktionen (z. B. Aboverlängerungen), indem Sie eine neue eindeutige externalTransactionId angeben. Weitere Informationen finden Sie unter Nachfolgende Transaktionen für einen Kauf melden.

Beispiel:

  1. Ein Entwickler konfiguriert und aktiviert die alternative Abrechnung in seiner App.
  2. Nutzer 1 befindet sich in Südkorea, einem unterstützten Land, und versucht, product1 für 12.634, 10 KRW pro Monat mit einem Angebot für einen kostenlosen Testzeitraum zu kaufen.
  3. Die App startet den Kaufvorgang mit den ProductDetails für product1 und dem vom Nutzer ausgewählten Angebot.
  4. Nutzer 1 wählt das alternative Abrechnungssystem des Entwicklers aus.
  5. Der UserChoiceBillingListener erhält den Wert my_token als externalTransactionToken.
  6. Der Entwickler sendet dann die relevanten Informationen an sein Backend (externalTransactionToken-Wert und gekaufte Produkte). Anschließend startet er den Kaufvorgang für product1 im alternativen Abrechnungssystem. Dieser Transaktion wird auf Entwicklerseite eine eindeutige Transaktions-ID zugewiesen, die verwendet wird, um sie an Google Play zu melden: 123-456-789. Die Transaktions-ID ist erforderlich, auch wenn der Nutzer ein kostenloses Probeabo erhält.
  7. Nachdem die Transaktion für den Kauf im alternativen Abrechnungssystem erfolgt ist, meldet der Entwickler die Transaktion mit der folgenden Anfrage an Google Play. Sie wird zunächst als Transaktion mit einem Wert von 0 $ gemeldet, da der Nutzer einen kostenlosen Monat erhält.
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"
 }
}

Beachten Sie beim Melden einer ersten Transaktion Folgendes:

  • subscriptionType kann RECURRING (für Abos mit automatischer Verlängerung) oder PREPAID (für Prepaid-Abos) sein.
  • OtherRecurringProduct muss für einmalige Käufe verwendet werden, die mehrere Zahlungen oder eine verzögerte Zahlung erfordern. Bei einer Vorbestellung kann beispielsweise eine erste Transaktion mit einem Wert von 0 $ erfolgen, gefolgt von einer zweiten Transaktion zu einem späteren Zeitpunkt zum Preis der Artikelnummer, wenn die Vorbestellung ausgeführt wird. Weitere Informationen zum Melden nachfolgender Transaktionen finden Sie unter Nachfolgende Transaktionen für einen Kauf melden.
  • Sie müssen ExternalOfferDetails angeben, wenn Sie erste Transaktionen für externe Angebote melden. Für nachfolgende Transaktionen ist dies nicht erforderlich .

Wenn Sie mit einem Nutzer in Indien Transaktionen durchführen, bei denen die Steuer von seinem Verwaltungsgebiet (z. B. Bundesstaat oder Provinz) abhängt, geben Sie dieses Gebiet unter userTaxAddress an. Eine Liste der zulässigen Verwaltungsgebiete finden Sie in der vordefinierten Liste von Strings in der API-Referenzanleitung.

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"
 }
}

Externe Angebote

Wenn die gemeldete Transaktion im Rahmen des Programms für externe Angebote erfolgt, müssen Sie das Feld externalOfferDetails festlegen, wenn es sich um eine einmalige Transaktion oder die erste Transaktion einer wiederkehrenden Reihe handelt:

  • Wenn Sie Transaktionen für App-Downloads melden, legen Sie linkType auf LINK_TO_APP_DOWNLOAD fest und geben Sie die entsprechenden Werte für installedAppPackage und installedAppCategory an. Weitere Informationen finden Sie unter App-Download melden.
  • Wenn Sie Transaktionen für Angebote für digitale Inhalte melden, legen Sie linkType auf LINK_TO_DIGITAL_CONTENT_OFFER fest.
  • Nachdem eine externe App über das Programm für externe Angebote installiert wurde, müssen Sie Transaktionen melden, die in der externen App ausgeführt wurden. Verknüpfen Sie diese Transaktionen beim Melden mit dem ursprünglichen App-Download-Ereignis:
    • Geben Sie das externalTransactionToken aus dem App-Download-Ereignis an.
    • Legen Sie im Feld externalOfferDetails für appDownloadEventExternalTransactionId die externalTransactionId des App-Download-Ereignisses fest. Andere Felder in externalOfferDetails sind nicht erforderlich.

Beispielanfrage für eine Transaktion in einer externen App, die über externe Angebote heruntergeladen wurde :

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"
 }
}

Die aktualisierten Details zur Play-Servicegebühr für verschiedene Transaktionstypen finden Sie unter Änderungen am Programm für externe Angebote für Nutzer im Europäischen Wirtschaftsraum (EWR).

Nachfolgende Transaktionen für einen Kauf melden

In einigen Fällen gibt es mehr als eine Nutzerzahlung, die mit demselben externen Kauf verknüpft ist, z. B. Aboverlängerungen oder Aufladungen von Prepaid-Tarifen. Sie können diese nachfolgenden Transaktionen mit derselben API in Externaltransactions melden. Wie unter Neuen Kauf melden beschrieben, ist das externalTransactionToken für nachfolgende Transaktionen nicht erforderlich. Stattdessen wird für jede Verlängerungs- oder Aufladungstransaktion eine neue eindeutige externalTransactionId als Abfrageparameter gesendet, wobei die ID der ersten Transaktion im Feld initialExternalTransactionId enthalten ist.

Fortsetzung des vorherigen Beispiels:

  1. Die erste Verlängerung von Nutzer 1 erfolgt im alternativen Abrechnungssystem. Die anfängliche Transaktions-ID war 123-456-789.
  2. Der Entwickler meldet die wiederkehrende Transaktion im URL-Suchparameter als Transaktions-ID für diese neue Transaktion und verweist im Feld initialExternalTransactionId auf die Transaktions-ID der ersten Transaktion.

Beispielanfrage:

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"
 }
}

Upgrade oder Downgrade melden

Wenn Sie ein Upgrade oder Downgrade melden möchten, wenn der Nutzer ein Abo im alternativen Abrechnungssystem hat, verwenden Sie denselben Endpunkt und dieselbe Funktion in der Externaltransactions API und senden das externalTransactionToken, das der App für die Upgrade- oder Downgrade-Transaktion zur Verfügung gestellt wurde. Dies funktioniert ähnlich wie das Melden eines neuen Kaufs.

App-Download melden

Wenn Sie eine App-Installation im Abrechnungssystem für externe Angebote melden möchten, müssen Sie Externaltransactions.createexternaltransaction aufrufen und das externalTransactionToken senden, das der App zur Verfügung gestellt wurde. Melden Sie dies als einmalige Transaktion ohne Aufpreis. Dieser Vorgang ähnelt dem Melden einer ersten Transaktion. Achten Sie darauf, ExternalOfferDetails in den Anfragetext aufzunehmen.

Beispielanfrage:

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"
 }
}

Von der manuellen Meldung von Transaktionen für die alternative Abrechnung migrieren

Wenn Sie aktive Abos migrieren möchten, die gestartet wurden, während Sie eine alternative Abrechnung ohne automatisierte Meldung angeboten haben, erstellen Sie eine neue kostenlose Transaktion und verwenden Sie das Feld migratedTransactionProgram, anstatt eine initialExternalTransactionId oder ein externalTransactionToken anzugeben. Legen Sie transactionTime auf den Zeitpunkt fest, zu dem sich der Nutzer ursprünglich für jedes aktive Abo registriert hat. Melden Sie anschließend jede nachfolgende Transaktion für diese Abos wie gewohnt über die APIs und geben Sie die initialExternalTransactionId an, die zuvor zum Erstellen der Verlängerungstransaktionen verwendet wurde. Sobald das Abo migriert wurde, müssen Sie die nachfolgenden Transaktionen für das Abo nicht mehr manuell melden, sofern sie über die auf dieser Seite beschriebenen automatisierten Methoden gemeldet werden.

Beachten Sie beim Migrieren von Abos die Kontingentlimits, um zu prüfen, ob die Migration zu einem Kontingentausfall führt. Wenn viele Abos migriert werden müssen, verteilen Sie sie auf mehrere Tage oder fordern Sie eine Erhöhung des Kontingents an.

Das Feld migratedTransactionProgram kann nur verwendet werden, wenn Sie von der manuellen Meldung migrieren. Es wird eingestellt, wenn die manuelle Meldung nicht mehr unterstützt wird.

Beispielanfrage:

# 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"
 }
}

Anforderungen für Play-Partnerprogramme

Entwickler, die an Partnerprogrammen wie dem Play Media Experience Program teilnehmen, müssen beim Melden externer Transaktionen den transaction_program_code angeben. Wenn Sie ein berechtigter Entwickler sind, wenden Sie sich an Ihren Business Development Manager, um weitere Informationen zum Festlegen dieses Felds zu erhalten.

Erstattungen von Käufen an Google Play melden

Integrieren Sie die externaltransactions API, um Transaktionen zu melden, die Nutzern außerhalb des Abrechnungssystems von Google Play erstattet wurden. Damit Google Play korrekt ermitteln kann, welche Transaktion erstattet wurde, sollten Sie die entsprechende externalTransactionId für die zuvor gemeldete Transaktion als Teil der URL-Parameter angeben.

Wenn Sie Erstattungen von Abokäufen melden, verweisen Sie auf die externalTransactionId der jeweiligen wiederkehrenden Transaktion des Abos, die erstattet wird.

Beispiel: Angenommen, ein Abo hat die folgenden Transaktionen:

  • Eine erste Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567

  • Die erste wiederkehrende Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567..0

  • Die zweite wiederkehrende Transaktion mit der externen Transaktions-ID ABC.1234-5678-9012-34567..1

Wenn Sie eine Erstattung aller Transaktionen für das Abo melden möchten, müssen Sie drei separate Erstattungsanfragen stellen: eine für die erste Transaktion und zwei für die nachfolgenden Transaktionen.

Diese Methode akzeptiert sowohl volle Erstattungen (bei denen der Betrag mit dem Betrag übereinstimmt, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) als auch teilweise Erstattungen (bei denen der Betrag geringer ist als der Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat). Bei teilweisen Erstattungen müssen Sie den Betrag vor Steuern angeben, der erstattet wurde.

API-Kontingente

Für die Externaltransactions API gelten für alle Aufrufe API-Kontingente, genau wie für jeden anderen Endpunkt in der Google Play Developer API.

Außerdem gilt für die Externaltransactions API ein Limit von 1.200 Abfragen pro Minute (QPM) für Aufrufe von Externaltransactions.createexternaltransaction oder Externaltransactions.refundexternaltransaction. Aufrufe von Externaltransactions.getexternaltransaction werden nicht auf dieses Limit von 1.200 Abfragen pro Minute angerechnet.