Die Google Play Developer API enthält zusätzliche Funktionen zum Melden von Transaktionen aus Abrechnungs- und Verknüpfungsprogrammen. In diesem Leitfaden wird beschrieben, wie Sie Transaktionen aus diesen Abrechnungsprogrammen melden.
Es gibt einige Komponenten, die möglicherweise erforderlich sind, um externe Transaktionen von Ihrem Backend zu verarbeiten. Dazu müssen Sie Ihre Backend-Integration wie unter Google Play Developer API konfigurieren beschrieben einrichten. Informationen zum Erstellen von Entwickler-Backend-Funktionen, die nicht spezifisch für die Abrechnung und die Verknüpfung von Programmen sind, findest du unter Abrechnungssystem von Google Play.
Glossar
In diesem Leitfaden verwendete Begriffe:
- Abrechnungs- und Linkprogramme: Programme, die den Kauf digitaler Inhalte oder das Herunterladen von Apps außerhalb von Google Play ermöglichen. Dazu gehören die Programme für die alternative Abrechnung und für externe Inhalte.
- APIs für externe Transaktionen: APIs, die verwendet werden, um Transaktionen für berechtigte Abrechnungs- und Linkprogramme zu melden.
- Externe Transaktion: Eine gültige Transaktion, die außerhalb der App erfolgt und die Anforderungen des Programms für alternative Abrechnungssysteme und des Programms für 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.
- ID für externe Transaktion: Eine eindeutige Kennung, die von Ihnen generiert wird, um eine externe Transaktion zu identifizieren.
Play Console-Berechtigungen konfigurieren
Wenn Sie die externaltransactions API aufrufen möchten, um externe Transaktionen zu melden oder zu erstatten, weisen Sie Ihrem Dienstkonto in der Google Play Console die Berechtigung Bestellungen und Abos verwalten zu. Sie können diese Berechtigung auf Kontoebene oder für bestimmte Apps gewähren.
Eine Anleitung zum Erstellen eines Dienstkontos und zum Gewähren von Berechtigungen in der Play Console finden Sie unter Dienstkonto verwenden. Weitere Informationen zu Play Console-Berechtigungen finden Sie unter Nutzer von Entwicklerkonten hinzufügen und Berechtigungen verwalten.
Neue externe Transaktionen an Google Play melden
Binde die externaltransactions API ein, um Transaktionen zu melden, die außerhalb des Abrechnungssystems von Google Play in unterstützten Ländern stattfinden, einschließlich Transaktionen über 0 $, die aus Käufen von kostenlosen Probeabos und App-Installationen resultieren. Sie sollten Transaktionen im Rahmen von Abrechnungs- und Linkprogrammen nur für Länder mit berechtigten Nutzern starten und melden, wie es im Rahmen der Programme zur alternativen Abrechnung und für externe Inhalte zulässig ist. Andernfalls wird der API-Aufruf abgelehnt. Eingeschlossen sind sämtliche Transaktionen für Neukäufe, Verlängerungen, Aufladungen, Upgrades, Downgrades und App-Downloads.
Externe Transaktionsberichte
Du solltest 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 Erstgebühren, Verlängerungen, Erstattungen und Sonstiges. Die Meldeanforderungen finden Sie in den Richtlinien für das jeweilige Abrechnungs- und Linkprogramm.
Jede externe Transaktion wird mit einer ID für externe Transaktionen gemeldet. Bei wiederkehrenden Käufen (z. B. Abos mit automatischer Verlängerung) musst du die ID der externen Transaktion, die mit der ersten Transaktion des wiederkehrenden Kaufs verknüpft ist, als Parameter für alle nachfolgenden Transaktionen senden, einschließlich Erstattungen. Dadurch wird die Reihe von Transaktionen für diesen Kauf aufgezeichnet. Du solltest eine neue externe Transaktions-ID für Käufe senden, wenn sich das Produkt ändert (z. B. ein Upgrade oder Downgrade) oder wenn die wiederkehrende Transaktion gekündigt wurde oder abgelaufen ist und dasselbe Produkt später noch einmal gekauft wird. Diese externe Transaktions-ID darf keine personenidentifizierbaren, proprietären oder vertraulichen Informationen enthalten.
Erste Transaktion melden
Jedes Mal, wenn ein neuer Kauf oder App-Download in Abrechnungs- und Linkprogrammen autorisiert wird, musst du die externaltransactions API aufrufen.
Der externalTransactionToken, den die App über die Google Play Billing Library erhält, ist im Anfragetext 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 müssen Sie nachfolgende Transaktionen (z. B. Aboverlängerungen) mit einer neuen eindeutigen externalTransactionId melden. Weitere Informationen finden Sie unter Nachfolgende Transaktionen für einen Kauf melden.
Beispiel:
- Ein Entwickler konfiguriert und aktiviert die alternative Abrechnung in seiner App.
- Nutzer 1 befindet sich in Südkorea, einem unterstützten Land, und versucht,
product1für 12.634, 10 KRW pro Monat mit einem einmonatigen kostenlosen Testzeitraum zu kaufen. - Die App startet den Kaufvorgang mit der
ProductDetailsfürproduct1und dem Angebot, das der Nutzer ausgewählt hat. - Nutzer 1 wählt das alternative Abrechnungssystem des Entwicklers aus.
- Der
UserChoiceBillingListenererhält den Wertmy_tokenalsexternalTransactionToken. - Der Entwickler sendet dann die relevanten Informationen an sein Backend (
externalTransactionToken-Wert und gekaufte Produkte). Anschließend wird der Kaufvorgang fürproduct1im alternativen Abrechnungssystem gestartet. Dieser Transaktion wird auf Entwicklerseite eine eindeutige Transaktions-ID zugewiesen, die für die Meldung an Google Play verwendet wird: 123-456-789. Die Transaktions-ID ist erforderlich, auch wenn der Nutzer einen kostenlosen Testzeitraum erhält. - 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 anfänglich als Transaktion mit einem Wert von null Dollar 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:
subscriptionTypekannRECURRING(für Abos mit automatischer Verlängerung) oderPREPAID(für Prepaid-Abos) sein.OtherRecurringProductmuss für einmalige Käufe verwendet werden, die mehrere Zahlungen oder eine verzögerte Zahlung erfordern. Bei einer Vorbestellung kann beispielsweise eine erste Transaktion über 0 € erfolgen, gefolgt von einer zweiten Transaktion zu einem späteren Zeitpunkt zum Preis der SKU, 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
ExternalOfferDetailsangeben, wenn Sie erste Transaktionen für externe Angebote melden. Für nachfolgende Transaktionen ist dies nicht erforderlich.
Wenn du eine Transaktion mit einem Nutzer in Indien durchführst, bei dem die Steuer von seinem Verwaltungsgebiet (z. B. einem Bundesstaat oder einer Provinz) abhängt, gib dieses Gebiet unter userTaxAddress an. Eine Liste der vordefinierten Strings für die Verwaltungsgebiete finden Sie im API-Referenzhandbuch.
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 für
linkTypeden WertLINK_TO_APP_DOWNLOADfest und geben Sie die entsprechenden Werte fürinstalledAppPackageundinstalledAppCategoryan. Weitere Informationen finden Sie unter App-Download melden. - Wenn Sie Transaktionen für Angebote mit digitalen Inhalten melden, legen Sie für
linkTypeden WertLINK_TO_DIGITAL_CONTENT_OFFERfest. - 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
externalTransactionTokenaus dem App-Download-Ereignis an. - Legen Sie im Feld
externalOfferDetailsden WertappDownloadEventExternalTransactionIdauf dieexternalTransactionIddes App-Download-Ereignisses fest. Andere Felder inexternalOfferDetailssind nicht erforderlich.
- Geben Sie die
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 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 sind mehrere Nutzerzahlungen 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 Aufladungstransaktion eine neue eindeutige externalTransactionId als Suchparameter gesendet, wobei die ID der ursprünglichen Transaktion im Feld initialExternalTransactionId enthalten ist.
Beispiel:
- Die erste Verlängerung von Nutzer 1 erfolgt über das alternative Abrechnungssystem. Die ursprüngliche Transaktions-ID war 123-456-789.
- Der Entwickler meldet die Transaktionswiederholung im URL-Suchparameter als externe Transaktions-ID für diese neue Transaktion und verweist im Feld
initialExternalTransactionIdauf 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", # 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 du ein Upgrade oder Downgrade melden möchtest, während der Nutzer ein Abo im alternativen Abrechnungssystem hat, verwende denselben Endpunkt und dieselbe Funktion in der Externaltransactions API und sende 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 kostenlose, einmalige Transaktion. Dieser Vorgang ähnelt dem Melden einer ersten Transaktion. Geben Sie im Anfragetext ExternalOfferDetails an.
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 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 kostenlose Transaktion mit dem Feld migratedTransactionProgram, anstatt initialExternalTransactionId oder externalTransactionToken anzugeben. Setze transactionTime auf den Zeitpunkt, zu dem sich der Nutzer ursprünglich für das jeweilige aktive Abo registriert hat. Melden Sie danach jede nachfolgende Transaktion für diese Abos wie gewohnt über die APIs und geben Sie dabei 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.
Beachten Sie bei der Migration von Abos die geltenden Kontingentlimits, um sicherzustellen, dass die Migration nicht 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 verwendet werden, wenn Sie von der manuellen Berichterstellung migrieren. Sie 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 du ein berechtigter Entwickler bist, wende dich an deinen Business Development Manager, um weitere Informationen zum Festlegen dieses Felds zu erhalten.
Erstattungen für Käufe 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 die erstattete Transaktion korrekt identifizieren kann, müssen Sie die entsprechende externalTransactionId für die zuvor gemeldete Transaktion als Teil der URL-Parameter angeben.
Wenn du Erstattungen für Abokäufe meldest, gib die externalTransactionId der jeweiligen Wiederholung des Abos an, für die die Erstattung erfolgt.
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 du eine Erstattung aller Transaktionen für das Abo melden möchtest, musst du drei separate Erstattungsanfragen stellen: eine für die erste Transaktion und zwei für die nachfolgenden Transaktionen.
Diese Methode akzeptiert sowohl volle Erstattungen (der Betrag entspricht dem Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) als auch teilweise Erstattungen (der Betrag ist kleiner als der Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat). Bei teilweisen Erstattungen müssen Sie den erstatteten Betrag vor Steuern angeben.
API-Kontingente
Für die Externaltransactions API gelten wie für alle anderen Endpunkte in der Google Play Developer API API-Kontingente für alle Aufrufe.
Darüber hinaus gilt für die Externaltransactions API ein Limit von 1.200 Abfragen pro Minute für Aufrufe von Externaltransactions.createexternaltransaction oder Externaltransactions.refundexternaltransaction. Aufrufe von Externaltransactions.getexternaltransaction werden nicht auf dieses Limit von 1.200 QPM angerechnet.