API für stornierte Käufe

Die Google Play Voided Purchases API bietet eine Liste von Bestellungen, die mit Käufen verknüpft sind, die ein Nutzer storniert hat. Anhand der Informationen in dieser Liste können Sie ein Annullierungssystem implementieren, das verhindert, dass der Nutzer auf Produkte aus diesen Bestellungen zugreift.

Diese API gilt für einmalige In-App-Bestellungen und App-Abos.

Ein Kauf kann auf folgende Arten storniert werden:

• Der Nutzer beantragt eine Erstattung für seine Bestellung.
• Der Nutzer storniert seine Bestellung.
• Eine Bestellung wird zurückgebucht.

• Der Entwickler storniert oder erstattet die Bestellung.

  Hinweis :In der API für ungültige Käufe werden nur widerrufene Bestellungen angezeigt. Wenn ein Entwickler einen Kauf erstattet, ohne die Option zum Widerrufen festzulegen, wird die Bestellung nicht von der API zurückgegeben.

• Google storniert oder erstattet die Bestellung.

Wenn Sie diese API verwenden, tragen Sie dazu bei, dass alle Nutzer Ihrer App, insbesondere wenn es sich um ein Spiel handelt, ein ausgewogeneres und faireres Erlebnis haben.

Hinweis :Im Gegensatz zu anderen auftragsbezogenen Datenquellen enthält die Voided Purchases API auch Käufe, die von Zahlungsabwicklern zurückgebucht werden. Daher kann es zu Abweichungen zwischen den Informationen aus dieser API und Informationen aus anderen bestellbezogenen Datenquellen kommen.

Hinweis :Die Voided Purchases API gibt stornierte Käufe nur zurück, wenn sie widerrufen werden müssen. Entwickler können diese API als Hinweis darauf verwenden, wann sie zusätzliche Maßnahmen ergreifen müssen. Einige Käufe werden jedoch möglicherweise erstattet, weil der Kauf vom Entwickler nie bestätigt wurde und daher möglicherweise nicht in den Aufzeichnungen des Entwicklers vorhanden ist.

Zugriff erhalten

Wenn Sie die API für stornierte Käufe verwenden möchten, benötigen Sie die Berechtigung zum Ansehen von Finanzinformationen. Sie stellen die Autorisierung über einen OAuth-Client oder ein Dienstkonto bereit. Wenn Sie ein Dienstkonto verwenden, aktivieren Sie in diesem Konto die Berechtigung „Finanzberichte ansehen“.

Weitere Informationen zum autorisierten Zugriff auf Google Play Developer APIs finden Sie in den folgenden Anleitungen:

• API-Zugriff-Clients einrichten
• Nutzer von Entwicklerkonten hinzufügen und Berechtigungen verwalten

Stornierte Käufe ansehen

Verwenden Sie die Methode GET, um eine Liste der stornierten Käufe anzufordern. Geben Sie in Ihrer Anfrage den vollständig qualifizierten Paketnamen Ihrer App an, z. B. com.google.android.apps.maps, sowie das Autorisierungstoken, das Sie beim Zugriff auf die API erhalten haben.

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

Sie können auch die folgenden optionalen Parameter in Ihre Anfrage aufnehmen:

startTime

Die Zeit in Millisekunden seit der Unixzeit der ältesten stornierten Transaktion, die in der Antwort angezeigt werden soll. Standardmäßig ist startTime auf „Vor 30 Tagen“ festgelegt.

Über die API können nur stornierte Käufe angezeigt werden, die in den letzten 30 Tagen erfolgt sind. Ältere stornierte Käufe sind nicht in der Antwort enthalten, unabhängig vom Wert, den Sie für startTime angegeben haben.

Hinweis:Die stornierten Käufe in der Antwort werden basierend auf dem Zeitpunkt gefiltert, zu dem ein bestimmter Datensatz von der API als storniert angesehen wird, nicht anhand des in der Antwort zurückgegebenen Werts von voidedTimeMillis.

endTime

Die Zeit in Millisekunden seit der Unixzeit der neuesten stornierten Käufe, die in der Antwort angezeigt werden sollen. Standardmäßig ist endTime auf die aktuelle Zeit eingestellt.

Hinweis:Die stornierten Käufe in der Antwort werden basierend auf dem Zeitpunkt gefiltert, zu dem ein bestimmter Datensatz von der API als storniert angesehen wird, nicht anhand des in der Antwort zurückgegebenen Werts von voidedTimeMillis.

maxResults

Die maximale Anzahl der stornierten Käufe, die in jeder Antwort angezeigt werden. Standardmäßig ist dieser Wert 1.000. Der Höchstwert für diesen Parameter ist ebenfalls 1.000.

Token

Ein Fortsetzungstoken aus einer vorherigen Antwort, mit dem Sie weitere Ergebnisse aufrufen können.

Typ

Der Typ der stornierten Käufe, die in jeder Antwort angezeigt werden. Wenn der Wert auf 0 gesetzt ist, werden nur ungültige In-App-Käufe zurückgegeben. Wenn der Wert auf 1 gesetzt ist, werden sowohl ungültige In-App-Käufe als auch ungültige Abokäufe zurückgegeben. Der Standardwert ist 0.

Hinweis:Bevor Sie den Erhalt von stornierten Abokäufen anfordern, müssen Sie in der Antwort zur eindeutigen Identifizierung von Einmalkäufen und Abos auf die Verwendung von orderId umstellen. Andernfalls erhalten Sie mehrere Abo-Bestellungen mit demselben PurchaseToken.

includeQuantityBasedPartialRefund

Gibt an, ob stornierte Käufe von mengenbasierten Teilerstattungen berücksichtigt werden sollen. Diese sind nur für Käufe in variabler Stückzahl anwendbar. Wenn true, können zusätzliche stornierte Käufe mit voidedQuantity zurückgegeben werden, was die Erstattungsmenge einer mengenbasierten Teilerstattung angibt. Der Standardwert ist false.

Hinweis:Wenn die verbleibende Gesamtmenge eines Kaufs erstattet wird, hat der entsprechende stornierte Kauf keinen voidedQuantity. Das ist ein Signal dafür, dass der Kauf vollständig erstattet wurde. Wenn beispielsweise ein Kauf mit einer Menge von 10 Artikeln dreimal mit den Mengen 2, 3 und 5 erstattet wird, gibt es 3 ungültige Käufe. Die ersten beiden stornierten Käufe haben eine voidedQuantity von 2 und 3, während der dritte stornierte Kauf keine voidedQuantity hat.

Die Antwort ist ein JSON-String mit einer Liste der stornierten Käufe. Wenn es mehr Ergebnisse als die im Anfrageparameter maxResults angegebene Anzahl gibt, enthält die Antwort einen nextPageToken-Wert, den Sie in eine nachfolgende Anfrage einfügen können, um weitere Ergebnisse aufzurufen. Das erste Ergebnis in der Liste ist der älteste stornierte Kauf.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

Kontingente

Für die Voided Purchases API gelten die folgenden Kontingente pro Paket:

• 6.000 Abfragen pro Tag. Der Tag beginnt und endet um Mitternacht (Pacific Time).
• 30 Anfragen in einem beliebigen Zeitraum von 30 Sekunden.

Richtlinien für Erstanfragen

Bei Ihrer ersten API-Anfrage sollten Sie möglicherweise alle verfügbaren Daten für Ihre App abrufen. Obwohl dies unwahrscheinlich ist, könnte dadurch Ihr Tageskontingent erschöpft werden. Wenn Sie Daten zu stornierten Käufen auf sicherere und konsistentere Weise abrufen möchten, sollten Sie die folgenden Best Practices beachten:

• Verwenden Sie den Standardwert für den Parameter maxResults. Wenn Sie Ihr gesamtes Abfragekontingent für einen Tag nutzen, können Sie so die Details von 6.000.000 ungültigen Käufen abrufen.
• Wenn eine Antwort einen Wert für nextPageToken enthält, weisen Sie diesen Wert dem Parameter token bei Ihrer nächsten Anfrage zu.

Best Practices

Hinweis :Entwickler sollten nicht nur diese API verwenden, sondern auch Entwicklerbenachrichtigungen in Echtzeit (Real-time developer notifications, RTDN) einbinden. Mit RTDN erhältst du Benachrichtigungen von Google, wenn sich die Berechtigung eines Nutzers in deiner App ändert, z. B. wenn ein Nutzer einen Kauf rückgängig macht.

Wenn Sie diese API in Ihrer App verwenden, denken Sie daran, dass es viele Gründe für eine Stornierung gibt und es keine Patentlösung für alle Fälle gibt. Wichtig ist, dass du deine Widerrufsrichtlinien und ‑strategien immer mit Blick auf deine Nutzer entwickelst. Dazu können Sie die folgenden Best Practices anwenden:

• Verwenden Sie diese API als eines von vielen Elementen in einer umfassenden Strategie, um unerwünschtes Verhalten zu bekämpfen. Der Widerruf des Zugriffs auf In-App-Produkte ist in der Regel effektiver, wenn er mit einer App kombiniert wird, die angemessene Preise für In-App-Käufe, ein App-Design, das unerwünschtes Verhalten verhindert, eine starke Nutzerbasis, deren Kultur solches Verhalten ablehnt, und reaktionsschnelle und effiziente Nutzer-Supportkanäle bietet.
• Wenden Sie Ihre Widerrufsrichtlinie einheitlich an, um allen Nutzern gegenüber fair zu sein.
• Wenn Sie unerwünschtes Verhalten angehen möchten, sollten Sie eine stufenweise Richtlinie erstellen. Beginnen Sie beispielsweise mit In-App-Warnungen bei ersten Verstößen und eskalieren Sie Ihre Reaktionen, wenn das unerwünschte Verhalten eines Nutzers anhält. Als letzte Möglichkeit können Sie verhindern, dass ein Nutzer überhaupt mit Ihrer App interagiert.
• Wenn Sie eine Widerrufsrichtlinie einführen und jedes Mal, wenn Sie sie aktualisieren, sollten Sie die Kommunikationskanäle Ihrer App nutzen, um Ihre Nutzer über die Änderungen zu informieren. Geben Sie Ihren Nutzern Zeit, sich mit diesen Änderungen vertraut zu machen, bevor sie in Ihrer App in Kraft treten.
• Seien Sie transparent gegenüber Ihren Nutzern und informieren Sie sie, wenn Sie Maßnahmen ergreifen, z. B. wenn Sie ihren Zugriff auf ein In‑App-Produkt widerrufen. Idealerweise sollten Nutzer in der Lage sein, Ihre Entscheidungen anzufechten, und solche Anfechtungen sollten fair behandelt werden.
• Behalten Sie Feedbackformulare und Communityforen im Blick, um zu verstehen, was Nutzer zu unerwünschtem Verhalten veranlasst und wie sie dieses Verhalten ausüben. Nutzen Sie diese Erkenntnisse als erste Verteidigungslinie.