Die Google Play Developer API enthält jetzt zusätzliche Funktionen zum Melden von Transaktionen aus einem System für alternative Abrechnungen oder externe Angebote. In diesem Leitfaden wird beschrieben, wie Transaktionen über alternative Abrechnungen oder externe Angebote gemeldet werden.
Es gibt einige Komponenten, die möglicherweise erforderlich sind, um die In-App-Käufe über Ihr Back-End zu verarbeiten. Dazu musst du deine Back-End-Integration einrichten, wie unter Google Play Developer API konfigurieren beschrieben. Für alle Entwickler-Back-End-Funktionen, die nicht spezifisch für APIs zur alternativen Abrechnung oder für externe Angebote sind, gilt die Anleitung in der Dokumentation zum Google Play-Abrechnungssystem.
Neue externe Transaktionen an Google Play melden
Durch die Einbindung von Externaltransactions APIs kannst du Transaktionen melden, die außerhalb des Abrechnungssystems von Google Play in unterstützten Ländern stattfinden, einschließlich Transaktionen für 0 $, die aus kostenlosen Testkäufen resultieren. Transaktionen über alternative Abrechnungssysteme oder externe Angebotssysteme dürfen nur für berechtigte Nutzerländer gestartet und gemeldet werden, soweit dies im Rahmen des Programms für alternative Abrechnung oder externe Angebote zulässig ist. Andernfalls wird der API-Aufruf abgelehnt. Dies gilt für alle Transaktionen, einschließlich neuer Käufe, Verlängerungen, Aufladenen, Upgrades, Downgrades usw.
Externe Transaktionsberichte
Du solltest die Externaltransactions API aufrufen, um eine externe Transaktion zu melden, nachdem die Zahlung über das alternative Abrechnungssystem oder externe Angebotssystem autorisiert wurde. Dies gilt für alle Transaktionen, einschließlich Einstiegsgebühren, Verlängerungen, Erstattungen und mehr. Alle Transaktionen müssen innerhalb von 24 Stunden nach der Transaktion gemeldet werden.
Jede externe Transaktion wird mit einer externen Transaktions-ID gemeldet. Bei wiederkehrenden Käufen (z. B. automatisch verlängerbare Abos) musst du die externe Transaktions-ID, die der ersten Transaktion im wiederkehrenden Kauf zugeordnet ist, als Parameter für alle nachfolgenden Transaktionen, einschließlich Erstattungen, senden. Dadurch wird die Reihe von Transaktionen für diesen Kauf aufgezeichnet. Sie senden eine neue externe Transaktions-ID für Käufe, wenn sich das Produkt ändert (z. B. ein Upgrade oder ein Downgrade) oder wenn die wiederkehrende Transaktion abgebrochen oder abgelaufen ist und dasselbe Produkt später noch einmal gekauft wird. Sie dürfen keine personenidentifizierbaren Informationen sowie proprietäre oder vertrauliche Informationen als Teil dieser externen Transaktions-ID angeben.
Neuen Kauf melden
Bei jedem neuen Kauf im System für die alternative Abrechnung oder für externe Angebote ist ein Aufruf der Externaltransactions API erforderlich. Für diese neuen Käufe musst du eine eindeutige
externalTransactionId, die mit dem Kauf in deinem Back-End verknüpft ist, als Abfrageparameter angeben. Dieser externalTransactionId kann nicht innerhalb der Paket-ID derselben App wiederverwendet werden.
Das externalTransactionToken, das die App über den UserChoiceBillingListener-, AlternativeBillingOnlyReportingDetailsListener- oder ExternalOfferReportingDetailsListener-Callback erhält, ist auch als Teil des Anfragetexts für einmalige Käufe und Ersttransaktionen in einem wiederkehrenden Kauf (z. B. einem Abo) erforderlich. In beiden Fällen wird dies als erste Transaktion bezeichnet. Nach der ersten Transaktion ist die externalTransactionToken nicht mehr erforderlich. Nachfolgende Transaktionen (z. B. Aboverlängerungen) werden durch Angabe einer neuen eindeutigen externalTransactionId gemeldet. Weitere Informationen zum Melden nachfolgender Transaktionen 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/Monat mit einem einmonatigen kostenlosen Testzeitraum zu kaufen. - Die App startet den Kaufvorgang mit dem
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 entsprechenden Informationen an sein Backend (
externalTransactionToken-Wert und gekaufte Produkte). Anschließend startet er den Kaufvorgang fürproduct1im alternativen Abrechnungssystem. Dieser Transaktion wird auf Entwicklerseite eine eindeutige Transaktions-ID zugewiesen, über die sie an Google Play gemeldet wird: 123-456-789. Die Transaktions-ID ist erforderlich, obwohl der Nutzer eine kostenlose Testversion erhält. - Nachdem die Kauftransaktion im alternativen Abrechnungssystem erfolgt ist, meldet der Entwickler die Transaktion mit der folgenden Anfrage an Google Play. Anfänglich wird sie als Transaktion von null Dollar gemeldet, da der Nutzer einen Monat kostenlos 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"
}
}
Wenn Transaktionen mit einem Nutzer mit Wohnsitz in Indien erfolgen und die Steuern von seinem Verwaltungsgebiet (z. B. Bundesstaat oder Provinz) variieren, müssen Sie dieses Gebiet unter userTaxAddress angeben. Informationen zu den jeweiligen Verwaltungsgebieten finden Sie in der vordefinierten Liste von Strings 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"
}
}
Nachfolgende Transaktionen für einen Kauf melden
In einigen Fällen ist mit demselben externen Kauf mehr als eine Nutzerzahlung verbunden (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 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 ersten Transaktion ist im Feld initialExternalTransactionId enthalten.
Ausgehend vom vorherigen 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 ersten 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 besitzt, verwenden Sie denselben Endpunkt und dieselbe Funktion in der Externaltransactions API und senden die externalTransactionToken, die für die Upgrade- oder Downgrade-Transaktion an die Anwendung bereitgestellt wurde. Dies funktioniert ähnlich wie die Berichterstellung für einen neuen Kauf.
Von der manuellen Berichterstellung für Transaktionen im alternativen Abrechnungssystem migrieren
Wenn Sie aktive Abos migrieren möchten, die gestartet wurden, während Sie eine alternative Abrechnung ohne automatisierte Berichterstellung angeboten haben, erstellen Sie mit dem Feld migratedTransactionProgram eine neue kostenlose Transaktion, anstatt initialExternalTransactionId oder externalTransactionToken anzugeben. Lege für transactionTime den Zeitpunkt fest, zu dem sich der Nutzer ursprünglich für jedes aktive Abo registriert hat. Melde dann jede nachfolgende Transaktion für diese Abos wie gewohnt über die APIs und gib die initialExternalTransactionId an, die oben zum Erstellen der Verlängerungstransaktionen verwendet wurde.
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 beim Migrieren von Abos die geltenden Kontingentlimits, damit 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 Erhöhung des Kontingents an.
Das Feld migratedTransactionProgram kann nur bei der Migration von der manuellen Berichterstellung verwendet werden. 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"
}
}
Erstattungen für Käufe bei Google Play melden
Binde die Externaltransactions API ein, um Transaktionen zu melden, die Nutzern außerhalb des Abrechnungssystems von Google Play erstattet wurden. Damit Play korrekt erkennen kann, welche Transaktion erstattet wurde, 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 den externalTransactionId für die konkrete Wiederholung des Abos an, das erstattet wird.
Beispiel: Ein Abo umfasst folgende 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: einen für die erste Transaktion und zwei für die nachfolgenden Transaktionen.
Diese Methode akzeptiert sowohl vollständige Erstattungen (bei denen der Betrag dem Betrag entspricht, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat) und Teilerstattungen (bei denen der Betrag kleiner ist als der Betrag, den der Nutzer bei der ursprünglichen externen Transaktion bezahlt hat). Bei teilweisen Erstattungen musst du den Betrag vor Steuern angeben, der erstattet wurde.
API-Kontingente
Für die Externaltransactions API gelten für alle Aufrufe tägliche API-Kontingente, wie für alle anderen Endpunkte in der Google Play Developer API.
Darüber hinaus hat die Externaltransactions API ein Limit von 1.200 Abfragen pro Minute (Queries Per Minute, QPM) für Aufrufe von Externaltransactions.createexternaltransaction oder Externaltransactions.refundexternaltransaction. Externaltransactions.getexternaltransaction-Aufrufe werden nicht auf dieses Limit von 1.200 Abfragen pro Minute angerechnet.