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

Die Google Play Developer API bietet zusätzliche Funktionen zum Melden von Transaktionen aus Abrechnungs- und Linkprogrammen. In diesem Leitfaden wird beschrieben, wie Sie Transaktionen aus diesen Abrechnungsprogrammen melden.

Es gibt einige Komponenten, die möglicherweise erforderlich sind, um externe Transaktionen über Ihr Backend abzuwickeln. Dazu müssen Sie die Backend-Integration wie unter Google Play Developer API konfigurieren beschrieben einrichten. Informationen zum Erstellen von Entwickler-Backend-Funktionen, die nicht speziell für die Abrechnung und Linkprogramme vorgesehen sind, finden Sie unter Abrechnungssystem von Google Play.

Glossar

In diesem Leitfaden verwendete Begriffskonventionen:

• Abrechnungs- und Linkprogramme: Programme, die den Kauf digitaler Inhalte oder den Download von Apps außerhalb von Google Play ermöglichen. Dazu gehören die Programme zur alternativen Abrechnung und für externe Angebote.
• APIs für externe Transaktionen: APIs, die zum Melden von Transaktionen für berechtigte Abrechnungs- und Link-Programme verwendet werden.
• Externe Transaktion: Eine berechtigte Transaktion, die außerhalb der App erfolgt, wie in den Programmanforderungen definiert. Dazu gehören Käufe digitaler Inhalte und App-Downloads.
• Token für externe Transaktionen: Ein Token, das über die Play-Abrechnungsbibliothek bereitgestellt wird und das Sie verwenden können, wenn der Nutzer eine externe Transaktion abschließt. Dieses Token wird verwendet, um Google Play über eine erfolgreiche externe Transaktion zu informieren.
• Externe Transaktions-ID: Eine eindeutige Kennung, die von Ihnen generiert wird, um eine externe Transaktion zu identifizieren.

Neue externe Transaktionen bei Google Play melden

Binden Sie die externaltransactions API ein, um Transaktionen, die außerhalb des Abrechnungssystems von Google Play erfolgen, in unterstützten Ländern zu melden, einschließlich Transaktionen im Wert von 0 $, die aus Käufen von kostenlosen Probeabos und App-Installationen resultieren. Sie sollten Transaktionen in Abrechnungs- und Linkprogrammen nur für infrage kommende Nutzerländer starten und melden, sofern dies gemäß den Richtlinien zur alternativen Abrechnung oder zu externen Angeboten zulässig ist. Andernfalls wird der API-Aufruf abgelehnt. Das gilt für alle Transaktionen, einschließlich neuer Käufe, Verlängerungen, Aufladungen, Upgrades, Downgrades und App-Downloads.

Berichterstellung zu externen Transaktionen

Sie sollten die externaltransactions API aufrufen, um eine externe Transaktion zu melden, nachdem eine Zahlung über ein Abrechnungs- und Linkprogramm autorisiert wurde. Dies gilt für alle Transaktionen, einschließlich Erstbelastungen, Verlängerungen, Erstattungen und andere. Informationen zu den Berichtsanforderungen finden Sie in den Richtlinien für das jeweilige Abrechnungs- und Linkprogramm.

Jede externe Transaktion wird mit einer externen Transaktions-ID gemeldet. Bei wiederkehrenden Käufen (z. B. Abos mit automatischer Verlängerung) müssen Sie die externe Transaktions-ID, die mit der ersten Transaktion des wiederkehrenden Kaufs verknüpft ist, als Parameter für alle nachfolgenden Transaktionen, einschließlich Erstattungen, senden. Hier wird die Reihe von Transaktionen für diesen Kauf aufgezeichnet. Sie sollten eine neue externe Transaktions-ID 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 personenidentifizierbaren, geschützten oder vertraulichen Informationen in diese externe Transaktions-ID aufnehmen.

Erste Transaktion melden

Jedes Mal, wenn ein neuer Kauf oder App-Download in Abrechnungs- und Linkprogrammen erfolgreich ist, müssen Sie die externaltransactions API aufrufen.

Die externalTransactionToken, die die App über die Callbacks UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener oder BillingProgramReportingDetailsListener empfängt, ist als Teil des Anfragetexts für App-Downloads, Einmalkäufe und Ersttransaktionen bei einem wiederkehrenden Kauf (z. B. ein Abo) erforderlich. Dies wird als Eröffnungstransaktion bezeichnet. Nach der ersten Transaktion müssen Sie nachfolgende Transaktionen (z. B. Aboverlängerungen) mit einer neuen eindeutigen externalTransactionId melden. Weitere Informationen zum Melden nachfolgender Transaktionen 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 einmonatigen kostenlosen Testabo zu kaufen.
3. Die App startet den Kaufvorgang mit der ProductDetails für product1 und dem Angebot, das der Nutzer ausgewählt hat.
4. Nutzer 1 wählt das alternative Abrechnungssystem des Entwicklers aus.
5. Die 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 wird der Kaufvorgang für product1 im alternativen Abrechnungssystem gestartet. Dieser Transaktion wird auf Entwicklerseite eine eindeutige Transaktions-ID zugewiesen, die verwendet wird, um sie bei Google Play zu melden: 123-456-789. Die Transaktions-ID ist erforderlich, auch wenn der Nutzer ein 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 anfangs als Transaktion mit einem Betrag 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, für die mehrere Zahlungen oder eine verzögerte Zahlung erforderlich sind. Bei einer Vorbestellung kann es beispielsweise eine erste Transaktion über 0 $und dann eine zweite Transaktion zu einem späteren Zeitpunkt zum Preis der Artikelnummer geben, 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 Transaktionen für das erste externe Angebot melden. Dies ist für nachfolgende Transaktionen nicht erforderlich.

Wenn Sie mit einem Nutzer in Indien Geschäfte abschließen und die Steuer von seinem Verwaltungsgebiet (z. B. einem Bundesstaat oder einer Provinz) abhängt, geben Sie dieses Gebiet unter userTaxAddress an. Eine Liste der anwendbaren Verwaltungseinheiten finden Sie in der vordefinierten Liste von Strings in der API-Referenz.

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 App-Download-Transaktionen 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 digitale Inhalte melden, legen Sie linkType auf LINK_TO_DIGITAL_CONTENT 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 werden. Verknüpfen Sie diese Transaktionen beim Melden mit dem ursprünglichen App-Download-Ereignis:
  • Geben Sie die externalTransactionToken aus dem App-Download-Ereignis an.
  • Legen Sie im Feld externalOfferDetails appDownloadEventExternalTransactionId auf die externalTransactionId des Ereignisses für den App-Download 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": "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"
 }
}

Die aktualisierten Details zur Google 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 ist mehr als eine Nutzerzahlung mit demselben externen Kauf verknüpft, z. B. bei 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 die externalTransactionToken für nachfolgende Transaktionen nicht erforderlich. Stattdessen wird für jede Verlängerungs- oder Aufladetransaktion eine neue eindeutige externalTransactionId als Abfrageparameter gesendet. Die ID der ursprünglichen Transaktion ist im Feld initialExternalTransactionId enthalten.

Im Anschluss an das vorherige Beispiel:

1. Die erste Verlängerung von Nutzer 1 erfolgt über das alternative Abrechnungssystem. Die ursprüngliche Transaktions-ID lautete 123-456-789.
2. Der Entwickler meldet das Wiederholen der Transaktion im URL-Abfrageparameter als externe Transaktions-ID für diese neue Transaktion und verweist im Feld initialExternalTransactionId auf die externe Transaktions-ID der ursprünglichen Transaktion.

Beispielanfrage:

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

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 die externalTransactionToken, die der App für die Upgrade- oder Downgrade-Transaktion bereitgestellt wurde. Das 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 die externalTransactionToken senden, die der App bereitgestellt wurde. Melden Sie dies als einmalige Transaktion kostenlos. Dieser Vorgang ähnelt dem Melden einer Erstabwicklung. Achten Sie darauf, ExternalOfferDetails in den Anfragetext einzufügen.

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 Berichterstellung von Transaktionen mit alternativer Abrechnung migrieren

Wenn Sie aktive Abos migrieren möchten, die gestartet wurden, während Sie eine alternative Abrechnung ohne automatisiertes Melden angeboten haben, erstellen Sie eine neue Transaktion kostenlos mit dem Feld migratedTransactionProgram, anstatt initialExternalTransactionId oder externalTransactionToken anzugeben. Setzen Sie die transactionTime auf den Zeitpunkt, zu dem sich der Nutzer ursprünglich für jedes aktive Abo registriert hat. Melden Sie danach jede nachfolgende Transaktion für diese Abos wie gewohnt über die APIs und geben Sie die initialExternalTransactionId an, die Sie zuvor zum Erstellen der Verlängerungstransaktionen verwendet haben. Nach der Migration des Abos 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.

Achten Sie beim Migrieren von Abos auf 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 Kontingenterhöhung an.

Das Feld migratedTransactionProgram kann nur bei der Migration von manuellen Berichten verwendet werden. Er wird eingestellt, wenn die manuelle Berichterstellung 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 die transaction_program_code angeben, wenn sie externe Transaktionen melden. Wenn Sie ein berechtigter Entwickler sind, wenden Sie sich an Ihren Business Development Manager, um weitere Informationen zum Festlegen dieses Felds zu erhalten.

Erstattungen für Käufe bei Google Play melden

Binden Sie die externaltransactions API ein, um Transaktionen zu melden, die Nutzern außerhalb des Abrechnungssystems von Google Play erstattet wurden. Damit Play die erstattete Transaktion richtig identifizieren kann, müssen Sie die entsprechende externalTransactionId für die zuvor gemeldete Transaktion als Teil der URL-Parameter angeben.

Wenn du Erstattungen von Abokäufen meldest, verweise auf die externalTransactionId der jeweiligen Wiederholung 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 für alle Transaktionen für das Abo melden möchten, müssen Sie drei separate Erstattungsanträge stellen: einen für die ursprüngliche Transaktion und zwei für die nachfolgenden Transaktionen.

Bei dieser Methode sind sowohl vollständige Erstattungen (bei denen der Betrag dem Betrag entspricht, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) als auch Teilerstattungen (bei denen der Betrag geringer ist als der Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) möglich. Bei teilweisen Erstattungen müssen Sie den erstatteten Betrag vor Steuern angeben.

API-Kontingente

Für die Externaltransactions API gelten API-Kontingente für alle Aufrufe, 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 (Queries Per Minute, QPM) für Aufrufe von Externaltransactions.createexternaltransaction oder Externaltransactions.refundexternaltransaction. Aufrufe von Externaltransactions.getexternaltransaction werden nicht auf dieses Limit von 1.200 QPM angerechnet.