API für stornierte Käufe

Die Google Play Voided Purchases API stellt eine Liste von Bestellungen zur Verfügung, die mit Käufen verknüpft sind, die ein Nutzer für ungültig erklärt hat. Sie können Informationen aus dieser Liste verwenden, um ein Sperrsystem zu implementieren, das den Nutzer daran hindert, auf Produkte aus diesen Bestellungen zuzugreifen.

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

So können Sie einen Kauf für ungültig erklären:

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

  • Der Entwickler storniert oder erstattet die Bestellung.

  • Google storniert oder erstattet die Bestellung.

Mit dieser API sorgen Sie für eine ausgewogenere und fairere Nutzererfahrung für alle Nutzer Ihrer App, insbesondere wenn es sich bei Ihrer App um ein Spiel handelt.

Zugang erhalten

Zur Verwendung der Voided Purchases API benötigst du die Berechtigung zum Aufrufen von Finanzdaten. Die Autorisierung erfolgt über einen OAuth-Client oder ein Dienstkonto. Wenn du ein Dienstkonto verwendest, aktiviere die Berechtigung „Finanzberichte aufrufen“ in diesem Konto.

Weitere Informationen dazu, wie du autorisierten Zugriff auf Google Play Developer APIs erhältst, findest du in den folgenden Leitfäden:

Anzeigen stornierter Käufe

Fordern Sie mit der Methode GET eine Liste der stornierten Käufe an. Geben Sie in der Anfrage den voll qualifizierten Paketnamen für Ihre Anwendung (z. B. com.google.android.apps.maps) sowie das Autorisierungstoken an, das Sie beim Erhalten des Zugriffs 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 Ihrer Anfrage auch die folgenden optionalen Parameter hinzufügen:

startTime

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

Die API kann nur ungültige Käufe anzeigen, die in den letzten 30 Tagen erfolgt sind. Ältere stornierte Käufe sind nicht in der Antwort enthalten, unabhängig von dem Wert, den du für startTime angegeben hast.

endTime

Die Zeit in Millisekunden seit der Unixzeit des letzten stornierten Kaufs, den Sie in der Antwort sehen möchten. Standardmäßig ist endTime auf die aktuelle Uhrzeit eingestellt.

maxResults
Die maximale Anzahl an ungültigen Käufen, die in jeder Antwort angezeigt werden. Der Standardwert ist 1.000. Beachten Sie, dass der Maximalwert für diesen Parameter ebenfalls 1.000 ist.
Token
Ein Fortsetzungs-Token aus einer vorherigen Antwort, mit dem Sie weitere Ergebnisse ansehen können.
Typ

Der Typ der annullierten Käufe, die in den einzelnen Antworten angezeigt werden. Wenn der Wert auf 0 gesetzt ist, werden nur stornierte In-App-Käufe zurückgegeben. Wenn der Wert auf „1“ gesetzt ist, werden sowohl stornierte In-App-Käufe als auch stornierte Abokäufe zurückgegeben. Der Standardwert ist 0.

includeQuantityBasedPartialRefund

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

Die Antwort ist ein JSON-String, der eine Liste mit ungültigen Käufen enthält. Wenn die Anzahl der Ergebnisse die im Anfrageparameter maxResults angegebene Zahl überschreitet, enthält die Antwort den Wert nextPageToken, den Sie an eine nachfolgende Anfrage übergeben können, um weitere Ergebnisse anzusehen. Das erste Ergebnis in der Liste zeigt den ältesten stornierten 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

Die Voided Purchases API legt die folgenden Kontingente pro Paket fest:

  • 6.000 Abfragen pro Tag. (Ein Tag beginnt und endet um Mitternacht Pacific Time.)
  • 30 Abfragen innerhalb von 30 Sekunden

Richtlinien für erste Anträge

Bei der ersten API-Anfrage möchten Sie möglicherweise alle verfügbaren Daten für Ihre Anwendung abrufen. Dieser Vorgang kann zwar unwahrscheinlich sein, aber Ihr Tageskontingent möglicherweise erschöpfen. Halten Sie sich an die folgenden Best Practices, um stornierte Kaufdaten sicherer und einheitlicher abzurufen:

  • Verwenden Sie den Standardwert für den Parameter maxResults. Auf diese Weise können Sie, wenn Sie Ihr gesamtes Abfragekontingent für einen Tag nutzen, 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 bei Ihrer nächsten Anfrage dem Parameter token zu.

Best Practices

Wenn Sie diese API in Ihrer App verwenden, denken Sie daran, dass es viele Gründe gibt, einen Kauf zu stornieren, und dass es keine Lösung gibt, die in allen Fällen funktioniert. Sie sollten Ihre Nutzer beim Entwerfen Ihrer Widerrufsrichtlinien und -strategien im Hinterkopf behalten. Dazu können Sie die folgenden empfohlenen Vorgehensweisen anwenden:

  • Verwenden Sie diese API als eines von vielen Elementen in einer umfassenden Strategie, um mit unerwünschtem Verhalten umzugehen. Der Zugriff auf In-App-Produkte zu widerrufen ist in der Regel effektiver, wenn sie mit einer App kombiniert wird, die angemessene Preise für In-App-Käufe hat, einem App-Design, das unerwünschtes Verhalten abschreckt, einer starken Nutzerbasis, deren Kultur ein solches Verhalten ablehnt, und mit reaktionsschnellen und effizienten Nutzersupportkanälen.
  • Verwalten Sie Ihre Widerrufsrichtlinie einheitlich, um Fairness für alle Nutzer zu gewährleisten.
  • Wenn du mit unerwünschtem Verhalten umgehst, kannst du eine gestaffelte Richtlinie erstellen. Beginnen Sie beispielsweise mit In-App-Warnungen bei Vorabverstößen und eskalieren Sie Ihre Antworten, wenn sich das unerwünschte Verhalten eines Nutzers nicht wiederholt. Als letzte Möglichkeit können Sie auch verhindern, dass ein Nutzer mit Ihrer Anwendung interagiert.
  • Wenn Sie eine Sperrrichtlinie einführen und sie jedes Mal aktualisieren, sollten Sie die Nutzer über die Kanäle zur Kontaktaufnahme Ihrer App über die Änderungen informieren. Gib deinen Nutzern Zeit, diese Änderungen klar zu verstehen, bevor sie in deiner App wirksam werden.
  • Seien Sie gegenüber Ihren Nutzern transparent und informieren Sie sie, wenn Sie Maßnahmen ergreifen, z. B. den Zugriff auf ein In-App-Produkt widerrufen. Idealerweise sollten Nutzer in der Lage sein, Ihre Entscheidungen anzufechten, und solche Streitigkeiten sollten fair behandelt werden.
  • Überwachen Sie Feedbackformulare und Community-Foren, um zu verstehen, was Nutzer zu unerwünschtem Verhalten veranlasst und wie sie ein solches Verhalten durchführen. Nutzen Sie diese Erkenntnisse als erste Verteidigungslinie.